Score an External Asset

Scoring is asynchronous. Submit the asset, poll for completion, then fetch results.

POST /v1/media
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "id": "spring-15s-vertical-v1",
  "version": "1.0",
  "url": "https://your-cdn.com/creative.mp4",
  "workspaceId": 45914,
  "channels": ["META", "ADWORDS", "DV360", "LINKEDIN", "REDDIT"],
  "name": "Spring Campaign — 15s Vertical"
}

Request body:

Field	Type	Required	Notes
`id`	string	Yes	Your external (client-side) media ID. Combined with `version` (and `source`) it must be unique — resubmitting the same `(id, version)` returns the existing asset rather than creating a new one.
`url`	string	Yes	Direct download URL. Redirect chains and auth-gated links can cause scoring to fail silently. S3 presigned URLs, CDN links, and `drive.usercontent.google.com` direct links work.
`version`	string	No	Asset version label (your side). Part of the uniqueness key with `id`.
`source`	string	No	Source system identifier (e.g. DAM name).
`workspaceId`	number	No	Numeric workspace ID. Two effects: (1) only API media submitted with a `workspaceId` are visible inside ACS, and (2) scoring uses the workspace's guidelines on top of the organization-global guidelines. If omitted, only org-global guidelines apply and the media is not visible in ACS. Use `GET /v1/workspaces` to find available IDs.
`channels`	string[]	No	Channel identifiers to score against. See Channel Identifiers. If omitted, defaults to the workspace's active-scorecard channels.
`name`	string	No	Human-readable name.
`description`	string	No	Free-text description.
`brands`	string[]	No	Brand identifiers that apply to this asset.
`markets`	string[]	No	Market identifiers that apply to this asset.

Successful response:

{
  "status": "OK",
  "result": {
    "uniqueId": "8576725c-dc61-42c6-bf56-3898ea2523cf"
  }
}

The response result contains only the uniqueId. Store the id / version / url you submitted on your side — they are not echoed back.

Step 2 — Poll for status

Look up by uniqueId:

GET /v1/media/{uniqueId}/status

Or, equivalently, by your external id + source + version:

GET /v1/media/{id}/status?source=<src>&version=<ver>

Use one form or the other — not both.

Response:

{
  "status": "OK",
  "result": {
    "uniqueId": "8576725c-dc61-42c6-bf56-3898ea2523cf",
    "id": "spring-15s-vertical-v1",
    "version": "1.0",
    "source": "my-dam",
    "status": "COMPLETE"
  }
}

The inner status describes the media's processing state. The outer envelope status is always "OK" on success.

Status values:

Value	Meaning
`PROCESSING`	Media is being ingested or scored. Keep polling.
`COMPLETE`	Scoring finished — fetch scores.
`ERROR`	A non-terminal error occurred during processing.
`UNSUPPORTED`	Media format/type is not supported. Terminal.
`FAILED`	Processing failed. Terminal.

Recommended polling interval: every 10–15 minutes. Scoring is a multi-stage pipeline; tighter polling does not speed it up and risks hitting rate limits.

Step 3 — Retrieve scores

GET /v1/scoring/media/{uniqueId}/scores?format=detail&channel=META

Query parameters:

Param	Type	Notes
`channel`	string	Comma-separated channel identifiers to filter results (e.g. `META,DV360`).
`source`	string	Optional. Only required when looking up by external `id` if a non-empty `source` was used at submission time (`source` + `id` + `version` together disambiguate the asset). Omit when looking up by `uniqueId`.
`version`	string	Optional. Required when looking up by external `id` if a non-empty `version` was used at submission. Omit when looking up by `uniqueId`.
`format`	string	`summary` (default) returns the per-channel rollup only. `detail` returns the per-channel rollup plus a `detail` array with per-guideline results (`name`, `channel`, `result`, `weight`, etc.). Pass `summary,detail` to be explicit.

Summary-level response:

{
  "status": "OK",
  "result": {
    "media": {
      "id": "spring-15s-vertical-v1",
      "uniqueId": "8576725c-dc61-42c6-bf56-3898ea2523cf",
      "version": "1.0",
      "name": "Spring Campaign — 15s Vertical",
      "type": "VIDEO"
    },
    "summary": {
      "META": {
        "score": 0.83,
        "adherencePercent": 0.62,
        "passCount": 26,
        "failCount": 20,
        "applicableCount": 53,
        "notApplicableCount": 2,
        "notAvailableCount": 7
      }
    }
  }
}

Per-channel summary fields:

score — weighted score (0.0–1.0).
adherencePercent — unweighted pass rate (0.0–1.0).
passCount / failCount — counts of guidelines that returned PASS / FAIL.
applicableCount — total guidelines applicable to the asset's media type for this channel — i.e. the count of all possible scores (= passCount + failCount + notAvailableCount).
notApplicableCount — guidelines that did not apply to the asset's format/creative type (excluded from applicableCount).
notAvailableCount — applicable guidelines that returned a NO_DATA_* code (could not be evaluated). Counted within applicableCount.

Channel keys in summary and detail use the canonical identifiers (META, X, etc.) — see Channel Identifiers.