> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pixalate.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pixalate.com/_mcp/server.

# SCO Validation & Verification API

> Validate the structure of an OpenRTB supply chain object (SCO) and verify its sellers against ads.txt, app-ads.txt and sellers.json with Pixalate's 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](/apis/authentication).
* **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`:

```bash
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:

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

| Field     | Type              | Description                                                                            |
| --------- | ----------------- | -------------------------------------------------------------------------------------- |
| `status`  | string            | `valid`: the SCO is valid. `invalid`: the SCO is invalid. `error`: there was an error. |
| `reasons` | array of integers | The [reason codes](#reason-codes) for the verdict.                                     |

## Endpoints

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

| Endpoint                    | Checks              | Supply type           | `id` value                        | Reference                                                   |
| --------------------------- | ------------------- | --------------------- | --------------------------------- | ----------------------------------------------------------- |
| `POST /sco/app/vv`          | Validate and verify | Apps (mobile and CTV) | App bundle ID                     | [Single](/api-reference/sco/validate-verify-app-single)     |
| `POST /sco/bulk/app/vv`     | Validate and verify | Apps (mobile and CTV) | App bundle ID                     | [Bulk](/api-reference/sco/validate-verify-app-bulk)         |
| `POST /sco/website/vv`      | Validate and verify | Websites              | Publisher domain                  | [Single](/api-reference/sco/validate-verify-website-single) |
| `POST /sco/bulk/website/vv` | Validate and verify | Websites              | Publisher domain                  | [Bulk](/api-reference/sco/validate-verify-website-bulk)     |
| `POST /sco/vv`              | Validate and verify | Websites or apps      | Publisher domain or app bundle ID | [Single](/api-reference/sco/validate-verify-both-single)    |
| `POST /sco/bulk/vv`         | Validate and verify | Websites or apps      | Publisher domain or app bundle ID | [Bulk](/api-reference/sco/validate-verify-both-bulk)        |
| `POST /sco/v`               | Validate only       | Any                   | See note below                    | [Single](/api-reference/sco/validate-single)                |
| `POST /sco/bulk/v`          | Validate only       | Any                   | See note below                    | [Bulk](/api-reference/sco/validate-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:

```bash
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.

> **Note**
>
> The API reference lists `id` as a required field for the validate-only endpoints but doesn't describe it. If a validate-only request is rejected, contact [support@pixalate.com](mailto:support@pixalate.com).

## 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.

| Code  | Meaning                               |
| ----- | ------------------------------------- |
| `101` | SCO declared incomplete               |
| `102` | SCO deserialization failed            |
| `201` | `sellers.json` not resolved           |
| `202` | `ads.txt` not resolved                |
| `203` | `app-ads.txt` not resolved            |
| `204` | Unable to resolve seller domain       |
| `205` | Publisher missing in SCO              |
| `206` | Direct seller not authorized          |
| `207` | Reseller not authorized               |
| `208` | Reseller listed as direct seller      |
| `209` | Link in SCO missing in `sellers.json` |

## Errors

| Status | Meaning                             | What to do                                                     |
| ------ | ----------------------------------- | -------------------------------------------------------------- |
| `400`  | The request has invalid parameters. | Check that the body is valid JSON with the fields shown above. |
| `401`  | The API key is invalid.             | Check the key in your `x-api-key` header.                      |

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](/apis/quotas-and-errors) for status codes across all Pixalate APIs.

## Related

#### [SCO Validation & Verification API reference](/api-reference/sco/validate-verify-both-single)

Request and response schemas for all eight endpoints.

#### [SCO validation and verification background](/compliance/sco)

What an SCO is and why verification matters.