API reference

Lookup endpoints

7 operations.

GET /v1/lookup-endpoints

The account's lookup endpoints, oldest first. Never a signing secret.

Operation id
listLookupEndpoints
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Answers

200 The endpoints. application/json

Field Type Always sent Notes
lookup_endpoints array of object yes
lookup_endpoints[] object yes
lookup_endpoints[].id string yes
lookup_endpoints[].name string yes
lookup_endpoints[].purpose string yes Values: identify_visitor , pick_owner , block_check .
lookup_endpoints[].url string yes The address as checked and stored, in its canonical form.
lookup_endpoints[].timeout_ms integer yes
lookup_endpoints[].on_failure string yes Values: fail_closed , fail_open .
lookup_endpoints[].is_active boolean yes
lookup_endpoints[].previous_secret_expires_at string or null yes While the old secret still works after a rotation, when it stops. Requests carry a signature with each secret until then. Limits: format date-time.
lookup_endpoints[].version integer yes
lookup_endpoints[].created_at string yes Limits: format date-time.
lookup_endpoints[].updated_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
429 Too many attempts. rate_limited

POST /v1/lookup-endpoints

Adds a lookup endpoint, switched on, and answers its signing secret once. The address is checked as written and through DNS; a refused address answers 400 with a reason.

Operation id
createLookupEndpoint
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.manage
Retry key
Optional: send an Idempotency-Key header.
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Parameters

Name In Type Required Notes
Idempotency-Key header string no Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
name string yes A label, such as the system that answers.
purpose string yes Values: identify_visitor , pick_owner , block_check .
url string yes An https address on a public host, refused and checked again before every call exactly as a webhook endpoint's address is. Limits: 1 to 2048 characters.
timeout_ms integer no The whole step's budget in milliseconds: the address check, the call, one retry and reading the answer. Default 2000. A call or a retry starts only with at least the smaller of 250 ms and a quarter of the budget left. Limits: at least 100, at most 10000.
on_failure string no What a failed lookup does. fail_closed: the visitor is asked to try again and nothing is stored. fail_open: the step goes on as if nothing was found, and the failure raises an alert; a failed check never permits what another check refuses. A new endpoint starts with fail_closed for pick_owner and fail_open for block_check. Values: fail_closed , fail_open .

Answers

201 The endpoint, with its signing secret. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
name string yes
purpose string yes Values: identify_visitor , pick_owner , block_check .
url string yes The address as checked and stored, in its canonical form.
timeout_ms integer yes
on_failure string yes Values: fail_closed , fail_open .
is_active boolean yes
previous_secret_expires_at string or null yes While the old secret still works after a rotation, when it stops. Requests carry a signature with each secret until then. Limits: format date-time.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.
secret string or null yes The signing secret, whsec_ and base64, shown this once (Standard Webhooks). Null on a repeat of the same request (same Idempotency-Key): rotate it to get a new one.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
409 The same identifier was already used for a different request. This request is already running. id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/lookup-endpoints/{lookup_endpoint_id}

One lookup endpoint with its recent outcomes by kind. Never its signing secret, never a request or an answer.

Operation id
getLookupEndpoint
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
lookup_endpoint_id path string yes Limits: pattern ^lkp_[0-9a-z]{26}$.

Answers

200 The endpoint. application/json

Field Type Always sent Notes
id string yes
name string yes
purpose string yes Values: identify_visitor , pick_owner , block_check .
url string yes The address as checked and stored, in its canonical form.
timeout_ms integer yes
on_failure string yes Values: fail_closed , fail_open .
is_active boolean yes
previous_secret_expires_at string or null yes While the old secret still works after a rotation, when it stops. Requests carry a signature with each secret until then. Limits: format date-time.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.
recent_outcomes array of object yes What the lookups of the last 7 UTC days came to, by kind, newest day first. Test calls are not counted.
recent_outcomes[] object yes
recent_outcomes[].day string yes The UTC day, as YYYY-MM-DD.
recent_outcomes[].kind string yes answered, or why the lookup failed: address_refused, could_not_check, timeout, http_status, redirect, network_error, not_json, too_large, no_result, unknown_owner. Values: answered , address_refused , could_not_check , timeout , http_status , redirect , network_error , not_json , too_large , no_result , unknown_owner .
recent_outcomes[].count integer yes
recent_outcomes[].last_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
429 Too many attempts. rate_limited

PATCH /v1/lookup-endpoints/{lookup_endpoint_id}

Changes a lookup endpoint's name, address, budget or failure setting, or switches it on or off. Send the version you read. The purpose never changes. A new address, and switching an endpoint on, check the address again.

Operation id
updateLookupEndpoint
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.manage
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Parameters

