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.
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.
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.
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.
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.
You must first request authorization to send events on behalf of your clients. You have the following authentication options:
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.
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.
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.
You can monitor Event Match Quality score per event, along with match keys being sent, using the following API endpoint, parameters and fields:
https://graph.facebook.com/v21.0
/<pixel_id>/setup_quality
Parameter | Description |
---|---|
agent_name string | Optional. For example, if your partner_agent value is The If you are an advertiser, most of the time you should not worry about If you do not provide an |
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. |
Graph API Explorer
GET/v21.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" } ] }
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.
The partner_agent
value in your API GET request should be a normalized lowercase format. This field is now optional.
Conversions API setup quality guidance from Meta Business Help Center: