ID Matching API Reference

It is often the case that a person will interact with multiple apps and Pages you own. To allow you to identify a person consistently across every app and Page you own, the ID Matching API allows you to retrieve all of their Page-scoped and app-scoped IDs from a single ID.

For example, you can use the Page-scoped ID for a person received from a webhook event to retrieve their app-scoped IDs for every app you own, and their Page-scoped IDs for every Page you own. This allows you to identify and provide a consistent experience across multiple channels, such as multiple Messenger apps.

For complete details on implementing ID Matching, see Page & App ID Matching.

Contents

Requirements

ID Matching API Usage Policy


The ID Matching API may only be used by a business to connect the IDs for that business's app or Page to another app or Page owned by and maintained on behalf of the same business. For example, service providers may not use the API to support multiple customers.

For potential violations of this policy, your API requests will be subject to a review and return an error message “(#200) Your business is currently going through review to access this API.”

The ID Matching API uses the Facebook Business Manager to identify which apps and Pages are owned by you. For the ID Matching API to identify a person's app-scoped and Page-scoped IDs across all of the apps and Pages you own, you must do the following:

  • Create a Business Manager account.
  • Add all apps you want matched to your Business Manager account.
  • Add all Pages you want matched to your Business Manager account.

For more information on setting up a Business Account and adding your apps and Pages to it, see Facebook for Business.

Base URI

https://graph.facebook.com/v2.6/

Retrieve Page-scoped IDs

The ids_for_pages endpoint allows you to retrieve a person's Page-scoped IDs across all Pages you own. You may also retrieve the person's Page-scoped ID for a specific Page.

Path

GET /<ID>/ids_for_pages?
  page=<OPTIONAL_PAGE_ID>
  &access_token=<ACCESS_TOKEN>
  &appsecret_proof=<APP_SECRET_PROOF>

Request Parameters

ParameterTypeDescription

ID

Integer

The person's Page-scoped ID or app-scoped ID.

page

Integer

Optional. Page ID of a specific Page to retrieve the person's Page-scoped ID for. If not set, endpoint will return all Page-scoped IDs for all Pages you own.

access_token

String

Page access token if ID is a Page-scoped ID.


App access token if ID is an app-scoped ID.

appsecret_proof

String

A SHA-256 hash of Page ID and Page token if ID is a Page-scoped ID.


A SHA-256 hash of app ID and app token if ID is an app-scoped ID.


For more information on generating appsecret_proof, see Verifying Graph API Calls with appsecret_proof in Securing Graph API Requests.

Example Response

{
  "data": [
    {
      "id": "1429374444444138",
      "page": {
        "name": "YourPage",
        "id": "1080444444438365"
      }
    },
    {
      "id": "1254444444442919",
      "page": {
        "name": "YourOtherPage",
        "id": "644444441943165"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "MTA4MDYxNjQ2ODczODM2NQZDZD",
      "after": "NjgyNDk4MTcxOTQzMTY1"
    }
  }
}

Retrieve App-scoped IDs

The ids_for_apps endpoint allows you to retrieve a person's app-scoped IDs across all Pages you own. You may also retrieve the person's app-scoped ID for a specific app.

Path

GET /<ID>/ids_for_apps?
  app=<OPTIONAL_APP_ID>
  &access_token=<ACCESS_TOKEN>
  &appsecret_proof=<APP_SECRET_PROOF>

Request Parameters

ParameterTypeDescription

ID

Integer

The person's Page-scoped ID or app-scoped ID.

app

Integer

Optional. App ID of a specific app to retrieve the person's app-scoped ID for. If not set, endpoint will return all app-scoped IDs for all apps you own.

access_token

String

Page access token if ID is a Page-scoped ID.


App access token if ID is an app-scoped ID.

appsecret_proof

String

A SHA-256 hash of Page ID and Page token if ID is a Page-scoped ID.


A SHA-256 hash of app ID and app token if ID is an app-scoped ID.


For more information on generating appsecret_proof, see Verifying Graph API Calls with appsecret_proof in Securing Graph API Requests.

Example Response

{
  "data": [
    {
      "id": "10212959474723846",
      "app": {
        "link": "https://www.facebook.com/games/?app_id=344444443510389",
        "name": "Your App",
        "id": "369042944444449"
      }
    },
    {
      "id": "10213144444441476",
      "app": {
        "link": "https://www.facebook.com/games/?app_id=1719944444448212",
        "name": "Your Other App",
        "id": "1719933444444412"
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "MzY5MDQyOTMzNTEwMzg5",
      "after": "MTcxOTkzMzY3ODMwODIxMgZDZD"
    }
  }
}