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.
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"
}'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.
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 |
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.
{
"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"
}
}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.
Isolated sandbox data
Sandbox developer apps can seed synthetic survey, response, and contact objects isolated from production survey and participant tables.