Identify: POST /identify

POST/api/v1/identify Public key

Submits a signal report collected by a client SDK. The response carries the complete verdict. There is no second call to make.

Headers

x-api-keystringrequired
A public key, or a secret key from a server.
Idempotency-Keystring
Up to 255 characters. Makes retries safe. See Idempotency.
Content-Encodingstring
gzip to send a compressed body.

Body

sdkobjectrequired
The SDK that collected the report.
2 child fields
- platformstring
  web, ios, android, or a bridge such as react-native-ios.
- versionstring
  The SDK version.
consentstringrequired
The consent state the SDK collected under. Must be granted; anything else, or no value, is refused with 422 consent_required. See privacy and consent.
signalsobjectrequired
The signal report the SDK collected. Its contents are produced by the SDKs and are not a public contract.
tagstring
Your own reference for this identification, echoed on the event and in webhooks.

Response

request_idstring
Identifies this identification. A UUIDv7.
deferred_tokenstring
A capability for sending this request's deferred report within 24 hours. Omitted on duplicates.
duplicateboolean
true when this Idempotency-Key was already answered. Only request_id is meaningful then.
visitor_idstring
The stable visitor identifier: 20 letters and digits. Always present on a new identification.
visitor_is_newboolean
Whether your organization is seeing this visitor for the first time.
identifiableboolean
false when the report carried too little to identify anyone. The request is still scored.
visitor_confidenceinteger
From 0 to 100. 100: seen before exactly. 85 to 99: recognised after the device changed. 0: a new visitor ID.
statestring
enriched, or unavailable when the network lookup could not run.
reasonstring
A short token explaining an unavailable state. Omitted otherwise.
suspect_scoreinteger
The weighted sum of the signals that fired. Omitted when the request was not scored, which is different from 0.
suspect_levelstring
low, medium or high, from your threshold.
triggersarray
Each signal that fired, heaviest first. Omitted when none did.
4 child fields
- signalstring
  The signal, such as tor or automation.
- groupstring
  The signal's group, such as bot for automation.
- weightinteger
  The weight the signal added, from the weights in force.
- confidencestring
  low, medium or high.

Response headers

Fingerly-Balance-Microsinteger
Your remaining balance in millionths of a US dollar. Reflects production traffic.
RateLimit-Limitinteger
Your organization's rate limit, per second.
RateLimit-Remaininginteger
What remained of the limit when the request was admitted.
Retry-Afterinteger
On 429, seconds to wait before retrying.

These headers can be read from browser JavaScript as well as from servers and proxies. A first-party proxy relays only the rate limit headers, never Fingerly-Balance-Micros.

Billing

A production identification costs $0.0025, falling to $0.0020 past 250,000 in a month and $0.0015 past a million; a request whose identifiable is false costs $0.0005 at every volume. Development and staging keys, duplicates, refused requests and requests whose state is unavailable are free. See billing.

Errors

Status	Code	When
`401`	`unauthorized`	The key did not authenticate from this origin or platform.
`401`	`proxy_key_missing`	A proxy forwarded visitor details without its proxy key.
`402`	`billing_blocked`	The organization is not accepting traffic.
`402`	`no_credit`	The balance is used up.
`413`	`payload_too_large`	The body is over 1 MiB.
`422`	`consent_required`	The body did not carry `consent` `granted`.
`422`	`idempotency_key_too_long`	The key is over 255 characters.
`422`	`invalid_visitor_metadata`	A proxy forwarded malformed visitor details.
`429`	`rate_limited`	Over the organization's rate limit.
`503`	`service_unavailable`	Retry with the same `Idempotency-Key`.