SDK endpoints - Insito

The SDK wraps these endpoints into idiomatic mobile code. If you’re integrating from a platform we don’t have an SDK for yet (Flutter, Swift, Kotlin, web), call these directly. Base URL: https://api.insito.app/v1/sdk. See Authentication for the Bearer proj_xxx header.

`POST /identify`

Idempotent upsert of a respondent. Call once when your user signs in or as early as you have a stable userId.

Request

{
  "userId": "user-123",        // required, your stable identifier
  "platform": "ios",            // optional
  "appVersion": "2.7.0",        // optional
  "metadata": { "cohort": "beta-q2" }, // optional device metadata
  "properties": {                // optional custom user properties
    "plan": "premium",           // string | number | boolean values only
    "transactionsThisMonth": 14,
    "hasLinkedCard": true
  },
  "events": [                    // optional, declare trigger events
    { "name": "checkout_completed", "description": "User finished a purchase" }
  ],
  "screens": [                   // optional, declare screens
    { "name": "Checkout" }
  ]
}

Response

{
  "respondentId": "550e8400-e29b-41d4-a716-446655440000"
}

Idempotent on (project_id, userId) — calling again with the same userId updates platform, appVersion, metadata, properties, and last_seen_at but doesn’t create a new respondent. properties are custom, business-level user attributes (only string / number / boolean values are kept). They’re stored on the respondent and discovered into the project’s User Properties registry, where they become type-aware audience filters. The API stores exactly the metadata object you send. Our SDKs merge device metadata (locale, timezone, osVersion, sessionCount, daysSinceInstall) into metadata before calling this endpoint; if you call it directly, send those keys yourself to use them in audience filters. events and screens (each up to 200 items, name 1–256 chars, optional description ≤ 500 chars) register entries in the project’s App Variable Registry as declared (source sdk_init). They flip to verified once the SDK actually fires them. Auto-discovered events/screens are registered automatically by POST /event and POST /screen-map — you only need these fields to pre-declare variables before they’re first seen.

`POST /event`

Trigger evaluation. Decides whether to show a survey.

Request

{
  "event": "checkout_completed",  // required string, 1–128 chars (snake_case by convention)
  "userId": "user-123"             // required
}

Response (no survey)

{ "survey": null }

Reasons: user not yet identified, no active survey for this trigger, user is within the throttle window, plan is exhausted, or response limit reached on the survey.

Response (survey shown)

{
  "survey": {
    "surveyId": "uuid",
    "logic": {},
    "showBranding": true,
    "showQuestionNumbers": true,
    "allowBack": true,
    "autosaveProgress": true,
    "delaySeconds": 3,
    "questions": [
      {
        "id": "uuid",
        "type": "nps",
        "text": "How likely are you to recommend us?",
        "options": null,
        "settings": null,
        "isRequired": true,
        "position": 0
      }
    ]
  },
  "brandConfig": {
    "themeMode": "auto",
    "colors": { "primary": "#FF6B35", "background": null, "surface": null, "textPrimary": null, "textSecondary": null, "border": null },
    "colorsDark": { "primary": "#FF8A5C", "background": null, "surface": null, "textPrimary": null, "textSecondary": null, "border": null },
    "typography": { "fontFamily": "Inter", "questionSize": "medium", "bodySize": "medium", "questionWeight": "bold" },
    "shape": { "borderRadius": 12 },
    "spacing": "default",
    "branding": { "showPoweredBy": true, "logoUrl": null }
  },
  "labels": {
    "next": "Continue",
    "npsLowLabel": "Not likely",
    "npsHighLabel": "Very likely"
  }
}

Survey-level flags control the modal UX:

Field	Default	Notes
`showBranding`	`true`	Footer “Powered by Insito”. Forced on Free/Starter.
`showQuestionNumbers`	`true`	Progress labels like `Question 1 of 3`.
`allowBack`	`true`	Back button in the footer when not on the first step.
`autosaveProgress`	`true`	When `true`, partial answers are saved via `/responses`.

The survey object also carries logic (branching rules between questions, {} when none) and, when the trigger defines a delay, delaySeconds (wait this long after qualifying before showing). Each question includes a settings object with type-specific configuration (scale bounds, screen copy, etc.), or null. brandConfig (INS-103) is the project’s Brand Kit. It is only present when the project has saved a Brand Kit — projects with no Brand Kit omit the key entirely, and the SDK keeps the theme from init(). Returned by both /event and /evaluate. null colours / borderRadius / fontFamily mean “inherit the SDK preset”. branding.showPoweredBy is forced to true below the Growth plan. The SDK applies it on top of the base preset but below any init() overrides (code wins over the dashboard). themeMode (INS-104) is "light", "dark", or "auto". auto follows the device appearance (Appearance.getColorScheme()) and switches live while the modal is open. colorsDark is the dark-scheme palette, applied only when dark is resolved; null tokens inherit the SDK dark preset. labels (INS-135) are the project’s SDK UI label overrides. Like brandConfig, the key is only present when the project has overridden at least one label — and only the overridden keys are included. Returned by both /event and /evaluate. The SDK merges them over its built-in defaults and below any init({ labels }) overrides (code wins over the dashboard). See SDK labels for the full key list. options shape per question type:

nps: null — score is always 0–10
rating: { "max": 5 }
multiple_choice: { "choices": ["A", "B", "C"], "multiSelect": false }
open_text: { "maxLength": 500 }

`POST /evaluate`

