Skip to navigation
Identity verification APIAddress Triage

Create remediation links for a grade

Creates one hosted verification link per customer in the chosen grade, each running the published workflow you name, so the customer can confirm their address. Up to 500 links are created per call; when remaining is above zero, call again to continue.

The call is safe to repeat: a row that already has a link is skipped and counted under skipped.alreadyMinted. Rows without your reference, rows for closed, suspended or rejected customers, and (unless you opt in) rows with no contact details are skipped and counted too. No entity is created by this call.

Side effects. Every created link fires the entity.address_link_created webhook. An email carrying the link is sent only to the recipients you name. The call is recorded in your audit log. Creating links is not billed; each verification is billed as usual when the customer completes it in production.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
grade_not_remediable400Only the confirmable_in_app and needs_presence grades can be sent a link.
insufficient_credits402The balance cannot cover the request.
triage_job_not_found404No triage job has this identifier in this organisation and environment.
workflow_not_available422The workflow is not published, is suspended, or went offline during the run.
workflow_subject_mismatch422The workflow verifies businesses. Address remediation needs a workflow for individuals.
secret_key_required403A publishable key was used. This API accepts secret keys only.
environment_mismatch403The key belongs to an environment this host does not serve.
rate_limited429The request rate limit for this key was reached. Retry after a short wait.
rate_limit_store_unavailable503Rate limiting is temporarily unavailable. Retry shortly.

A missing or unknown key returns 401 with a plain sentence in error rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

jobIdstringRequired

The jobId returned when the triage job was accepted.

Request

This endpoint expects an object.
gradeenumRequired

The grade whose rows should receive a link. Only confirmable_in_app and needs_presence can be remediated.

Allowed values:
workflowIdstringRequired1-64 characters
The public identifier of a published workflow for individuals that each link runs.
includeUnreachablebooleanOptional
Set to true to create links for rows with no contact details on file as well.
limitintegerOptional1-500
The most links to create in this call. Defaults to 500.
recipientslist of objectsOptional
Where to email each link. A row you do not name still gets a link and a webhook, but no email.

Response

Success
mintedinteger
How many links this call created.
emailedinteger
How many of those links were accepted for delivery by email.
skippedobject
Rows in the grade that were deliberately passed over, by reason.
remaininginteger
Rows in the grade still waiting for a link. Call again to continue.
workflowobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error