Prerequisites
- A platform API key (
abl_…). Send it in thex-api-keyheader or asAuthorization: Bearer abl_…. User session tokens (JWT) are refused. - The
feedback-survey:writepermission on the key to submit ratings. Thefeedback-survey:readpermission to list responses. - The ID of the project.
- The name of an existing survey in the project. You refer to a survey by name.
Workflow and use cases
- Submit a rating for each response you collect. Send the survey name and the rating on the survey’s own scale.
- Poll the list of responses from the oldest one. Pass the
nextCursorfrom each page ascursorin the next request. - Use
survey_idto match responses to a survey, because a survey name can change.
List of endpoints
All paths start with/api/public/feedback/projects/{projectId}.
Behavior to know
- The platform key identifies the origin of every submitted response. A body that sets
origin,captureMethod,surveyTemplateId, orscorereturns400 FIELD_NOT_ACCEPTED. Any other unknown field returns400 UNKNOWN_FIELD. - The API checks each rating against the survey’s control range: thumbs 0 to 1, star 1 to 5, scale 0 to 10. A rating outside the range returns
422 INVALID_INPUT. The API never adjusts the value. - A free-text survey collects no rating. Submitting a rating to it returns
422 TEMPLATE_COLLECTS_NO_RATING. - A repeated submission returns the original
response_id. - The list returns all responses for the project, including ones captured in the product and by other integrations. Use
response_sourceto tell them apart. - The
surveyfield in a response shows the survey’s current name for display only. It is empty if the survey was deleted. Usesurvey_idto correlate. - Use
survey,from, andtoto filter the list. A survey name that does not exist returns404 SURVEY_NOT_FOUND. - The
limitparameter accepts 1 to 200 and defaults to 50. Values above 200 are capped. A cursor that the API did not issue returns400 INVALID_CURSOR. - Exceeding the rate allowance of the key returns
429.