Name In Type Required Notes
lookup_endpoint_id path string yes Limits: pattern ^lkp_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
name string no A label, such as the system that answers.
url string no An https address on a public host, refused and checked again before every call exactly as a webhook endpoint's address is. Limits: 1 to 2048 characters.
timeout_ms integer no The whole step's budget in milliseconds: the address check, the call, one retry and reading the answer. Default 2000. A call or a retry starts only with at least the smaller of 250 ms and a quarter of the budget left. Limits: at least 100, at most 10000.
on_failure string no What a failed lookup does. fail_closed: the visitor is asked to try again and nothing is stored. fail_open: the step goes on as if nothing was found, and the failure raises an alert; a failed check never permits what another check refuses. A new endpoint starts with fail_closed for pick_owner and fail_open for block_check. Values: fail_closed , fail_open .
is_active boolean no false switches it off: an owner lookup rule naming it goes on to the next rule, and no booking is checked against it. true switches it on and checks its address again.

Answers

200 The endpoint after the change. application/json

Field Type Always sent Notes
id string yes
name string yes
purpose string yes Values: identify_visitor , pick_owner , block_check .
url string yes The address as checked and stored, in its canonical form.
timeout_ms integer yes
on_failure string yes Values: fail_closed , fail_open .
is_active boolean yes
previous_secret_expires_at string or null yes While the old secret still works after a rotation, when it stops. Requests carry a signature with each secret until then. Limits: format date-time.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/lookup-endpoints/{lookup_endpoint_id}

Deletes a lookup endpoint. Send the version you read. An endpoint a routing rule names is refused (409 lookup_in_use): change the rule first, or switch the endpoint off.

Operation id
deleteLookupEndpoint
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.manage
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
lookup_endpoint_id path string yes Limits: pattern ^lkp_[0-9a-z]{26}$.
version query integer yes Limits: at least 1.

Answers

204 The endpoint has been deleted.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
429 Too many attempts. rate_limited

POST /v1/lookup-endpoints/{lookup_endpoint_id}/rotate-secret

Replaces the signing secret and answers the new one once. Send the version you read. By default the old secret keeps working for 24 hours and requests carry both signatures.

Operation id
rotateLookupSecret
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.manage
Assistant tool
No. It mints a capability, credential or secret that outlives the grant and is later checked against the member's full role (decision 0043, point 8).

Parameters

Name In Type Required Notes
lookup_endpoint_id path string yes Limits: pattern ^lkp_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
keep_previous boolean no Default true: the old secret keeps working for 24 hours, and requests carry both signatures. false: it stops at once, for a secret that leaked.

Answers

200 The endpoint, with its new signing secret. application/json

Field Type Always sent Notes
id string yes
name string yes
purpose string yes Values: identify_visitor , pick_owner , block_check .
url string yes The address as checked and stored, in its canonical form.
timeout_ms integer yes
on_failure string yes Values: fail_closed , fail_open .
is_active boolean yes
previous_secret_expires_at string or null yes While the old secret still works after a rotation, when it stops. Requests carry a signature with each secret until then. Limits: format date-time.
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.
secret string or null yes The signing secret, whsec_ and base64, shown this once (Standard Webhooks). Null on a repeat of the same request (same Idempotency-Key): rotate it to get a new one.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

POST /v1/lookup-endpoints/{lookup_endpoint_id}/test

Calls the endpoint now with synthetic input (operation test), signed and timed exactly like a real lookup, and answers the parsed answer or why it failed. Nothing is stored, counted or retried beyond the one retry a lookup makes, and the failure setting is not applied. An answer larger than 16 KB fails.

Operation id
testLookupEndpoint
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
lookups.manage
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Parameters

Name In Type Required Notes
lookup_endpoint_id path string yes Limits: pattern ^lkp_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
email string no The visitor's email the test sends. Left out, the request has none. Limits: at most 254 characters.
phone string no The visitor's phone number the test sends, in international form. Limits: at most 40 characters.

Answers

200 How the test went. application/json

Field Type Always sent Notes
request_id string yes The request's id, also its webhook-id header.
outcome string yes answered with the parsed answer, or why the lookup failed. Values: answered , address_refused , could_not_check , timeout , http_status , redirect , network_error , not_json , too_large , no_result , unknown_owner .
answer one of 2 shapes or null yes The answer as the product read it. Null when the lookup failed.
answer{variant 1} object yes Shape 1 of 2.
answer{variant 1}.blocking boolean yes
answer{variant 1}.person_ref string or null yes
answer{variant 2} object yes Shape 2 of 2.
answer{variant 2}.outcome string yes Values: owner , no_owner .
answer{variant 2}.owner_ref string or null yes
answer{variant 2}.owner_external object or null yes The owner as an id in another system, when the answer named it that way instead of by owner_ref. A test does not map it to a host.
answer{variant 2}.owner_external.system string yes
answer{variant 2}.owner_external.external_id string yes
answer{variant 2}.person_ref string or null yes
http_status integer or null yes
duration_ms integer yes
attempts integer yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited