App-Scoped User IDs

Before May 1, 2018, Pages API endpoints relied on App-Scoped User IDs (ASID). Apps created before this date continued receiving ASIDs in endpoint responses, unless an app admin used the App Dashboard to opt-in to receive Page-Scoped User IDs (PSID). Starting with v7.0+, Pages API endpoints will only accept and return PSIDs for all apps, regardless of their creation date. This change will also be applied to all API versions on May 5th, 2021.

The Page-Scoped ID API allows you to map ASIDs to their PSID equivalents. The API is deprecated in v7.0+, but can be used with older versions until May 5th, 2021.

Page-Scoped User ID FAQs

App Scoped ID

Facebook issues App-Scoped User IDs, ASIDs, when people first login to an instance of an app. With ASIDs, the ID for the same user will be different between apps. This makes it harder for a user's data to be passed between apps, which helps protect people's information.

Page Scoped ID

Facebook issues Page-Scoped User IDs, PSIDs, if your app uses Pages API or Messenger APIs. With PSIDs, the ID for the same user will be different between pages. This makes it harder for a user's data to be mapped across pages which helps protect people's information.

If an app is making any Pages API calls, i.e. read/post/delete objects related to FB Pages, and the API deals with User IDs, i.e either takes User IDs as input or returns User IDs in responses, then those User IDs are going to change. Prior to May 1, 2018, they were App-Scoped IDs, ASIDs. Going forward they will be Page-Scoped IDs, PSIDs.

If your app used the Pages API and ASIDs before this date, you will need to migrate your ASIDs to PSIDs within 180 days of your App Review approval at which time your ASIDs will no longer work. Only after you have completed the migration will your app receive PSIDs instead of ASIDs.

To facilitate the ASID to PSID migration process, use the Page Scoped ID API. This API allows you to map an ASID and a page to a PSID. You can then prepare your systems to be able to support PSIDs. Once your migration is complete you can then enable PSIDs to be returned via the Pages API endpoints.

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 of the Settings > Advanced in your app's dashboard will display the number of days remaining for your app.

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. There was no way to connect the conversations across the two platforms as they used different IDs. However, when Pages API starts returning PSIDs, you will be able to connect a customer's interactions with the page across both Pages APIs and Messenger APIs unlocking additional messaging scenarios that are based on PSIDs.

This change also helps further protect people's information as it makes it more difficult for a user's data to be mapped across pages.

Any new apps created after May 1, 2018 will automatically get a PSID for Pages API. Any apps created prior to May 1, 2018, will continue to get ASID until they indicate via the app dashboard that they are ready to get PSID.

All apps using Pages API must resubmit for App Review. Once our review team reviews and approves your app, you have 180-days to migrate from ASID to PSID. At the end of 180 days, Pages API will start returning PSID instead of ASID.

Within the 180-day migration period an app can use the Page Scoped ID API to map existing ASIDs to PSIDs. Note that this mapping API you will not be able to access this API after the 180 day migration period.

If an app completes migration before the 180 days ends, it can be configured to switch to PSID immediately on the app dashboard toggle. Once switched to PSID, it will start receiving PSIDs immediately and you will lose access to the Page Scoped ID API.

After the 180-day period following App Review approval, ASIDs will no longer be accepted via the API and your app will start receiving PSIDs instead of ASIDs. You will no longer have access to the Page-Scoped ID API to migrate existing ASIDs to PSIDs. All PSID related options on your app's dashboard will be disabled.

If the 180 day grace period has passed (from the day the app was approved via app review) apps will no longer have access to the Page Scoped ID API.

If the app is still within the 180 day grace period (from the day the app was approved via app review), the Page Scoped ID API is still accessible up to 3 days after the app has been switched to PSID. An app will get the full 3 additional days as long as it is within the 180 day window. An app may get less than 3 days if it extends beyond the 180 day window.

No, the switch is final. Both manual and automatic ASID to PSID migrations are final after the migration is complete. Please verify the PSIDs work as expected on your test pages before switching to PSIDs.

Once your app is approved through App Review, you will have 180 days to migrate any ASIDs to PSIDs. A new button appears in your app dashboard that you use switch Pages API to return PSIDs if you complete migration with the 180 day window. If you take no action, the switch will occur automatically once the 180-day grace period ends.

No, with the exception of test pages you select, only ASIDs will work until you make the switch to PSIDs. You can select up to 5 test pages in the app dashboard to test PSIDs before you complete the migration and make the official switch. Note that you will not be able to edit or modify your list of 5 test pages and selected pages cannot be removed from the test list.

Yes, this is a per app setting that is automatically enabled when an app is approved for Pages permissions in App Review.

Yes, the PSID will remain unique for the user-page combination irrespective of which app retrieves it.

Yes, a PSID for a user on page will never be the same for a different user on a different page.

Yes, however this requires that you or your organization sign an additional contract. Submit a request to increase your quota.

Access to the Page Scoped ID API will be discontinued once you migrate to PSIDs. However, there is a short grace period, up to 3 days, after switching to PSIDs where you will still be able to use the PSID API to map any IDs you might have missed or fix any errors. This buffer if only available within the 180-day period after your app has been approved.

No, there is a separate rate limit that is based on how many IDs the app is allowed to map. When calling the mapping APIs, both the app level and page level rate limit will not be applied to the API, and the API will not be counted against either rate limits.

Error code 100 is returned when the quota allocated to your app is met. Every app has an allocated number of PSIDs they can translate that is calculated based on the pages the app manages and can vary per app. You will see this error when you reach that limit. If you map the same ASID to multiple PSIDs on different pages, it will be counted multiple times against the limit.