Developer and integration center

Plan secure, observable survey integrations

SierraTec exposes a live application API and generated OpenAPI specification. V5.9 adds a versioned public /api/v1 compatibility layer for supported developer resources; internal application routes remain separate from that stable contract.

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.

MethodEndpointPurposeTypical scope
GET/v1/surveysList surveys with cursor pagination and updated-since filters.surveys:read
POST/v1/surveysCreate a draft survey under a workspace.surveys:write
POST/v1/surveys/{id}/publishPublish an approved survey version.surveys:publish
GET/v1/surveys/{id}/responsesRead responses under authorized filters and field controls.responses:read
POST/v1/exportsQueue an asynchronous, permission-checked export job.exports:create
GET/v1/jobs/{id}Read import, export, delivery, or analysis job status.jobs:read
POST/v1/webhooksRegister 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.

  1. Read the raw bodyDo not reserialize JSON before signature verification.
  2. Check timestampReject events outside the permitted replay window.
  3. Verify signatureUse constant-time comparison and the active signing secret.
  4. DeduplicateStore the event ID before running downstream effects.
  5. 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"
  }
}
Public API

Developer apps, OAuth consent, stable v1 resources, canonical webhooks

Build against the versioned public compatibility surface while keeping internal application routes free to evolve independently.

Developer applications

Create sandbox, staging, or production apps with explicit scopes, registered redirect URIs, one-time client secrets, OAuth authorization codes, and revocable access tokens.

Public API contract

covers surveys, responses, templates, integrations, export jobs, job status, and webhook management with normalized pagination, errors, and API metadata.

Webhook operations

Canonical envelopes include id, type, api_version, created_at, workspace_id, attempt, and data. Delivery history and deliberate replay are part of the contract.

Rate-aware

Authenticated public API responses expose rate-limit metadata; 429 responses include Retry-After.

Release-pinned specification

JSON · YAML · live /openapi.json

Isolated sandbox data

Sandbox developer apps can seed synthetic survey, response, and contact objects isolated from production survey and participant tables.