Signal Readiness API

Using the Signal Readiness API, partners can access the Signal Readiness scores and recommendations that are available to advertisers in Events Manager within Snap Ads Manager.

What is the Signal Readiness Score?

The Signal Readiness Score indicates how effective the customer parameters and identity signals passed with your app and web conversion events may be at matching to a Snapchat account.

Matched events help you deliver your ads to Snapchatters who are more likely to take the action you care about, and attribute those actions back to your ads. Better event quality score means events are more likely to match to a Snapchat account, which can help you see more conversions and lower your cost per result.

Learn more about Signal Readiness in this help center article.

Understanding Your Event Quality Score

There are three scores that indicate how effective the parameters you are sending are at matching to a Snapchat account.

Signal Readiness Explainer

Using this API for a Public-Facing UI

This API is intended for approved partners and advertisers to troubleshoot or monitor signal readiness for internal purposes. Any use of data from this API on a public-facing user interface must first be reviewed and approved by the Snap team. If you would like to display information from this API publicly, please contact your Snap representative for approval.

Authentication

This API requires you to pass a bearer token in the Authorization header:

curl 'https://adsapi.snapchat.com/v1/pixels/{{Pixel Id}}/event_quality_scores' \
--header 'Authorization: Bearer {{API ACCESS TOKEN HERE}}'

This API accepts two types of tokens: the Long Lived Conversions API token and the Snap OAuth token.

Long Lived CAPI token

Follow the steps below to obtain a Long Lived CAPI Token. Long Lived tokens are valid until they are deleted in the Ads Manager.

Log in to Ads Manager. Then click the menu in the top corner and select Business Details.
Once on this page, under the OAuth Apps section, you will now see a new section called the Conversions API Tokens. Here you can click on the Generate Token button to generate a new token. Please note that you must be an Organization Admin to view this section of the page.
You can then copy the token and use it for this endpoint
You may generate multiple tokens and can also delete these tokens to invalidate them. These tokens do not expire and you do not need to refresh access.
Long lived tokens can only be used for the pixel and app IDs that belong to the Org where the token has been generated.

Snap OAuth token

This token can be obtained by following the OAuth flow described in this documentation. Note that OAuth tokens are only valid for 60 minutes and must be refreshed when they expire.

Rate Limiting

The rate limit differs depending on the token used.

Long Lived CAPI Token: We recommend a 1000 request/second limit.
OAuth Token: Rate limits are implemented both at App and Token level, the App is able to support an overall average volume of 20 requests/second, individual Access tokens issued by the App can make requests at an average of 10 requests/second.

API Spec

Pixel endpoint

curl 'https://adsapi.snapchat.com/v1/pixels/{{Pixel Id}}/event_quality_scores?locale={{Locale Code}}' \
--header 'Authorization: Bearer {{API ACCESS TOKEN HERE}}'

Path parameters

Parameter	Description	Example
Pixel Id	The ID of the pixel to get the event quality scores for.	`57ad1ad-600076e-58fa375-e19284`

Query parameters

Parameter	Description	Example
Locale Code	The locale code to get the event quality scores for.	`es-es`, `en-US`, `DE-DE`

Sample request

curl 'https://adsapi.snapchat.com/v1/pixels/808bc6d0-4cd9-4b08-930f-f2912081eea5/event_quality_scores?locale=en-US' \
--header 'Authorization: Bearer {{API ACCESS TOKEN HERE}}'

Sample response

