Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Get event quality scores for conversions

You can access Event Quality Score (EQS) in the API for any ad accounts that you have access to. Use it to prioritize improvements for user matching, deduplication, and overall measurement accuracy.
Learn more about EQS.

Before you begin

Make sure you take the following actions before calling the EQS endpoint:
  • Generate an OAuth access token with the
    ads:read
    scope.
  • Set up conversion tracking with the conversion API, Pinterest Tag, or both.

Call the EQS endpoint

GET
Get event quality score (EQS)
Get event quality score (EQS)

Query parameters

EQS request parameters
ParameterDescription
ad_account_id

string
required
Unique identifier for the organization for which you are measuring conversion quality, such as the owner of the website where events are occurring.
source_platform

string
optional
Use to filter results by event source platforms:
  • MOBILE
  • WEB
ingestion_source

string
optional
Use to filter results by event ingestion sources:
  • CONVERSIONS_API
  • TAG
  • MMP
lookback_period

string
required
Limit the results to events occurring within one day (
1d
) or 14 days (
14d
) preceding the request.

Example request

curl --request GET \
  --url 'https://api.pinterdev.com/v5/ad_accounts/123456789012/conversion_eqs?lookback_period=14d' \
  --header 'authorization: Bearer pina_ABCD1234...'

Response fields to keep in mind

The endpoint returns an
overall_status
—or quality rating—for each
source_platform
and
ingestion_source
combination for the
ad_account_id
specified in request.
It also lists each conversion event type associated with each user matching/event insight parameter (such as
email
or
order_id
) and the parameter
coverage
in that event type, which is the percentage of events that include the parameter.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
Any parameters and code examples that appear in this section support this use case, but may not represent the full endpoint specification. See the endpoint reference page for the comprehensive spec.
EQS response fields
FieldDescription
overall_status

string
One of three event quality ratings for each user matching and event insight parameter:
  • GOOD
  • FAIR
  • NEEDS_IMPROVEMENT
Learn what each score means.
quality_components

object
Provides a nested structure indicating the coverage percentage and any quality issues for conversion event types associated with each relevant user matching and event insight parameter:
quality_components
  [parameter]
  [event_type]
    coverage
    issues
quality_components.[user matching/event insight parameter]

string
Type of user matching or event insight parameter.
quality_components.[user matching/event insight parameter].[event_type]

string
Type of conversion event.
quality_components.[user matching/event insight parameter].[event_type].coverage

float
Percentage of events that include the parameter
Can be whole numbers or decimals.
quality_components.[user matching/event insight parameter].[event_type].issues

object
Any problems that impact the event's coverage.
Object structure includes:
  • id
    : Identifier for the issue
  • name
    : Name of the issue
  • reason
    : Description of the issue

Example response

We shortened this example for readability. It shows the structure for one
source_platform
and
ingestion_source
combination:
[
  {
    "overall_status": "FAIR",
    "quality_components": {
      "ip_address": {
        "add_to_cart": {
          "coverage": 100
        },
        "view_category": {
          "coverage": 100
        },
        "lead": {
          "coverage": 100
        },
        "checkout": {
          "coverage": 100
        },
        "signup": {
          "coverage": 100
        },
        "page_visit": {
          "coverage": 100
        }
      },
      "order_id": {
        "checkout": {
          "coverage": 100
        }
      },
      "product_id": {
        "checkout": {
          "coverage": 100
        },
        "add_to_cart": {
          "coverage": 100
        },
        "page_visit": {
          "coverage": 0,
          "issues": [
            {
              "id": "product_id_catalog_match",
              "name": "Low Product ID catalog match",
              "reason": "Some events aren't able to match the Product ID you are sending us to the Product ID in the catalog you uploaded to Pinterest."
            },
            {
              "id": "product_id_coverage",
              "name": "Low Product ID coverage",
              "reason": "Some events aren't receiving Product ID."
            }
          ]
        }
      },
      "user_agent": {
        "lead": {
          "coverage": 100
        },
        "checkout": {
          "coverage": 100
        },
        "page_visit": {
          "coverage": 100
        },
        "add_to_cart": {
          "coverage": 100
        },
        "signup": {
          "coverage": 100
        },
        "view_category": {
          "coverage": 100
        }
      },
      "order_value": {
        "checkout": {
          "coverage": 99.86
        },
        "add_to_cart": {
          "coverage": 100
        }
      },
      "external_id": {
        "lead": {
          "coverage": 100
        },
        "signup": {
          "coverage": 100
        },
        "view_category": {
          "coverage": 100
        },
        "add_to_cart": {
          "coverage": 100
        },
        "checkout": {
          "coverage": 100
        },
        "page_visit": {
          "coverage": 100
        }
      },
      "click_id": {
        "add_to_cart": {
          "coverage": 18.09
        },
        "checkout": {
          "coverage": 15.04
        },
        "view_category": {
          "coverage": 19.89
        },
        "signup": {
          "coverage": 1.99
        },
        "lead": {
          "coverage": 15.59
        },
        "page_visit": {
          "coverage": 17.59
        }
      },
      "maid": {
        "checkout": {
          "coverage": 0,
          "issues": [
            {
              "id": "hashed_maid_valid",
              "name": "Invalid Hashed Maid",
              "reason": "Some events are receiving Hashed Maid in the wrong format. This could be because the Hashed Maid are not formatted or hashed correctly."
            },
            {
              "id": "hashed_maid_coverage",
              "name": "Low Hashed Maid coverage",
              "reason": "Some events aren't receiving Hashed Maid."
            }
          ]
        },
        "lead": {
          "coverage": 0,
          "issues": [
            {
              "id": "hashed_maid_valid",
              "name": "Invalid Hashed Maid",
              "reason": "Some events are receiving Hashed Maid in the wrong format. This could be because the Hashed Maid are not formatted or hashed correctly."
            },
            {
              "id": "hashed_maid_coverage",
              "name": "Low Hashed Maid coverage",
              "reason": "Some events aren't receiving Hashed Maid."
            }
          ]
        },
        "signup": {
          "coverage": 0,
          "issues": [
            {
              "id": "hashed_maid_valid",
              "name": "Invalid Hashed Maid",
              "reason": "Some events are receiving Hashed Maid in the wrong format. This could be because the Hashed Maid are not formatted or hashed correctly."
            },
            {
              "id": "hashed_maid_coverage",
              "name": "Low Hashed Maid coverage",
              "reason": "Some events aren't receiving Hashed Maid."
            }
          ]
        },
        "add_to_cart": {
          "coverage": 0,
          "issues": [
            {
              "id": "hashed_maid_valid",
              "name": "Invalid Hashed Maid",
              "reason": "Some events are receiving Hashed Maid in the wrong format. This could be because the Hashed Maid are not formatted or hashed correctly."
            },
            {
              "id": "hashed_maid_coverage",
              "name": "Low Hashed Maid coverage",
              "reason": "Some events aren't receiving Hashed Maid."
            }
          ]
        }
      },
      "email": {
        "checkout": {
          "coverage": 100
        },
        "lead": {
          "coverage": 99.96
        },
        "add_to_cart": {
          "coverage": 100
        },
        "signup": {
          "coverage": 100
        }
      }
    },
    "ingestion_source": "CONVERSIONS_API",
    "source_platform": "MOBILE",
    "lookback_period": "14d"
  },
  ...
  }
]
Was this page helpful?