surveys reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

GET /v1/surveys

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Required header: x-one-survey-config-version: 1.0. The server rejects an absent or incompatible value.

Request

No query parameters or JSON body. Send the required header with the app API key.

Response

JSON response shape

{ surveys: SurveyCatalogItem[];
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleSurveyCatalog.

POST /v1/surveys/participations/:participationId/shown

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: participationId (string). Every target must belong to the authenticated app or workspace.

Required header: x-one-survey-config-version: 1.0. The server rejects an absent or incompatible value.

Required header: x-one-platform: ios | android | web | windows | macos. These customer-scoped commands also require the established customer identity and proof headers managed by the SDK.

Request

Send JSON with Content-Type: application/json and the required headers. Path parameters remain in the URL.

{ shownAt: string;
  }

Validation schemas: surveyShownSchema in the downloadable schema registry.

Response

JSON response shape

{ shownAt: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleSurveyShown.

POST /v1/surveys/participations/:participationId/dismiss

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: participationId (string). Every target must belong to the authenticated app or workspace.

Required header: x-one-survey-config-version: 1.0. The server rejects an absent or incompatible value.

Required header: x-one-platform: ios | android | web | windows | macos. These customer-scoped commands also require the established customer identity and proof headers managed by the SDK.

Request

Send JSON with Content-Type: application/json and the required headers. Path parameters remain in the URL.

{ shownAt?: string | undefined;
  }

Validation schemas: surveyDismissSchema in the downloadable schema registry.

Response

JSON response shape

{ success: boolean;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleSurveyDismiss.

POST /v1/surveys/participations/:participationId/response

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: participationId (string). Every target must belong to the authenticated app or workspace.

Required header: x-one-survey-config-version: 1.0. The server rejects an absent or incompatible value.

Required header: x-one-platform: ios | android | web | windows | macos. These customer-scoped commands also require the established customer identity and proof headers managed by the SDK.

Request

Send JSON with Content-Type: application/json and the required headers. Path parameters remain in the URL.

{ submissionId: string;
  answers: { questionId: string;
  choiceIds?: string[] | undefined;
  otherText?: string | undefined;
  text?: string | undefined;
  rating?: number | undefined;
  }[];
  shownAt?: string | undefined;
  }

unknown

Validation schemas: surveySubmissionSchema in the downloadable schema registry.

Response

JSON response shape

SurveySubmissionReceipt

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleSurveySubmission.