fingerlydocs
fingerly.io Log inDashboard
API reference

Submit from a client SDK

The one URL the client SDKs and every first-party proxy post to: an identification, or the deferred report that follows it, told apart by the body.

POST/api/v1/ingest Public key

The browser SDK posts both of its calls here: the identification, and the deferred report after it. A first-party proxy forwards everything it receives to this one URL without looking inside. Having one URL is what lets the SDK post to your proxy's path exactly as given, with nothing appended that a content blocker could match across sites. The iOS and Android SDKs, and the React Native, Flutter and Lynx packages over them, post their identifications here too, at /api/v1/ingest under the API origin they are configured with.

Telling the two apart

BodyHandled asAnswer
Has a tokenA deferred report. The request it belongs to comes from the signed token.202 with request_id, and duplicate when this exact report was already accepted.
No tokenAn identification.200 with the complete verdict, exactly as POST /identify answers.

Headers

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

Body

  • sdkobjectrequired
    The SDK's platform and 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. Produced by the SDKs and not a public contract.
  • tagstring
    On an identification, your own reference, echoed on the event and in webhooks.
  • tokenstring
    On a deferred report, the deferred_token from the identification's answer.

Responses

The identify response and its headers, or the deferred report response. Errors are those of the matching endpoint, with 422 invalid_supplement for a token that is not valid, and 422 consent_required for either kind of body without consent granted.

A request forwarded by a proxy, or sent to a hosted subdomain, is answered without Fingerly-Balance-Micros. A request that carries forwarded visitor headers without a proxy key is refused with 401 and proxy_key_missing.

Last updated