{
  "request_status": "SUCCESS",
  "request_id": "6808199600ff096f996664635e0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d312d3937392d310001013e",
  "event_quality_scores": [
    {
      "sub_request_status": "SUCCESS",
      "event_quality_score": {
        "action_source": "WEB",
        "event_source": "API",
        "event_type": "ADD_CART",
        "recommendations": [
          {
            "title": "CAPI - Low First Name, Last Name, and Zip Code coverage",
            "description": "You're currently sending First Name, Last Name, and Zip Code on only 0% of your Purchase events.",
            "recommendation_code": "PII_COVERAGE_CAPI",
            "priority": "P2",
            "score": "BAD"
          }
        ]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "event_quality_score": {
        "action_source": "WEB",
        "event_source": "SDK",
        "event_type": "PURCHASE",
        "recommendations": [
          {
            "title": "Pixel - Low Product Match Rate - Purchase",
            "description": "We're unable to match the item IDs or group IDs in your Purchase events to products in your catalog.",
            "recommendation_code": "LOW_PRODUCT_MATCH_RATE_SDK",
            "priority": "P1",
            "score": "BAD"
          }
        ]
      }
    }
  ]
}

App endpoint

curl 'https://adsapi.snapchat.com/v1/mobile_apps/{{Snap App Id}}/event_quality_scores?locale={{Locale Code}}' \
--header 'Authorization: Bearer {{API ACCESS TOKEN HERE}}'

Path parameters

Parameter	Description	Example
Snap App Id	The ID of the app to get the event quality scores for.	`57ad1ad-600076e-58fa375-e19284`

Query parameters

Parameter	Description	Example
Locale Code	The locale code to get the event quality scores for.	`es-es`, `en-US`, `DE-DE`

Sample request

curl 'https://adsapi.snapchat.com/v1/mobile_apps/808bc6d0-4cd9-4b08-930f-f2912081eea5/event_quality_scores?locale=es-MX' \
--header 'Authorization: Bearer {{API ACCESS TOKEN HERE}}'

Sample response

{
  "request_status": "SUCCESS",
  "request_id": "6808294b00ff0659765ed71b150001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d312d3937392d3100010123",
  "event_quality_scores": [
    {
      "sub_request_status": "SUCCESS",
      "event_quality_score": {
        "action_source": "MOBILE_APP",
        "event_source": "MMP",
        "event_type": "APP_INSTALL",
        "recommendations": [
          {
            "title": "Cobertura baja de Versión de SO - Inclusión: com.einnovation.temu",
            "description": "Actualmente envías Versión de SO en solo el 0 % de tus eventos de Instalación de app de inclusión.",
            "recommendation_code": "PII_COVERAGE_MMP_KOCHAVA_OPT_IN",
            "priority": "P2",
            "score": "BAD",
            "partner": "kochava",
            "app_os": "Android"
          },
          {
            "title": "Cobertura baja de Versión de SO - Inclusión: com.einnovation.temu",
            "description": "Actualmente envías Versión de SO en solo el 0 % de tus eventos de Instalación de app de inclusión.",
            "recommendation_code": "PII_COVERAGE_MMP_TENJIN_OPT_IN",
            "priority": "P2",
            "score": "BAD",
            "partner": "tenjin",
            "app_os": "Android"
          }
        ]
      }
    }
  ]
}

Response fields

Field	Description	Examples
request_status	The status of the request.	SUCCESS, FAILED
request_id	The ID of the request.	`e4dae153-1514-43bb-b81f-676ebcfe8abc`
event_quality_scores	The event quality scores for the pixel or app.	`List<EventQualityScore>`

Event Quality Score

A list of event quality scores. Scores are broken down by each action source, event source, and event type.

Field	Description	Examples
action_source	The action source associated with the score.	WEB, OFFLINE, MOBILE_APP
event_source	Event source associated with the score.	API, SDK, MMP
event_type	Event type associated with the score.	PURCHASE, ADD_CART, APP_INSTALL
recommendations	The recommendations for the event.	`List<Recommendation>`

Recommendation

Contains a list of recommended improvements that, if implemented, should increase event quality scores. Recommendations are provided for each partner and mobile app operating system (OS). Note that not all recommendations included in the API response will appear in Events Manager due to UI space limitations.

Field	Description	Examples
title	Brief description of the Signal Readiness recommendation. This is the title that advertisers see for the recommendation in Ads Manager.	`Pixel - Low Product Match Rate - Purchase`
description	Detailed description of the Signal Readiness recommendation. This is the full explanation that advertisers see in Ads Manager.	`We're unable to match the item IDs or group IDs in your Purchase events to products in your catalog.`
recommendation_code	Code associated with the recommendation.	`PII_COVERAGE_CAPI`, `PII_SPAM_CAPI`
priority	Priority of the recommendation. Implementing higher priority recommendations typically result in a greater improvement on the score.	`P0`, `P1`, `P2`
score	Signal readiness score associated with the event.	`GOOD`, `OKAY`, `BAD`
partner	Partner associated with the recommendation. (App Endpoint Only)	`snapchat`
app_os	Mobile OS associated with the recommendation. (App Endpoint Only)	`Android`, `iOS`

Was this page helpful?

Yes

What is the Signal Readiness Score?​

Understanding Your Event Quality Score​

Using this API for a Public-Facing UI​

Authentication​

Long Lived CAPI token​

Snap OAuth token​

Rate Limiting​

API Spec​

Pixel endpoint​

Path parameters​

Query parameters​

Sample request​

Sample response​

App endpoint​

Path parameters​

Query parameters​

Sample request​

Sample response​

Response fields​

What is the Signal Readiness Score?

Understanding Your Event Quality Score

Using this API for a Public-Facing UI

Authentication

Long Lived CAPI token

Snap OAuth token

Rate Limiting

API Spec

Pixel endpoint

Path parameters

Query parameters

Sample request

Sample response

App endpoint

Path parameters

Query parameters

Sample request

Sample response

Response fields