Integration Quality API

Advertisers that share server events using the Conversions API can see the Event Match Quality in Events Manager. However, this only works on an individual basis and is difficult to scale in cases where a tech provider partner, agency partner or advertiser is managing hundreds and thousands of Meta Pixels for their businesses. The Integration Quality API can help solve this problem by consolidating integration quality metrics programmatically at scale.

About Event Match Quality

Event Match Quality

Event Match Quality (EMQ) is a score (out of 10) that indicates how effective the customer information sent from your server may be at matching event instances to a Facebook account. High quality event matching may improve ads attribution and performance. Note that this metric is in development.

How It's Calculated

Event Match Quality is calculated by looking at which customer information parameters are received from your server via a Conversions API integration, the quality of the information received and the percent of event instances that are matched to a Meta account.

How It's Used

Event Match Quality is used to assess whether you're sending via Conversions API the right customer information to match your events to a Meta account, and whether you have set up your customer information parameters correctly. Customer information parameters help match your events to a Meta account so you can attribute conversions to your ads and deliver them to people who are most likely to convert.

Event Match Quality is calculated in real time. Learn more about EMQ best practices here.

EMQ is currently available only for web events. For other event types such as offline and physical store events, app events, conversion leads or any integration under alpha or beta stages, contact your Meta representative for guidance on improving match quality.

Common Use Cases

Partners and agencies may use the Integration Quality API to provide a quality dashboard and insights, while helping their advertisers to enhance and optimize their integrations. Partners may also use this integration to monitor the stability of their Conversions API integration. Advertisers may use this endpoint to aggregate integration quality data to incorporate in their monitoring.

Authentication

Advertiser Authentication via Business Manager

1. In Business Manager, go to the Users section and select the System User tab. Click on the specific system user you are using for the Conversions API.
2. Go to the Assign Asset dialog and choose Pixels. Then, select the pixels you want to send events on behalf of.
3. For each pixel, select the Manage Pixel permission, and click Save Changes.
4. Go back to your system user's details page. Verify that the selected pixels are visible there.
5. To generate the access token, follow instructions here.

Partner Platform Authentication

You must first request authorization to send events on behalf of your clients. You have the following authentication options:

Facebook Login for Business (Recommended)

Facebook Login for Business is the preferred authentication and authorization solution for tech providers and business app developers who need access to their business clients' assets. It allows you to specify the access token type, types of assets, and permissions your app needs, and save it as a set (configuration). You can then present the set to your business clients to complete the flow and grant your app access to their business assets.

Meta Business Extension (Recommended)

With this option, Meta Business Extension (MBE) returns all the necessary information needed to send events on behalf of the client. MBE provides an endpoint to retrieve system user access tokens created in the client’s Business Manager. This process includes permissions to send server events and is done automatically and securely. MBE is currently under beta, please contact your Meta representative for access.

The endpoint requires a user access token as an input parameter. If you are a new MBE user, call this endpoint to fetch the system user access token after you have finished setting up MBE. Existing users need to ask for re-authentication before calling the new API endpoint.

Client Sharing of a Meta Pixel to Partner’s Business Manager

With this option, the client shares their Meta Pixel to the partner via Business Manager settings or via the API. Then, the partner can assign the partner system user to the client pixel and generate an access token to send server events.

Retrieving Pixel Integration Quality Information

You can monitor Event Match Quality score per event, along with match keys being sent, using the following API endpoint, parameters and fields:

Endpoint

https://graph.facebook.com/v21.0/<pixel_id>/integration_quality

Parameters

Fields

Example

Graph API Explorer

GET/v21.0/<PIXEL_ID>/integration_quality?fields=event_match_quality,event_name&agent_name=<AGENT_NAME>&access_token=<ACCESS_TOKEN>

cURL

curl -X GET -G \
  -d 'fields="event_match_quality,event_name"' \
  -d 'agent_name="<AGENT_NAME>"' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<LATEST_VERSION>/<PIXEL_ID>/integration_quality

API Response

{
  "data": [
    {
      "event_match_quality": {
        "composite_score": 5.1,
        "match_key_feedback": [
          {
            "identifier": "email",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "user_agent",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "external_id",
            "coverage": {
              "percentage": 100
            }
          }
        ]      
      },
      "event_name": "pLTVPurchase"
    },
    {
      "event_match_quality": {
        "composite_score": 7.2,
        "match_key_feedback": [
          {
            "identifier": "email",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "user_agent",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "phone",
            "coverage": {
              "percentage": 69.1
            }
          },
          {
            "identifier": "fbp",
            "coverage": {
              "percentage": 96.7
            }
          },
          {
            "identifier": "external_id",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "fbc",
            "coverage": {
              "percentage": 3.2
            }
          }
        ]
      },
      "event_name": "CompleteRegistration"
    }
  ]
}

FAQs

Learn More

1. Conversions API Best Practices.

2. Drive performance with an optimized Conversions API setup.

3. Best practices to onboard the Conversions API for partners

4. Conversions API setup quality guidance from Meta Business Help Center:

• Best practices for Conversions API to help improve ad performance. These Conversions API best practices can help businesses improve their ad performance by lowering their cost per action. We suggest following these best practices upon initial setup, but they can also be used to update existing setups.

• View server event details in Meta Events Manager. After businesses set up the Conversions API, they can use this article to learn how to monitor events and parameters to make sure their setup is working effectively and identify opportunities for improvement. They can also use this article to learn how to use server event details (Event Matching [Event Match Quality/EMQ]), Data Freshness, Event Overview and Event Deduplication) in Events Manager to improve their Conversions API setup.