Skip to navigation
Identity verification APIAddress

Start a presence check

Starts a presence check on the captured address pin of the entity. The check observes, over a window of days, whether the device of the person is at the address, and then resolves.

Only one check can run per entity. A repeat call while one is running returns it with existing: true and status 200, so the call is safe to retry. The body is optional; unknown keys are ignored.

Side effects: a newly started check fires entity.address_presence_started, and its result fires entity.address_verified or entity.address_presence_failed. The call is recorded in your audit log. A check is billed once, when it resolves as verified or failed, in production only. A check that ends inconclusive is not billed. Outside production the observation window runs in minutes rather than days.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
entity_not_found404No live entity has this reference in this organisation and environment.
no_address_pin422The entity has no captured address pin. Collect one with the address step of a verification first.
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.
windowDaysintegerOptional3-30
How many days the check observes before it must resolve. Defaults to 10.
minNightsintegerOptional1-14
How many nights at the address verify it. Defaults to 3.
minDaysintegerOptional1-21
How many days of evidence verify it when nights are not available. Defaults to 5.
dwellFloorMinutesintegerOptional5-240
The shortest stay, in minutes, that counts as being at the address. Defaults to 30.

Response

A check was already running and is returned.
watchIdstring
The identifier of the presence check.
statusenum

The state of the check. A newly started check is MONITORING.

deadlineAtdatetime
When the check resolves at the latest.
existingboolean
True when a check was already running and was returned instead of starting another.

Errors

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