Request/Response Format

All customer endpoints share common request/response conventions. Beyond endpoint-specific schemas, this page documents the format and behavior that applies to every call.

https://live-activity.api.useinsider.com

All customer endpoints live under the /api/v1/live-activity/ prefix.

Headers

Required headers on customer endpoints are as follows:

The token collection/synchronization flows the Insider One’s Mobile SDK runs in the background use a different auth model and are not called directly by the customer.

Request body

• All customer endpoints accept a JSON body.

• Requests without the Content-Type: application/json header are rejected with a 400 response.

• If the body cannot be parsed, a 400 BAD_REQUEST response is returned.

• An empty body is forbidden. At least one field is required on every endpoint. An empty body returns a 400 REQUEST_INVALID response.

Success response

Successful responses return with HTTP 200. Every endpoint has its own response schema. The common field is as follows:

{
  "status": "success",
  ...
}

status is always "success" in success responses.

Error response envelope

All error responses use the following standard structure:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "skipped": { ... },
  "gdpr_denied_details": [ ... ]
}

Some 401 and 503 responses may have an empty body when returned directly by Insider One's authorization layer. In that case, only look at the HTTP status code.

Authentication errors

All 401/503 responses return an empty body. Only the HTTP status code is meaningful. To resolve, renew your API key.

Rate limit

Your rate limit buckets are separate per endpoint:

• 1,000/min for /register

• 1,000/min for /start

• 1,000/min for /update

• 1,000/min for /end

On overflow, apply a short-lived exponential backoff on the client. No retry header is returned. If the flow remains stuck, contact the Insider One team.

Server-side errors

If a transient error occurs on Insider One's side, refer to the following options.

Retry is safe on idempotent endpoints (/register, /update). /start and /end are not idempotent. Check the lifecycle rules before retrying.

Keep in mind

• All timestamp fields are in RFC 3339 format. E.g., 2026-05-20T10:00:00Z.

• activity_id is always generated by Insider One (UUID v4). The customer cannot include it in the request; any activity_id field sent is ignored.

• Response field order is not guaranteed. Parse the JSON and read fields by name.

• omitempty fields: Some response fields are only returned when they have meaningful values (partial, skipped_not_synced, gdpr_denied_details, unprocessed_insider_id_count). Assume the missing field is false or 0.