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

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