Deliverable QA
POST /deliverable-qa/scores
Score a third-party delivery report
Scope: deliverable-qa:write. The broad write grant does not include it. Idempotency-Key is required.
Needs the explicit deliverable-qa:write key scope (never the broad write; OAuth does not carry it). Off until the site switches it on. 6 Workbench credits per usable score; a result that is not checkable is free, including a report with no checkable sample. No order or seller is affected. The links are fetched before any credit is spent, and the charge and the stored result commit together, so a failed or interrupted request costs nothing. Retry the exact request with the same Idempotency-Key to get the stored answer without fetching or charging again; a changed body is a conflict. Up to 200 URLs are accepted and 10 sampled (the site can raise this to 50), within a 30-second budget. robots.txt and per-host gaps are honoured across keys. Unknown, blocked and skipped links do not count as missing. A band is sampled evidence, not proof. A key may spend at most 600 credits per UTC day by default. expected_credits is the most you authorise: a higher price is refused.
Parameters
| Name | Where | Description |
|---|---|---|
Idempotency-Key required | header | Makes a retry safe. Required on every POST. Must match ^[A-Za-z0-9_.-]{1,64}$. |
Request body
| Field | Type | Description |
|---|---|---|
urls required | list of string | The links the report lists. Send final destination URLs: a redirect is unknown, not missing. At most 200; a sample of 10 is checked. Up to 200 items. |
target | string | The buyer's site. Left out, the result is capped at partial. Up to 2048 characters. |
promised_count | integer | How many links the report promised. 1 to 1000000. |
expected_credits required | integer | The most you authorise for this call. A higher price is refused with price_changed. 1 to 100000. |
family | string | The kind of work. Only links is checked here; the others come back not checkable and free. One of links, content, social, other. Default links. |
Example request
curl -X POST "https://www.seoclerk.com/api/v1/deliverable-qa/scores" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY" \
-H "Idempotency-Key: scoredeliverablereport-1" \
-H "Content-Type: application/json" \
-d '{"urls":["string"],"expected_credits":1}'
Response 200
| Field | Type | Description |
|---|---|---|
band | string | verified, partial, unverified, failed or not_checkable. |
score | integer or null | 0-100. |
checked | integer | |
verified | integer | |
flags | object | |
submitted | integer | URLs received. |
sampled | integer | URLs checked. |
items | list of object | |
items[].url | string | |
items[].http_status | integer or null | |
items[].links_to_target | boolean or null | |
items[].rel | string or null | |
items[].indexable | boolean or null | |
items[].detail | object | |
items[].checked_at | timestamp or null | |
credits_charged | integer | 0 when the result is not checkable. |
credit_source | string or null | granted, paid or mixed. |
balance | integer | Credits left after the charge. |
{
"data": {
"band": "string",
"score": 1,
"checked": 1,
"verified": 1,
"flags": {},
"submitted": 1,
"sampled": 1,
"items": [
{
"url": "string",
"http_status": 1,
"links_to_target": true,
"rel": "string",
"indexable": true,
"detail": {},
"checked_at": "2026-10-10T14:03:22Z"
}
],
"credits_charged": 1,
"credit_source": "string",
"balance": 1
},
"meta": {
"request_id": "9f2c4e1ab07d3351"
}
}