SeoclerksDevelopers

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

NameWhereDescription
Idempotency-Key requiredheaderMakes a retry safe. Required on every POST. Must match ^[A-Za-z0-9_.-]{1,64}$.

Request body

FieldTypeDescription
urls requiredlist of stringThe 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.
targetstringThe buyer's site. Left out, the result is capped at partial. Up to 2048 characters.
promised_countintegerHow many links the report promised. 1 to 1000000.
expected_credits requiredintegerThe most you authorise for this call. A higher price is refused with price_changed. 1 to 100000.
familystringThe 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

FieldTypeDescription
bandstringverified, partial, unverified, failed or not_checkable.
scoreinteger or null0-100.
checkedinteger
verifiedinteger
flagsobject
submittedintegerURLs received.
sampledintegerURLs checked.
itemslist of object
items[].urlstring
items[].http_statusinteger or null
items[].links_to_targetboolean or null
items[].relstring or null
items[].indexableboolean or null
items[].detailobject
items[].checked_attimestamp or null
credits_chargedinteger0 when the result is not checkable.
credit_sourcestring or nullgranted, paid or mixed.
balanceintegerCredits 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"
    }
}

Errors