Submit Survey Response

Submit a response to a survey on behalf of a customer.

Endpoint

POST /v1/surveys/{id}/responses

Path Parameters

Parameter	Type	Description
id	integer	Survey ID

Authentication

Requires an API key with the surveys:write scope.

Request Body

Field	Type	Required	Description
booking_id	integer	No	Link response to a booking
customer_id	integer	No	Link response to a customer
staff_id	integer	No	Staff member who collected the response
responses	array	Yes	Array of field responses
responses[].field_id	integer	Yes	The survey field ID
responses[].value	mixed	Yes	The response value
send_confirmation_email	boolean	No	Send confirmation emails (default: false)
signer_names	object	No	The name typed beside each signature, keyed by field ID. Stored only for a signature (or initials) field on this survey that is set to ask for one, and only when it was actually signed; signed_at is stamped by EquipDash. See Submit Waiver Response.

Field Value Types

Different field types expect different value formats:

Field Type	Value Format	Example
npsRating	integer (0-10)	9
starRating	integer (1-5)	4
csat	integer (1-5)	5
ces	integer (1-7)	6
likertScale	integer (1-5)	4
shortText, longText	string	"Great experience!"
singleChoice	string	"Friend referral"
multipleChoice	array of strings	["Option A", "Option C"]

Example Request

curl -X POST "https://app.equipdash.com/api/v1/surveys/1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "booking_id": 123,
    "customer_id": 456,
    "responses": [
      {
        "field_id": 10,
        "value": 9
      },
      {
        "field_id": 11,
        "value": 5
      },
      {
        "field_id": 12,
        "value": "Friend referral"
      },
      {
        "field_id": 13,
        "value": "Excellent service! The staff was very helpful and the equipment was in perfect condition."
      }
    ],
    "send_confirmation_email": true
  }'

Response

Success (201 Created)

{
  "data": {
    "id": 42,
    "waiver_form_id": 1,
    "booking_id": 123,
    "customer_id": 456,
    "staff_id": null,
    "submission_date": "2026-02-01T10:00:00+00:00",
    "waiver": {
      "id": 1,
      "name": "Customer Satisfaction Survey",
      "type": "survey"
    },
    "customer": {
      "id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com"
    },
    "booking": {
      "id": 123,
      "status": "confirmed"
    },
    "responses": [
      {
        "field_id": 10,
        "field_label": "How likely are you to recommend us?",
        "field_type": "npsRating",
        "value": "9"
      },
      {
        "field_id": 11,
        "field_label": "Rate our equipment quality",
        "field_type": "starRating",
        "value": "5"
      },
      {
        "field_id": 12,
        "field_label": "How did you hear about us?",
        "field_type": "singleChoice",
        "value": "Friend referral"
      },
      {
        "field_id": 13,
        "field_label": "Additional comments",
        "field_type": "longText",
        "value": "Excellent service! The staff was very helpful and the equipment was in perfect condition."
      }
    ],
    "nps_score": 9,
    "nps_category": "promoter",
    "created_at": "2026-02-01T10:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-01T10:00:00+00:00"
  }
}

NPS Data

When a survey contains an NPS rating field, the response includes:

Field	Type	Description
nps_score	integer	The NPS rating (0-10)
nps_category	string	promoter, passive, or detractor

NPS Categories:

• Promoter (9-10): Loyal enthusiasts
• Passive (7-8): Satisfied but unenthusiastic
• Detractor (0-6): Unhappy customers

Error Responses

Survey Not Published

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "survey",
        "message": "This survey is not accepting responses."
      }
    ]
  }
}

Missing Required Fields

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "responses",
        "message": "Missing required fields: How likely are you to recommend us?"
      }
    ]
  }
}

Invalid Customer/Booking

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": [
      {
        "field": "customer_id",
        "message": "Customer not found."
      }
    ]
  }
}

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks surveys:write scope
403	forbidden	Survey belongs to another supplier
404	not_found	Survey not found
422	validation_error	Invalid request data

Notes

• The survey must be in published status to accept responses
• At least one response is required in the responses array
• Only fields belonging to the survey are processed
• For NPS fields, the score and category are automatically calculated
• Confirmation emails can be sent to admins and customers when enabled