Skip to main content
These endpoints power the protocol that t.js and the iOS and Android SDKs use. In most integrations, you should not call them directly from application code. They live under /v2/collect/, separately from the /v1/ REST API.
The request bodies for batch and result endpoints use encrypted binary payloads and session-bound integrity checks. The supported public integration surface is the browser SDK, not manual construction of these transport messages.

Endpoint summary

GET /v2/collect/pings/:pingId

Used for timing measurement during session setup.
  • Authentication: none
  • Path parameter: pingId
  • Response: 204 No Content

POST /v2/collect/sessions

Creates or resumes a short-lived unified session and creates a document for the current page lifecycle.
  • Authentication: Authorization: Bearer pk_*
  • Content type: application/json. A request with a body of any other content type returns 415 with request.invalid_content_type. The one exception is text/plain, which the browser SDK uses to wrap its headers and JSON body so the browser skips a CORS preflight. A text/plain body that isn’t one of these wrapped requests returns 400 with request.invalid_transport_envelope.
Example response:
Implementation notes:
  • The default server sets an HTTP-only __Host-sid cookie on this call.
  • A session can span page lifecycles; each creation response identifies the new active document.
  • Treat sessionId as an opaque identifier. New sessions use the sid_... format, while legacy hex IDs are still accepted.
  • Native publishable keys are accepted on this endpoint only from the matching iOS or Android SDK. See Authentication.

Requests without a CORS preflight

A cross-origin request that sets its own headers waits for a CORS preflight, which adds a network round trip before the request itself. To avoid it, the browser SDK can send the three POST endpoints as Content-Type: text/plain with no other headers except Accept, and carry the headers in the body instead. Each endpoint accepts both forms, and a request must use only one of them. The body is an envelope: The header block can contain authorization, content-type, x-client-key, x-batch-seq, x-foil-sdk-version, x-foil-bundle-hash, and x-foil-client-attempt-id. It must contain content-type, which is application/json for session creation and application/octet-stream for batches and results. Each name follows the rules of the header it replaces. An envelope that is malformed, names any other header, or repeats a header that the request also sends returns 400 with request.invalid_transport_envelope. The SDK always sends session creation this way, and sends it again in the header form if the API answers 401. It sends batches and results this way only when the creation response includes simplePostVersion: 1, and then uses the document URLs rather than the shared session URL.

POST /v2/collect/sessions/:sessionId/documents/:documentId/batches

Submits encrypted observation batches for the current session.
  • Authentication: Authorization: Bearer pk_*
  • Required headers:
    • X-Client-Key
    • X-Batch-Seq
    • Content-Type: application/octet-stream
Example response:
For the first snapshot batch, the response also includes the fingerprint-ready payload shown above under fingerprint.

Results on the first batch

When the creation response includes firstBatchResults: true and the page is already waiting on getSession(), the browser SDK puts its results request inside the first snapshot batch. The response then also includes handoff, the body the results endpoint below returns, and getSession() resolves from it without a second request. When handoff is missing, the SDK sends the results request as usual. A page that hasn’t called getSession() never sends results this way. Possible failure cases include invalid sequence numbers (session.sequence_mismatch), invalid sessions (session.invalid_or_expired), and transport.session_reset_required. The last is a 409 with retryable set to true, and the client recovers by starting a new session. Example transport error:

POST /v2/collect/sessions/:sessionId/documents/:documentId/results

Requests a fresh sealed handoff for the accumulated session data.
  • Authentication: Authorization: Bearer pk_*
  • Required headers:
    • X-Client-Key
    • Content-Type: application/octet-stream
Responses include:
The public browser transport never returns verdicts, scores, phases, categories, or visitor IDs. Verify the sealed token locally on your backend or use GET /v1/sessions/:sessionId as the secondary integration method.