Setup Quality API

This API is under beta. For access, please contact your Meta representative.

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 Setup Quality API can help solve this problem by consolidating setup 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 Setup 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 setup quality data to incorporate in their monitoring.

Authentication

Advertiser Authentication via Business Manager

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.
Go to the Assign Asset dialog and choose Pixels. Then, select the pixels you want to send events on behalf of.
For each pixel, select the Manage Pixel permission, and click Save Changes.
Go back to your system user's details page. Verify that the selected pixels are visible there.
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 Setup 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/v20.0/<pixel_id>/setup_quality

Parameters

Parameter Description

Parameter	Description
`agent_name` string	Optional. The normalized value of the partner_agent field is used to filter only events sent with partner_agent param in /{pixel_id}/events POST request (see attributing your events best practices here and here). For example, if your partner_agent value is `[partner_name]_[majorversion]_[minorVersion]`, your normalized agent string value will be `partner_name` in lowercase. The `agent_name` allows you to set your own platform identifier when sending events on behalf of a client. If you are a managed partner/agency, work with your Meta representative to agree on an identifier for your platform. If you are an advertiser, most of the time you should not worry about `agent_name` attribution. If you do not provide an `agent_name`, all events regardless of whether they were sent by an agent or not, will be included in the EMQ calculation.

agent_name

string

Optional.
The normalized value of the partner_agent field is used to filter only events sent with partner_agent param in /{pixel_id}/events POST request (see attributing your events best practices here and here).

For example, if your partner_agent value is [partner_name]_[majorversion]_[minorVersion], your normalized agent string value will be partner_name in lowercase.

The agent_name allows you to set your own platform identifier when sending events on behalf of a client. If you are a managed partner/agency, work with your Meta representative to agree on an identifier for your platform.

If you are an advertiser, most of the time you should not worry about agent_name attribution.

If you do not provide an agent_name, all events regardless of whether they were sent by an agent or not, will be included in the EMQ calculation.

Fields

Field	Description
`event_name` string	A standard event or custom event name.
`event_match_quality` AdsPixelCAPIEMQ	Event Match Quality indicates how effective the customer information sent from your server may be at matching event instances to a Facebook account.

Example

Graph API Explorer

GET/v20.0/<PIXEL_ID>/setup_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>/setup_quality

API Response

{
  "data": [
    {
      "event_match_quality": {
        "composite_score": 6.2,
        "match_key_feedback": [
          {
            "identifier": "email",
            "coverage": {
              "percentage": 100
            }
          },
          {
            "identifier": "ip_address",
            "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": "ip_address",
            "coverage": {
              "percentage": 99.9
            }
          },
          {
            "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

What is the access token used for?

The access token is used when partners send signal events or access the Setup Quality API on behalf of advertisers. The client system user access token onboarding method is not compatible with the EMQ API at the moment.

Permalink

How should the partner_agent field be formatted?

The partner_agent value in your API GET request should be a normalized lowercase format. This field is now optional.

Permalink

Learn More

Conversions API Best Practices.
Drive performance with an optimized Conversions API setup.
Best practices to onboard the Conversions API for partners
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.