The Page-Scoped ID API is deprecated in v7.0+ and will be deprecated for all versions on May 5th, 2021.

Page-Scoped ID API

The Page-Scoped ID API allows you to get Page-scoped User IDs from App-scoped User IDs.

This API is only available to apps:

created before May 1st, 2018 and
have passed App Review

Overview

Prior to May 1, 2018, Pages API endpoints returned an App Scoped ID (ASID) for a user and Messenger API endpoints returned a Page Scoped ID (PSID) for a user. The different user IDs meant there was no way to connect conversations across the two platforms. As of May 1, 2018 , Pages API started using PSIDs which allows you to connect a customer's interactions with the page across both Pages and Messenger APIs.

Any apps created after May 1, 2018 are automatically assign PSIDs and no further action is required.

Any apps created before May 1, 2018 that used the Pages API and ASIDs will need to migrate existing ASIDs to PSIDs using the Page-Scoped ID API within 180 days of App Review approval.

How will I know when I need to migrate from ASIDs to PSIDs?

You will receive a dev alert when your app has been approved and can start the process of migration.

What do I need to do?

To migrate existing ASIDs to PSIDs use the Page Scoped ID API. This API maps an ASID and a page to a PSID and prepares your systems to support PSIDs. Once your migration is complete you can then enable PSIDs to be returned via the Pages API endpoints or the app dashboard.

In your app's dashboard under Settings > Advanced, a Pages API Migration section will appear. Click the Convert to PSIDs button to switch Pages API to return PSIDs once you gave migrated your existing ASIDs to PSIDs and prior to the 180-day deadline. The Pages API Migration will display the number of days remaining for you to switch your app to using PSIDs. Please note that after your app has been switched to return and accept PSIDs it can no longer accept ASIDs and the Page Scoped ID API to migrate ASIDs to PSIDs will no longer be accessible.

If you take no action, the switch to PSIDs will automatically occur at the end of the 180-day grace period.

Getting PSIDs from ASIDs

To get a Page-scoped ID from an App-scoped ID, send a POST request to the /pages_id_mapping root node and include the following parameters:

Parameters

Parameter	Value Type	Description
`access_token`	String	The targeted Page's access token. (To get a scoped User ID for a Page, your app must query the endpoint using that Page's access token.)
`appsecret_proof`	String	Your `appsecret_proof` hash. Refer to our Securing Requests document for more information.
`ignore_invalid_ids` (optional)	Boolean	Default is `false`. If set to `true`, invalid IDs will be ignored silently and omitted from the response. Otherwise, an error will be returned with a list of invalid IDs in the `error_data` property. ASIDs will be rejected if they are incomplete, belong to a different app, or if they are for non-ASID objects (e.g, a Post ID)
`user_ids`	String	A list of up to 200 App-scoped User IDs to be converted to equivalent Page-scoped IDs for the Page whose Page access token was used to make the request. Separate IDs by a comma (`,`).

Sample Requests & Responses

Sample Request

curl -i -X POST \
 -d "user_ids=10154673853349851,1001789542988" \
 -d "appsecret_proof=your-appsecret-proof" \
 -d "access_token=the-page-access-token" \
 "https://graph.facebook.com/v2.11/pages_id_mapping"

Sample Response

{
  "10154673853349851":
    {
      "id": "1535748669783931"
    },
  "1001789542988":
    {
      "id": "1061502733949241"
    }
}

Test Pages

To help with testing, you can designate up to 5 Pages as Test Pages. When using a Test Page with the Pages API, the API will return PSIDs instead of ASIDs.

To designate any Page you own as a Test Page, use the Pages API Migration section of your app's App Dashboard (Settings > Advanced > Pages API Migration).

Limits

API Availability

The Page-Scoped ID API will be available for 180 days from the date that your app passed App Review. The Pages API Migration section in your app's App Dashboard (Settings > Advanced > Pages API Migration) will display the number of days remaining for your app.

Rate Limits

Your app can convert up to 5M PSIDs, or 1% of the total number of fans across all of the Pages that your app manages, whichever value is smaller.

Error Codes

Error Code	Description
100	Current app exceeds rate limit
100	Invalid App-scoped User IDs for current App. Invalid IDs will be listed in the `error_data` property. This error will be ignored if you include the `ignore_invalid_ids=true` parameter and value in your request.
105	Number of `user_ids` exceeds the maximum limit of 200 ASIDs.
190	A Page access token is needed to call the API.
200	This App or Page is not allowed to use the Page-Scoped ID API.