Mapping Users Across Apps and Pages

Facebook issues app-scoped user IDs for people who first log into an instance of an app and for people who log in with Limited Login. for people who first use a Messenger bot, Facebook issues page-scoped user IDs . By definition, this means the ID for the same person may be different between these apps and bots.

A business may operate several Facebook Apps or bots - common in games studios, for example, to support use cases such as cross-promotion or fraud detection, or in bots used to communicate with users. In these cases, you may need to map the same person's ID between those apps and bots.

There are three methods by which you can map the same user across multiple apps:

• The token_for_business field on the User node
• The token_for_business property in the signed_request object passed to apps rendered inside a Facebook Canvas frame
• The ids_for_business edge on the User node

Before you can use any of these mechanisms, you first must let Facebook know that your apps are owned and operated by the same business entity. To do this you will need to use Facebook Business Manager to:

• create a new business, or
• associate your apps to an existing business.

The token_for_business field on the User node

Once an app has been associated with a Business Manager, you may request the token_for_business field on the User node, using the app-scoped ID obtained from Limited Login or the first login to an instance of an app. This call returns a string which is the same for this person across all the apps managed by the same Business Manager.

GET /me?fields=token_for_business

would yield:

{
  "id": "1234567890"
  "token_for_business": "weg23ro87gfewblwjef"
}

Usage notes:

• The person being queried must have logged into this app.
• This field can be called with an app access token, or a user access token. If using a user token, the person being queried must be the same person for whom the token was generated.
• If you use an app-soped ID obtained from Limited Login, you must use your app's app ID to make the call because you don't have a User token valid for Graph API calls. Be aware that Limited Login safeguards are not supported in this context.
• If the owning business changes, the value of token_for_business will also change.
• If you request the token_for_business field and the app is not associated with a Business Manager, the call returns an error.
• The value returned by token_for_business is a token, not an ID - it cannot be used directly against the Graph API to access a person's information. You should still store the ID in your database, and use this to call the Graph API to get that person's information.

For convenience, the token_for_business field is available in all API versions

The token_for_business property in the Canvas signed_request object

To make it simple for apps with a Canvas presence to map a user across multiple apps, if the app is associated with a Business Manager, and the user had logged into the app, a token_for_business field will be added and passed to the app via the signed_request passed to Canvas apps upon load. For example:

{
  "algorithm": "HMAC-SHA256",
  "expires": 1414263600,
  "issued_at": 1414257389,
  "oauth_token": "CAAGEkq9GMZAkBAFnvvQ3M6msZBKITLa1gVZBVdnLTdJue2QeV6fMKRXn4G6fcEZB5ZAJyg3z6HdaKOJCCMJ1l9YFWmN4hq6nNnx77f9O7SYhsnPcJ6iH79xjFwqhrALgieDp7GiziMy5Y3Mol6RzHvCM5ceqQe9ZAijvrWZB5hEIwphbMQKEwZA4ZBozXP3NJgEZA3nZCMTTtvleWpxfmqIqO5XwxneCZBsZC4",
  "token_for_business": "AbwoGqummPbF3zp_",
  "user_id": "10154418713995634"
}

The value of the token_for_business field will be the same as if queried on the User node directly, e.g. via /me?fields=token_for_business. It also follows the same rules, i.e. if the owning business changes, the value of token_for_business will also change.

If the app is not associated with a Business Manager, or the user has not logged into the app, the token_for_business property will not be present in the signed_request object.

The ids_for_business edge on the User node

Get mapped business IDs by calling the ids_for_business edge on the User node. The response is an array of objects, each of which represents an app which is associated with the same business as the calling app, which the person has also logged into.

GET /me/ids_for_business

Example Response:

{
  "data": [
    {
      "id": "10153949089790582", 
      "app": {
        "name": "Business's App 1", 
        "namespace": "business_app_1", 
        "id": "647733625268125"
      }
    }, 
    {
      "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"
      }
    }
  ]
}

For data to be returned by the API, the user must have logged into one or more apps which are associated with the same business as the app from which you're making the API call. Example: if a person has logged into 3 of 5 apps associated with the same business, the API will return 3 objects.

FAQs

Do I need to use the Business Mapping API?

No. The Business Mapping API is only useful for businesses who operate multiple Facebook Apps, and who need to map the same user's ID between them. If you have one primary app you are unlikely to need to use the Business Mapping API and thus do not need to set up a business or associate your apps with the business.

What is Business Manager?

Business Manager is a way to help businesses and agencies manage their Facebook Pages, ad accounts, apps and payment methods in one place. Read more about Business Manager.

I don't think I need to use the Business Mapping API but should I associate my apps with a business anyway?

If you don't need to use the Business Mapping API, we do not recommend setting up a business at this time. As a business needs to be linked with the primary Facebook Page for your business, the person who is best-placed to set up the business on Facebook is the person who usually manages facebook ad accounts and Page permissions for your company. If they have already setup your business within Business Manager, you are free to associate apps with that business.

Can I associate my app with multiple businesses?

No. An app can only be associated with one business at a time.

Can I transfer an app to another business?

Yes. First, you must remove the app from the business it's currently associated with. You can do this within Business Manager. Just go to the Applications tab within your business settings, select the app, and click "Remove". You can then associate the app with a new business.