SCO Validation & Verification API

The SCO Validation & Verification API checks an OpenRTB supply chain object (SCO) before you act on a bid request. Validation checks that the SCO is well formed. Verification also checks each seller it declares against the publisher’s ads.txt or app-ads.txt and each seller’s sellers.json entry. You get back a status and reason codes you can use to decline the request or take the problem to the seller.

Before you start

• API key: send it in the x-api-key header. See Authentication and API keys.
• Base URL: https://api.pixalate.com/api/v2
• Format: every endpoint takes a JSON POST body and returns JSON.

Make your first request

Validate and verify one SCO for a website. Send the serialized SCO string as sco and the publisher domain as id:

curl -X POST "https://api.pixalate.com/api/v2/sco/website/vv" \
  -H "x-api-key: $PIXALATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sco": "1.0,1!ssp.example.com,1234,1,bid-request-id-1,ExampleSSP,ssp.example.com",
    "id": "example.com"
  }'

For a mobile or CTV app, call /sco/app/vv and send the app’s bundle ID as id, for example com.example.mobileapp.

Read the response

The response is an array of results. Each result has a status and, when there’s a problem, the reasons behind it. This example shows the shape of a failed verification:

[
  {
    "status": "invalid",
    "reasons": [206]
  }
]

Endpoints

Pick an endpoint by supply type, by whether you want verification, and by single or bulk.

Use /sco/vv and /sco/bulk/vv when one integration submits both websites and apps.

Check many SCOs in one call

The bulk endpoints take a JSON array. Each element has the same sco and id fields as a single request:

curl -X POST "https://api.pixalate.com/api/v2/sco/bulk/vv" \
  -H "x-api-key: $PIXALATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "sco": "1.0,1!ssp.example.com,1234,1,bid-request-id-1,ExampleSSP,ssp.example.com",
      "id": "example.com"
    },
    {
      "sco": "1.0,1!ssp.example.com,1234,1,bid-request-id-2,ExampleSSP,ssp.example.com",
      "id": "com.example.mobileapp"
    }
  ]'

The response is an object with a results array that holds one outcome per submitted item. Each outcome has the same status and reasons fields as the single-item response.

Validate only

/sco/v and /sco/bulk/v check that an SCO is well formed without looking up any seller records, so they can only return reason codes 101 and 102. Use the validate-and-verify endpoints when you need authorization checks.

Reason codes

reasons contains one or more of these codes. Codes 101 and 102 are problems with the SCO itself. Codes 201 to 209 are problems with the authorization of the entities it declares, and only the validate-and-verify endpoints return them.

Errors

A 200 response with status: "invalid" or status: "error" isn’t an HTTP error. It’s the result of the check. See Quotas, limits and errors for status codes across all Pixalate APIs.

Related