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 returns415withrequest.invalid_content_type. The one exception istext/plain, which the browser SDK uses to wrap its headers and JSON body so the browser skips a CORS preflight. Atext/plainbody that isn’t one of these wrapped requests returns400withrequest.invalid_transport_envelope.
Implementation notes:
- The default server sets an HTTP-only
__Host-sidcookie on this call. - A session can span page lifecycles; each creation response identifies the new active document.
- Treat
sessionIdas an opaque identifier. New sessions use thesid_...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 threePOST 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-KeyX-Batch-SeqContent-Type: application/octet-stream
fingerprint.
Results on the first batch
When the creation response includesfirstBatchResults: 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-KeyContent-Type: application/octet-stream
GET /v1/sessions/:sessionId as the secondary integration method.