Skip to Content
IntegrationsServer API

Server API

Trigger surveys and manage targets from your backend using your project’s secret key. Unlike the dashboard and SDK APIs, this runs on its own binary with no browser-facing CORS, and the project is always resolved from the secret key — there’s no projectId in the URL.

Authentication

Every request requires a secret key (sk_...) in the Authorization header:

POST https://s2s-api.1sygnal.app/v1/surveys/{surveyId}/targets
Authorization: Bearer sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Content-Type: application/json

Secret keys are created from your project’s settings page (creating one requires a plan with Integrations enabled). A public key (pk_...) is rejected here — it can only authenticate the SDK. Never expose your secret key in client-side code; it grants write access to your project.

Base URL

https://s2s-api.1sygnal.app/v1

Add survey targets

Target specific users for a survey. Targeted users see the survey on their next page load regardless of trigger rules. Requires a plan with API-triggered surveys enabled.

POST /v1/surveys/{surveyId}/targets

Request body

FieldTypeRequiredDescription
userIdsstring[]One ofExternal user IDs (from identify()). Max 100.
userProfileIdsstring[]One ofInternal profile IDs. Max 100.
expiresAtstringNoISO 8601 timestamp. Target expires after this time.

Response

{ "added": 3, "notFound": ["user-xyz"] }

notFound lists any user IDs that couldn’t be resolved to a known profile.

Remove survey targets

DELETE /v1/surveys/{surveyId}/targets

Request body

FieldTypeRequiredDescription
userIdsstring[]One ofExternal user IDs. Max 100.
userProfileIdsstring[]One ofInternal profile IDs. Max 100.

Returns 204 No Content.

List survey targets

GET /v1/surveys/{surveyId}/targets?limit=50&cursor={cursor}

Response

{
  "data": [...],
  "nextCursor": "...",
  "hasMore": true,
  "total": 42
}

Errors

StatusCodeDescription
401UNAUTHORIZEDMissing Authorization header, or the key isn’t a valid, active sk_ secret key.
403FEATURE_NOT_AVAILABLEPlan doesn’t support API-triggered surveys.
404Survey not found, or doesn’t belong to the project resolved from your secret key.
400VALIDATION_ERRORInvalid request body (e.g., empty user list, > 100 users).
429Rate limit exceeded.

Rate limits

60 requests per minute per secret key. Rate limit headers are included in every response (X-RateLimit-Limit, X-RateLimit-Remaining).

Webhook signing with your secret key

When you add a webhook endpoint, 1Sygnal uses your project’s secret key as the HMAC signing key instead of generating a separate signing secret — creating one automatically if you don’t already have one (requires a plan with Integrations enabled; otherwise a whsec_... secret is generated instead). This means you verify webhook signatures with the same sk_... key you use for API calls. See Webhooks → Verifying the signature.

Privacy & ConsentWebhooks