The Page-Scoped ID API is deprecated in v7.0+ and will be deprecated for all versions on May 5th, 2021.
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:
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.
You will receive a dev alert when your app has been approved and can start the process of migration.
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.
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:
Parameter | Value Type | Description |
---|---|---|
| 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.) |
| String | Your |
| Boolean | Default is |
| 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 ( |
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"
{ "10154673853349851": { "id": "1535748669783931" }, "1001789542988": { "id": "1061502733949241" } }
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).
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.
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 Code | Description |
---|---|
100 | Current app exceeds rate limit |
100 | Invalid App-scoped User IDs for current App. Invalid IDs will be listed in the |
105 | Number of |
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. |