Skip to navigation
Identity verification APIAddress

Decline a presence check

Declines the latest presence check of the entity, running or ended because its time ran out, because your team decided it should not stand. The check becomes DECLINED, and then chooses what happens next:

  • fail (the default): a workflow waiting on the check fails. Workflow rules read address.presenceStatus as failed (and address.presenceDeclined as true), so the verification is declined. To check the customer again later, use /restart.
  • restart: a fresh check starts on the same pin at once, with the same settings. A workflow waiting on the old check keeps waiting and decides on the new one; its wait is held open until the new check can answer. A check whose time already ran out has settled its workflow, so restarting it starts a check no workflow reads.

A decline is your decision, not evidence: it is not billed, and no entity.address_verified or entity.address_presence_failed follows for the declined check. Fires entity.address_presence_declined (with restarted), and on a restart also entity.address_presence_started with startedVia: "restart". The call is recorded in your audit log with the note.

Error codes

errorStatusMeaning
note_required422The note is missing or shorter than 10 characters.
watch_not_found404The entity does not exist or has no presence check.
already_verified409The check is already verified.
integrity_failure409The check failed on tampered location reports.
not_declinable409Only a running check, or one that ended because its time ran out, can be declined.
stopped409The check was stopped.
superseded409The entity has a newer check.
another_check_running409With then: restart: another check is already running for the entity. Nothing was declined.
state_changed409The check changed while it was being declined. Nothing was declined.
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

externalUserIdstringRequired
Your own stable reference for the person or business, as sent when the entity was registered.

Request

This endpoint expects an object.
notestringRequired
Why the check is declined, at least 10 characters. Kept in your audit log, never sent to webhooks.
thenenumOptional

What happens next. fail (the default) fails a workflow waiting on the check, so the verification is declined. restart starts a fresh check on the same pin at once; a workflow waiting on the old check keeps waiting and decides on the new one.

Allowed values:

Response

Success
watchIdstring
The identifier of the presence check.
declinedboolean
Always true.
previousStatusenum
What the check was before it was declined.
Allowed values:
thenenum
What the decline did next.
Allowed values:
restartedWatchIdstring or null

The fresh check, when then is restart.

restartedDeadlineAtdatetime or null

When the fresh check must decide by, when then is restart.

workflowsWaitinginteger

How many workflows now wait on the fresh check. Always 0 unless then is restart.

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error