Ontwikkelaarsreferentie

Asynchrone API-batches

Plaats meerdere ondersteunde API-verzoeken in de wachtrij en verzamel de resultaten zonder een clientverbinding open te houden.

Asynchrone API-batches

Plaats meerdere ondersteunde API-verzoeken in de wachtrij en verzamel de resultaten zonder een clientverbinding open te houden.

POST /v1/batches

Zo werkt batchverwerking

Elke batch accepteert maximaal 100 ondersteunde openbare GET-verzoeken.
Elk item behoudt de normale prijs van het endpoint, en definitief mislukte items worden afzonderlijk terugbetaald.
De taakstatus en resultaten blijven 24 uur beschikbaar voor alle leden van het account.
Een optionele HTTPS-webhook kan uw systeem op de hoogte stellen wanneer de verwerking een eindstatus bereikt.

Voorbeeldverzoek

curl -X POST "https://domscan.net/v1/batches" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Idempotency-Key: customer-import-42" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"path": "/v1/status", "query": {"domain": "example.com"}},
      {"path": "/v1/dns", "query": {"domain": "example.org", "type": "MX"}}
    ]
  }'

Antwoordvelden

Veld	Type
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string

Voorbeeldantwoord

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  }
}

Status opvragen en annuleren

Vraag het statusendpoint op, haal de resultaten in volgorde op of annuleer werk dat nog niet is gestart.

GET /v1/batches/{job_id}
GET /v1/batches/{job_id}/results
DELETE /v1/batches/{job_id}

Ondertekende webhooks bij voltooiing

Webhookhandtekeningen gebruiken HMAC-SHA256 over de tijdstempel, een punt en de exacte aanvraagbody. Controleer de tijdstempel voordat u een levering accepteert.

X-DomScan-Event: batch.completed
X-DomScan-Timestamp: 1785231000
X-DomScan-Signature: sha256=...

GET /v1/batches

Queryparameters

Parameter	Type	vereist
limit	integer	optioneel

Antwoordvelden

Veld	Type
`jobs[]`	object[]
`jobs[]`	object
`jobs[].id`	string
`jobs[].status`	string
`jobs[].total`	integer
`jobs[].counts`	object
`jobs[].counts.pending`	integer
`jobs[].counts.processing`	integer
`jobs[].counts.succeeded`	integer
`jobs[].counts.failed`	integer
`jobs[].counts.cancelled`	integer
`jobs[].billing`	object
`jobs[].billing.credits_charged`	integer
`jobs[].billing.credits_refunded`	integer
`jobs[].billing.credits_net`	integer
`jobs[].webhook`	object
`jobs[].webhook.configured`	boolean
`jobs[].webhook.status`	string
`jobs[].webhook.attempts`	integer
`jobs[].status_url`	string
`jobs[].results_url`	string
`jobs[].poll_after_ms`	integer \| null
`jobs[].created_at`	string
`jobs[].started_at`	string \| null
`jobs[].completed_at`	string \| null
`jobs[].cancelled_at`	string \| null
`jobs[].updated_at`	string
`jobs[].processing_deadline_at`	string
`jobs[].results_expires_at`	string
`retention_hours`	integer

Voorbeeldverzoek

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches?limit=25"

Voorbeeldantwoord

{
  "jobs": [
    {
      "id": "string",
      "status": "queued",
      "total": 1,
      "counts": {
        "pending": 1,
        "processing": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1
      },
      "billing": {
        "credits_charged": 1,
        "credits_refunded": 1,
        "credits_net": 1
      },
      "webhook": {
        "configured": true,
        "status": "not_configured",
        "attempts": 1
      },
      "status_url": "https://example.com",
      "results_url": "https://example.com",
      "poll_after_ms": 1,
      "created_at": "2026-04-15T12:00:00Z",
      "started_at": "2026-04-15T12:00:00Z",
      "completed_at": "2026-04-15T12:00:00Z",
      "cancelled_at": "2026-04-15T12:00:00Z",
      "updated_at": "2026-04-15T12:00:00Z",
      "processing_deadline_at": "2026-04-15T12:00:00Z",
      "results_expires_at": "2026-04-15T12:00:00Z"
    }
  ],
  "retention_hours": 24
}

GET /v1/batches/:job_id

Antwoordvelden

Veld	Type
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string

Voorbeeldverzoek

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches/example.com"

Voorbeeldantwoord

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  }
}

GET /v1/batches/:job_id/results

Queryparameters

Parameter	Type	vereist
job_id	string	vereist
after	integer	optioneel
limit	integer	optioneel

Antwoordvelden

Veld	Type
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string
`results[]`	object[]
`results[]`	object
`results[].position`	integer
`results[].reference`	string \| null
`results[].request`	object
`results[].request.method`	string
`results[].request.path`	string
`results[].request.query`	object
`results[].status`	string
`results[].attempts`	integer
`results[].http_status`	integer \| null
`results[].result`	object \| null
`results[].error`	object \| null
`results[].billing`	object
`results[].started_at`	string \| null
`results[].completed_at`	string \| null
`next_after`	integer \| null

Voorbeeldverzoek

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches/example.com/results?after=example.com&limit=25"

Voorbeeldantwoord

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  },
  "results": [
    {
      "position": 1,
      "reference": "string",
      "request": {
        "method": "GET",
        "path": "string",
        "query": {}
      },
      "status": "pending",
      "attempts": 1,
      "http_status": 1,
      "result": {},
      "error": {},
      "billing": {},
      "started_at": "2026-04-15T12:00:00Z",
      "completed_at": "2026-04-15T12:00:00Z"
    }
  ],
  "next_after": 1
}

DELETE /v1/batches/:job_id

Antwoordvelden

Veld	Type
`job`	object
`job.id`	string
`job.status`	string
`job.total`	integer
`job.counts`	object
`job.counts.pending`	integer
`job.counts.processing`	integer
`job.counts.succeeded`	integer
`job.counts.failed`	integer
`job.counts.cancelled`	integer
`job.billing`	object
`job.billing.credits_charged`	integer
`job.billing.credits_refunded`	integer
`job.billing.credits_net`	integer
`job.webhook`	object
`job.webhook.configured`	boolean
`job.webhook.status`	string
`job.webhook.attempts`	integer
`job.status_url`	string
`job.results_url`	string
`job.poll_after_ms`	integer \| null
`job.created_at`	string
`job.started_at`	string \| null
`job.completed_at`	string \| null
`job.cancelled_at`	string \| null
`job.updated_at`	string
`job.processing_deadline_at`	string
`job.results_expires_at`	string

Voorbeeldverzoek

curl -X DELETE "https://domscan.net/v1/batches/example.com" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'

Voorbeeldantwoord

{
  "job": {
    "id": "string",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": true,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "poll_after_ms": 1,
    "created_at": "2026-04-15T12:00:00Z",
    "started_at": "2026-04-15T12:00:00Z",
    "completed_at": "2026-04-15T12:00:00Z",
    "cancelled_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z",
    "processing_deadline_at": "2026-04-15T12:00:00Z",
    "results_expires_at": "2026-04-15T12:00:00Z"
  }
}