Auto-evaluated trigger check. Unlike /event (named events), the SDK calls this for lifecycle triggers — app open, session start, and screen visit — reporting its local per-user counters so the server can match thresholds, audience filters, and frequency caps.

Request

{
  "userId": "user-123",              // required
  "currentScreen": "/checkout",       // optional; required for screen-visit triggers
  "contextType": "screen_visit",      // optional: "app_open" | "session_start" | "screen_visit"
  "coldStart": false,                 // optional; lets cold-start-only session triggers qualify
  "counters": {                       // optional local counters
    "appOpenCount": 12,
    "sessionCount": 8,
    "screenVisits": { "/checkout": 3 }
  },
  "properties": { "plan": "premium" } // optional
}

Response

Same shape as POST /event — { "survey": null } or a survey object (optionally with brandConfig and labels). The SDK follows a matched survey with POST /impression just like the named-event flow.

`POST /impression`

Records that a survey was shown to a user. Sets the per-user throttle window in Redis. The SDK fires this right after rendering the modal — don’t call it from a wait, did the user see it? position.

Request

{
  "surveyId": "uuid",  // from the previous /event call
  "userId": "user-123"
}

Response

{ "ok": true }

Internal note: Redis failures here are non-fatal (the data row is written either way). The throttle key just has a slightly delayed TTL when Redis is unhealthy.

`POST /responses`

Create or upsert a partial response while autosave is enabled. The SDK calls this as the user advances through questions.

Request

{
  "surveyId": "uuid",
  "userId": "user-123",
  "answers": [
    { "questionId": "uuid", "type": "nps", "value": 9 }
  ],
  "platform": "ios",
  "appVersion": "2.7.0"
}

Response

{ "responseId": "550e8400-...", "status": "partial" }

Returns 201 when it creates the partial row (which counts against the app’s monthly quota) and 200 when it updates the existing one — it’s idempotent per (survey, respondent) while status is partial. Returns 400 autosave_disabled if the survey has autosave turned off, 404 if the survey or respondent is unknown, and 402 response_limit_reached if the app is over its cap.

`PATCH /responses/:id`

Replace the answers on an existing partial response by its id.

Request

{
  "surveyId": "uuid",
  "userId": "user-123",
  "answers": [
    { "questionId": "uuid", "type": "open_text", "value": "Great app!" }
  ],
  "platform": "ios",
  "appVersion": "2.7.0"
}

Response

{ "responseId": "550e8400-...", "status": "partial" }

`POST /response`

Submit the user’s answers. Counts against your plan. Completes a partial response when responseId is supplied.

Request

{
  "surveyId": "uuid",
  "userId": "user-123",
  "responseId": "550e8400-...",
  "answers": [
    { "questionId": "uuid", "type": "nps", "value": 9 },
    { "questionId": "uuid", "type": "open_text", "value": "Love it!" }
  ],
  "platform": "ios",
  "appVersion": "2.7.0"
}

Omit responseId for a one-shot submit (no prior partial row).

Response (success)

{ "responseId": "550e8400-..." }

Response (plan exhausted)

{
  "error": "response_limit_reached",
  "upgradeUrl": "https://app.insito.io/settings/billing",
  "projectId": "550e8400-..."
}

Status 402 Payment Required (upgradeUrl and projectId are top-level, not nested). The SDK surfaces this as a response_failed event with reason: "response_limit_reached".

Answer `value` shapes

Question type	`value`
`nps`	Integer 0..10
`rating`	Integer 1..5
`multiple_choice` (single)	String matching one of `options.choices`
`multiple_choice` (multi)	Array of strings
`open_text`	String, ≤ `options.maxLength`

`POST /screen-map`

Batch upsert of screen visits. The SDK aggregates locally for ~60s then flushes here. Send null or omit if you don’t use screen tracking.

Request

{
  "screens": {
    "/home": 12,
    "/settings": 3,
    "/checkout/success": 1
  }
}

Up to 200 paths per call.

Response

{ "ok": true }

Cross-cutting

All SDK endpoints (GET /me, POST /identify, POST /event, POST /evaluate, POST /impression, POST /responses, PATCH /responses/:id, POST /response, POST /screen-map):

Authenticate with Authorization: Bearer proj_xxx.
Share the 120 req/min per-key rate limit (see Authentication).
Take a JSON body (Content-Type: application/json).
Validate with zod — a 400 returns { "error": "bad_request", "issues": [{ "path": "...", "message": "..." }] }.
Return { "error": "internal_error" } with status 500 on database failures.

OpenAPI

We’re publishing a full OpenAPI 3.1 spec — track [INS-…] for the schedule. Right now this page is the canonical reference.

​POST /identify

​Request

​Response

​POST /event

​Request

​Response (no survey)

​Response (survey shown)

​POST /evaluate

​Request

​Response

​POST /impression

​Request

​Response

​POST /responses

​Request

​Response

​PATCH /responses/:id

​Request

​Response

​POST /response

​Request

​Response (success)

​Response (plan exhausted)

​Answer value shapes

​POST /screen-map

​Request

​Response

​Cross-cutting

​OpenAPI

`POST /identify`

Request

Response

`POST /event`

Request

Response (no survey)

Response (survey shown)

`POST /evaluate`

Request

Response

`POST /impression`

Request

Response

`POST /responses`

Request

Response

`PATCH /responses/:id`

Request

Response

`POST /response`

Request

Response (success)

Response (plan exhausted)

Answer `value` shapes

`POST /screen-map`

Request

Response

Cross-cutting

OpenAPI