Developer and integration center

Plan secure, observable survey integrations

Review conceptual API, webhook, authentication, import, export, SSO, SCIM, and automation patterns for the SierraTec Survey product. The downloadable files are implementation examples, not a live production API contract.

Explore API patterns Open prototype OpenAPI

Example API request

curl --request POST \
  --url https://api.example.survey.sierratecsecure.com/v1/surveys \
  --header 'Authorization: Bearer $SIERRATEC_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f6b2d6e-...' \
  --data '{
    "title": "Customer onboarding feedback",
    "workspace_id": "ws_demo_001"
  }'

Implementation principles

Design integrations for least privilege, safe retries, and clear ownership

Scoped credentials

Separate environments, restrict access, rotate secrets, and never place private tokens in browser code.

Idempotent writes

Use stable event IDs and idempotency keys so retries do not create unintended duplicate effects.

Rate-aware clients

Respect rate headers, back off with jitter, persist cursors, and resume safely after partial failure.

Observable operations

Log correlation IDs, monitor delivery, protect sensitive data, and maintain clear support runbooks.

REST API concept

Core resources and workflow endpoints

A production contract should be versioned, documented in OpenAPI, tested for backward compatibility, and governed by plan entitlements.

Method	Endpoint	Purpose	Typical scope
GET	`/v1/surveys`	List surveys with cursor pagination and updated-since filters.	`surveys:read`
POST	`/v1/surveys`	Create a draft survey under a workspace.	`surveys:write`
POST	`/v1/surveys/{id}/publish`	Publish an approved survey version.	`surveys:publish`
GET	`/v1/surveys/{id}/responses`	Read responses under authorized filters and field controls.	`responses:read`
POST	`/v1/exports`	Queue an asynchronous, permission-checked export job.	`exports:create`
GET	`/v1/jobs/{id}`	Read import, export, delivery, or analysis job status.	`jobs:read`
POST	`/v1/webhooks`	Register a signed event destination.	`webhooks:manage`

Signed webhooks

Verify before processing

A production webhook should include a unique event ID, timestamp, type, workspace context, versioned payload, and signature. Consumers should reject stale or invalid signatures and deduplicate before applying changes.

Read the raw bodyDo not reserialize JSON before signature verification.
Check timestampReject events outside the permitted replay window.
Verify signatureUse constant-time comparison and the active signing secret.
DeduplicateStore the event ID before running downstream effects.
Acknowledge quicklyReturn success and process longer work asynchronously.

Webhook event example

{
  "id": "evt_demo_01H...",
  "type": "response.completed",
  "created_at": "2026-08-05T14:42:18Z",
  "workspace_id": "ws_demo_001",
  "data": {
    "survey_id": "sv_demo_123",
    "response_id": "rsp_demo_456",
    "status": "completed"
  }
}

Identity and data movement