Lookup endpoints
7 operations.
-
GET
/v1/lookup-endpoints -
POST
/v1/lookup-endpoints -
GET
/v1/lookup-endpoints/{lookup_endpoint_id} -
PATCH
/v1/lookup-endpoints/{lookup_endpoint_id} -
DELETE
/v1/lookup-endpoints/{lookup_endpoint_id} -
POST
/v1/lookup-endpoints/{lookup_endpoint_id}/rotate-secret -
POST
/v1/lookup-endpoints/{lookup_endpoint_id}/test
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
|