Survey responses, wherever you need them.
Read responses, subscribe to webhooks, and query declared customer properties from your own systems. Built for teams whose stack extends past Shopify and Klaviyo.
What the API covers.
Signals already syncs to Shopify, Klaviyo, and Compass without any code. The API is for everything else.
Response events
Read survey and Spark responses as structured events, including the question, the answer value, the survey version, and the resolved customer identity where one exists.
Webhooks
Subscribe to response, completion, and abandonment events and receive them at your own endpoint as they happen, rather than polling for changes.
Customer properties
Read the declared properties Signals maintains on a Signal profile, and look them up by Shopify customer ID or email.
Authentication
Scoped API keys issued per store, sent as a bearer token. Keys are scoped to read or write and can be rotated without downtime.
Rate limits
Per-key request limits with standard rate limit headers on every response, so a client can back off before it is throttled.
SDK
A typed client for JavaScript and TypeScript covering authentication, pagination, webhook signature verification, and retries.
The events you can subscribe to.
Available as webhook deliveries or as a readable event stream. Names shown are illustrative of the shape — the documentation carries the authoritative list and payload schemas.
survey.response.created A single answer was submitted. Fires per question for progressive surveys, so you see partial progress.
survey.completed The respondent reached the end of a survey. Carries the full answer set and the resolved customer.
survey.abandoned A started survey went idle past the abandonment window. Useful for recovery flows.
spark.answered A one-question Spark was answered, wherever it was published.
profile.property.updated A declared property changed on a Signal profile, including the previous value.
survey.published A survey moved from draft to live. Useful for change auditing and deploy notifications.
Keys, scopes, and back-off.
Authentication
API keys are issued per store from the Signals admin and sent as a bearer token on every request. Keys carry a read or write scope, can be rotated without interrupting an existing key, and are revocable immediately. A key only ever grants access to the store that issued it — tenant isolation is enforced at the data layer, not just in the token.
Authorization: Bearer sk_live_<your_key>
Content-Type: application/jsonNever expose a key in client-side code. Use a server-side proxy for browser or storefront access.
Rate limits
Limits are applied per API key over a rolling window. Every response includes the current limit, the requests remaining, and the reset time, so a well-behaved client never needs to be throttled to discover the ceiling. A 429 response includes a retry hint — honour it rather than retrying immediately.
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After (on 429 only)Prefer webhooks over polling. Most rate limit problems are a polling loop that should have been a subscription.
How the API behaves.
Request and response
- REST over HTTPS, JSON request and response bodies, UTF-8 throughout.
- Cursor-based pagination — pass the cursor from the previous page rather than an offset.
- All timestamps are ISO 8601 in UTC. There is no local-time variant.
- Resource identifiers are opaque strings. Do not parse them or assume a format.
- Additive changes ship without a version bump; breaking changes get a new version and a deprecation window.
- Every response carries a request ID — include it when you contact support.
Webhook handling
- Every delivery is signed. Verify the signature before you trust the payload.
- Delivery is at-least-once, so make your handler idempotent on the event ID.
- Respond with a 2xx quickly and do the real work asynchronously.
- Failed deliveries are retried with exponential backoff before the endpoint is marked unhealthy.
- Events may arrive out of order — use the event timestamp rather than arrival order.
A typed client, if you want one.
The JavaScript and TypeScript SDK wraps authentication, pagination, retries, and webhook signature verification. Everything it does is available over plain HTTP — the SDK exists to save you writing the same pagination loop again, not to hide the API.
- Typed response and property models
- Automatic cursor pagination as an async iterator
- Signature verification helper for webhook endpoints
- Retry with backoff on 429 and 5xx responses
- Works in Node and in edge runtimes
Shape of a call
const signals = new Signals({ apiKey });
for await (const r of signals.responses.list({
surveyId: 'srv_...',
since: '2026-07-01T00:00:00Z',
})) {
console.log(r.customerId, r.answers);
}Illustrative example. The documentation carries the authoritative method signatures and installation instructions.
Reasons to reach for the API.
- Mirror survey responses into your own warehouse or BI tool alongside Shopify order data.
- Push declared properties into an ESP or CDP that Signals does not integrate with natively.
- Trigger operational workflows — route a low satisfaction score into your support desk as a ticket.
- Build an internal dashboard for a team that does not have Shopify admin access.
- Enrich a headless storefront with the customer's declared preferences at render time.
- Audit which surveys changed and when, as part of a release process.
None of this is required to use Signals. Surveys, Klaviyo sync, and analytics all work without writing a line of code — the API is for teams who want the data somewhere else too.
Full reference lives in the docs.
This page is an overview. Endpoint paths, payload schemas, error codes, and installation instructions are maintained in the documentation, which may be served from a docs subdomain.
Install first, integrate second.
API keys are issued from the Signals admin once the app is installed on your store.