Skip to main content
Surveys let you ask customers standardized questions to understand their experience. You retrieve survey definitions through the API and send them to contacts via the message send endpoint. The opening question of the survey is delivered as the message text, and responses are captured automatically.

​
The Survey object

​
id
integer
Unique identifier for the survey.
​
name
string
Display name of the survey.
​
type
string
Survey type (e.g., NPS, CSAT).
​
question
string
The opening question text sent to the contact as the message.
​
created
string
ISO 8601 timestamp when the survey was created.
​
updated
string
ISO 8601 timestamp when the survey was last updated.

​
Get a survey

GET /v1/survey/{id} Retrieves a single survey by its ID.
​
id
integer
required
The ID of the survey to retrieve.
curl --request GET \
  --url https://api.heymarket.com/v1/survey/10 \
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 10,
  "name": "Post-purchase NPS",
  "type": "nps",
  "question": "How likely are you to recommend us to a friend? Reply with a number from 0 to 10.",
  "created": "2023-06-01T12:00:00Z",
  "updated": "2024-01-20T09:15:00Z"
}

​
List surveys

POST /v1/surveys Returns a paginated list of all surveys in your team.
​
limit
integer
Maximum number of surveys to return per page.
​
page
integer
Page number for pagination, starting at 1.
curl --request POST \
  --url https://api.heymarket.com/v1/surveys \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 20,
    "page": 1
  }'

[
  {
    "id": 10,
    "name": "Post-purchase NPS",
    "type": "nps",
    "question": "How likely are you to recommend us to a friend? Reply with a number from 0 to 10.",
    "created": "2023-06-01T12:00:00Z",
    "updated": "2024-01-20T09:15:00Z"
  },
  {
    "id": 11,
    "name": "Support CSAT",
    "type": "csat",
    "question": "How satisfied were you with your support experience? Reply 1 (very unsatisfied) to 5 (very satisfied).",
    "created": "2023-08-14T10:30:00Z",
    "updated": "2024-02-05T11:00:00Z"
  }
]

​
Sending a survey

To send a survey to a contact, include the survey_id field in the body of your POST /v1/message/send request. Heymarket uses the survey’s opening question as the message text and automatically processes the contact’s reply as a survey response. 
{
  "inbox_id": 413,
  "phone_number": "14155553434",
  "survey_id": 10
}
Surveys are created and managed from within the Heymarket app, not via the API. Use the API endpoints on this page to retrieve survey IDs for use in message sends.