fingerlydocs
fingerly.io Log inDashboard
API reference

Identify a visitor

Submit an SDK signal report and receive the visitor ID, the suspect score and the signals behind it in the same response.

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.
  • 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.

Billing

A production identification costs $0.003, or $0.0005 when identifiable is false. Development and staging keys, duplicates, refused requests and requests whose state is unavailable are free. See billing.

Errors

StatusCodeWhen
401unauthorizedThe key did not authenticate from this origin or platform.
402billing_blockedThe organization is not accepting traffic.
402no_creditThe balance is used up.
413payload_too_largeThe body is over 1 MiB.
422idempotency_key_too_longThe key is over 255 characters.
422invalid_visitor_metadataA proxy forwarded malformed visitor details.
429rate_limitedOver the organization's rate limit.
503service_unavailableRetry with the same Idempotency-Key.

Last updated