[{"data":1,"prerenderedAt":212},["ShallowReactive",2],{"doc:\u002Freference\u002Fidentify":3},{"page":4,"toc":207,"updated":211},{"path":5,"title":6,"seoTitle":7,"description":8,"blocks":9,"examples":178},"\u002Freference\u002Fidentify","Identify a visitor","Identify: POST \u002Fidentify","Submit an SDK signal report and receive the visitor ID, the suspect score and the signals behind it in the same response.",[10,15,18,22,37,57,62,116,131,133,136,138,141],{"type":11,"method":12,"path":13,"auth":14},"endpoint","POST","\u002Fapi\u002Fv1\u002Fidentify","public",{"type":16,"text":17},"p","Submits a signal report collected by a client SDK. The response carries the complete verdict. There is no second call to make.",{"type":19,"tone":20,"text":21},"callout","note","The client SDKs build and send this request for you. Call it directly only if you are writing your own transport, for example a proxy.",{"type":23,"title":24,"fields":25},"fields","Headers",[26,31,34],{"name":27,"type":28,"text":29,"required":30},"x-api-key","string","A public key, or a secret key from a server.",true,{"name":32,"type":28,"text":33},"Idempotency-Key","Up to 255 characters. Makes retries safe. See [Idempotency](\u002Freference\u002Fidempotency).",{"name":35,"type":28,"text":36},"Content-Encoding","`gzip` to send a compressed body.",{"type":23,"title":38,"fields":39},"Body",[40,51,54],{"name":41,"type":42,"text":43,"required":30,"children":44},"sdk","object","The SDK that collected the report.",[45,48],{"name":46,"type":28,"text":47},"platform","`web`, `ios`, `android`, or a bridge such as `react-native-ios`.",{"name":49,"type":28,"text":50},"version","The SDK version.",{"name":52,"type":42,"text":53,"required":30},"signals","The signal report the SDK collected. Its contents are produced by the SDKs and are not a public contract.",{"name":55,"type":28,"text":56},"tag","Your own reference for this identification, echoed on the event and in webhooks.",{"type":58,"level":59,"text":60,"id":61},"heading",2,"Response","response",{"type":23,"fields":63},[64,67,70,74,77,80,83,87,90,93,96,99],{"name":65,"type":28,"text":66},"request_id","Identifies this identification. A UUIDv7.",{"name":68,"type":28,"text":69},"deferred_token","A capability for sending this request's [deferred report](\u002Freference\u002Fdeferred-report) within 24 hours. Omitted on duplicates.",{"name":71,"type":72,"text":73},"duplicate","boolean","`true` when this `Idempotency-Key` was already answered. Only `request_id` is meaningful then.",{"name":75,"type":28,"text":76},"visitor_id","The stable visitor identifier: 20 letters and digits. Always present on a new identification.",{"name":78,"type":72,"text":79},"visitor_is_new","Whether your organization is seeing this visitor for the first time.",{"name":81,"type":72,"text":82},"identifiable","`false` when the report carried too little to identify anyone. The request is still scored.",{"name":84,"type":85,"text":86},"visitor_confidence","integer","From 0 to 100. `100`: seen before exactly. `85` to `99`: recognised after the device changed. `0`: a new visitor ID.",{"name":88,"type":28,"text":89},"state","`enriched`, or `unavailable` when the network lookup could not run.",{"name":91,"type":28,"text":92},"reason","A short token explaining an `unavailable` state. Omitted otherwise.",{"name":94,"type":85,"text":95},"suspect_score","The weighted sum of the signals that fired. Omitted when the request was not scored, which is different from `0`.",{"name":97,"type":28,"text":98},"suspect_level","`low`, `medium` or `high`, from your [threshold](\u002Fdocs\u002Fsuspect-score#levels).",{"name":100,"type":101,"text":102,"children":103},"triggers","array","Each signal that fired, heaviest first. Omitted when none did.",[104,107,110,113],{"name":105,"type":28,"text":106},"signal","The signal, such as `tor` or `automation`.",{"name":108,"type":28,"text":109},"group","The signal's group, such as `bot` for `automation`.",{"name":111,"type":85,"text":112},"weight","The weight the signal added, from the weights in force.",{"name":114,"type":28,"text":115},"confidence","`low`, `medium` or `high`.",{"type":23,"title":117,"fields":118},"Response headers",[119,122,125,128],{"name":120,"type":85,"text":121},"Fingerly-Balance-Micros","Your remaining balance in millionths of a US dollar. Reflects production traffic.",{"name":123,"type":85,"text":124},"RateLimit-Limit","Your organization's rate limit, per second.",{"name":126,"type":85,"text":127},"RateLimit-Remaining","What remained of the limit when the request was admitted.",{"name":129,"type":85,"text":130},"Retry-After","On `429`, seconds to wait before retrying.",{"type":16,"text":132},"These headers can be read from browser JavaScript as well as from servers and proxies.",{"type":58,"level":59,"text":134,"id":135},"Billing","billing",{"type":16,"text":137},"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](\u002Fdocs\u002Fbilling).",{"type":58,"level":59,"text":139,"id":140},"Errors","errors",{"type":142,"columns":143,"rows":147},"table",[144,145,146],"Status","Code","When",[148,152,156,159,163,167,170,174],[149,150,151],"`401`","`unauthorized`","The key did not authenticate from this origin or platform.",[153,154,155],"`402`","`billing_blocked`","The organization is not accepting traffic.",[153,157,158],"`no_credit`","The balance is used up.",[160,161,162],"`413`","`payload_too_large`","The body is over 1 MiB.",[164,165,166],"`422`","`idempotency_key_too_long`","The key is over 255 characters.",[164,168,169],"`invalid_visitor_metadata`","A proxy forwarded malformed visitor details.",[171,172,173],"`429`","`rate_limited`","Over the organization's rate limit.",[175,176,177],"`503`","`service_unavailable`","Retry with the same `Idempotency-Key`.",{"request":179,"response":196},[180,184,188,192],{"label":181,"lang":182,"code":183},"cURL","bash","curl -X POST \"https:\u002F\u002Fus.api.fingerly.io\u002Fapi\u002Fv1\u002Fidentify\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"x-api-key: fly_pk_us_production_…\" \\\n  -H \"Idempotency-Key: 7d5e1f2a-3c4b-4d6e-8f90-a1b2c3d4e5f6\" \\\n  -H \"Origin: https:\u002F\u002Fshop.example.com\" \\\n  -d '{\n    \"sdk\": { \"platform\": \"web\", \"version\": \"0.1.0\" },\n    \"signals\": { \"schema\": 1, \"…\": \"…\" },\n    \"tag\": \"checkout:8412\"\n  }'",{"label":185,"lang":186,"code":187},"JavaScript","ts","const result = await fingerly.identify({ tag: 'checkout:8412' })",{"label":189,"lang":190,"code":191},"Swift","swift","let result = try await fingerly.identify(tag: \"checkout:8412\")",{"label":193,"lang":194,"code":195},"Kotlin","kotlin","val result = fingerly.identify(tag = \"checkout:8412\")",[197,201,204],{"label":198,"lang":199,"code":200},"200","json","{\n  \"request_id\": \"01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4\",\n  \"deferred_token\": \"v1.eyJyZXF1ZXN0X2lkIjoi….…\",\n  \"visitor_id\": \"X9pL2mRc7KvT4bQw8NdF\",\n  \"visitor_is_new\": false,\n  \"identifiable\": true,\n  \"visitor_confidence\": 100,\n  \"state\": \"enriched\",\n  \"suspect_score\": 37,\n  \"suspect_level\": \"high\",\n  \"triggers\": [\n    {\n      \"signal\": \"tor\",\n      \"group\": \"tor\",\n      \"weight\": 14,\n      \"confidence\": \"high\"\n    },\n    {\n      \"signal\": \"automation\",\n      \"group\": \"bot\",\n      \"weight\": 9,\n      \"confidence\": \"medium\"\n    },\n    {\n      \"signal\": \"tampering\",\n      \"group\": \"browser_tampering\",\n      \"weight\": 8,\n      \"confidence\": \"medium\"\n    },\n    {\n      \"signal\": \"high_activity\",\n      \"group\": \"high_activity\",\n      \"weight\": 6,\n      \"confidence\": \"low\"\n    }\n  ]\n}",{"label":202,"lang":199,"code":203},"200 duplicate","{\n  \"request_id\": \"01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4\",\n  \"duplicate\": true\n}",{"label":205,"lang":199,"code":206},"429","{\n  \"error\": {\n    \"code\": \"rate_limited\",\n    \"message\": \"this organisation is sending faster than its rate limit allows\",\n    \"status\": 429\n  },\n  \"request_id\": \"01a0a84c-0f11-7a3e-9c2d-4b5e6f708192\"\n}",[208,209,210],{"id":61,"text":60,"level":59},{"id":135,"text":134,"level":59},{"id":140,"text":139,"level":59},"2026-09-17T16:57:52.000Z",1789667797854]