How use Facebook”Business Mapping API”, what is “app-scoped ID”?



I have written the article ‘How to use “Facebook Business Manager”‘ some months ago.
I have mentioned about “Business Mapping API” in that article.
This time, describe about it.

User ID have changed to “app-scoped ID” in api v2.0.

First of all, the specification about user ID have changed in api v2.0.

Facebook Platform Upgrade Guide

See “1. App-scoped User IDs” above.


What is “app-scoped ID”?

See below image, it explaining about “app-scoped ID”.

Actualy, both of “User ID” and “app-scoped ID” are just numbers.
There are no regularity.

So far we were able to get an same “User ID” from every app.
Now, we can get the “app-scoped-ID” that is different ID for each app later than api v2.0 was released.

Facebook may not want to give the information that can identify the user personal.

When was it changed to “app-scoped ID”?

The “app-scoped ID” have released with api v2.0.
It’s scope is the app either created after April 30 2014 or created before that and have been migrated to v2.0.

All user ID have been “app-scoped ID” in your app created after April 30 2014.
In the app created before April 30 2014 and have been migrated to v2.0, the ID of a user log in first time after migration is “app-scoped ID”.
The ID of a user had logged in before migration is still “User ID”.
It means the ID of existing user isn’t change by “app-scoped ID”.

We can no longer identify users across the multiple apps because of “app-scoped ID” change.

This specification change doesn’t affect the app running alone.
But it have a problem in the case of using the user ID across the multiple apps.
We can no longer use the user ID across the multiple apps because of user id is different for each app later than api v2.0.


We had referred to the data by using “User ID” as key if identify the same user across the multiple apps or use multiple apps in one promotion.
But we can’t any more.

Can we identify the user by other information?

Is there nothing to be replaced “User ID”?
It may be used the “name” or “username”.
Username is the string of the url, like “[username]”.

Unfortunately, “name” isn’t unique of all Facebook users.
Many users have same “name”.
On the other hand, “username” is unique.
But it had been expired that the api for getting the “username” information in api v2.0.

April 30th, 2014 – API Version v2.0


So, we can’t use both.
The only thing we can use is “email”.

I think, Facebook really not want to give the information that can identify the user personal.
Someday it may be going to be prohibited by the policy.

We can still identify the user by “Business Mapping API”!

Don’t be sad, we can still identify the user across the multiple apps by using “Business Mapping API”.
It has been available in api v2.0.
Of course it can get only “app-scoped ID”, not “user ID”

You need to set the “Business Manager”

You need to set the “Business Manager”, and making the business account.


Please see below ,how to use “Facebook Business Manager” is.

How to use “Facebook Business Manager”

Please note that when you make the account of “Business Manager” you need a facebook page.
And the admin UI of the page that was set in “Business Manager” is changed.

Prepare for using “Business Mapping API”

All of the apps that are used across need to be registered in “Business Manager”.
If you have the admin role of each app, registration will finish immediately.
It will be waiting for approval if you have not the admin role.


Every app registered in “Business Manager” is grouped by “Business Account”.
The app registered can use “Business Mapping API”, if it is later than api v2.0.

How to use “Business Mapping API”

You can get the data by calling api “/me/ids_for_business”.
If you call this, you will get like below.

  "data": [
      "id": "10153949089790582",  /* App Scoped User ID */
      "app": {
        "name": "Business's App 1",   /* App name */
        "namespace": "business_app_1",   /* App namespase */
        "id": "647733625268125"  /* App ID */
      "id": "605665581", 
      "app": {
        "name": "Business's App 2", 
        "namespace": "business_app_2", 
        "id": "370612223054807"
      "id": "10154053730190582", 
      "app": {
        "name": "Business's App 3", 
        "namespace": "business_app_3", 
        "id": "194890427204075"

In this case, the app “Business’s App 1”, “Business’s App 2”, “Business’s App 3” are registered in same “Business Manager”.

Now you can find that user id:10153949089790582 in the “App 1” and user id:605665581 in the “App 2” and user id:10154053730190582 in the “App 1” are same user.
Note that these user id are “app-scoped ID”, not “User ID”.

Umm…it’s inconvenience.

If you create the app each time, app will continue more and more. (App 1,2,3,4,5…100!)
So, if you store these ids in database you need create column as many as the number of apps.
If the number of apps is constant, there is no problem.

“Business Mapping API” demonstration

There are some apps demo below.

  1. Tuesday ※API v1.0 →Demo
  2. Sunday ※API v2.0 →Demo
  3. Monday ※API v2.0 →Demo
  4. Wednesday ※API v2.1 →Demo

These apps are registered in same “Business Manager”.
If it works, you can get the user id of every app when you log in each app except api v1.0 “Tuesday” app.

★Note that the user using the demo needs to have logged in all apps.
You can’t test “Business Mapping API” before you have logged in all apps.

Example of calling “/me?fields=id” by api v1.0 app.

Demo is here


Since it is api v1.0, this id “100*********125” is my “User ID”(real user ID) .
In api v1.0, “Business Mapping API” returns error.

Example of calling “/me?fields=id” and “/me/ids_for_business” by api v2.0 app.

Demo is here


Next, calling “/me?fields=id” and “/me/ids_for_business” by api v2.0 app.
Since it is api v2.0, this id “752*********630” is “App Scoped User ID”.

In api v2.0, “Business Mapping API” returns some data.
You can see there is different ID for each app.
By the way, the ID of the “Sunday” app is same as ID of the v1.0 app above.
Why is it?

Example of calling “/me?fields=id” and “/me/ids_for_business” by api v2.0 app that had been logged in before.

Demo is here


In this app, this is is real user id.

If the app had been logged in before April 30 2014, user id is still “User ID” not “app-scoped ID”.
If the user logged in the app again after April 30 2014, it doesn’t change.

I had logged in the “Sunday” app before April 30 2014.
That’s why the id of the “Sunday” app same as the “Tuesday” app(api v1.0).

Example of api v2.1

Demo is here


Of course, it’s same as v2.0.

How about if the app is staging?

If you have the staging app in addition to production app, the user id is different for each.
It is problem.

For this case, you can use “Test Apps” and get the id from staging app same as production app.

I will write about this soon.