Form Responses

💡 Understand how form data is structured across Billy API endpoints

Overview

Several Billy API endpoints return form responses, which are data submitted by attendees or buyers through configurable forms.

These forms are defined by the event organizer in Billy Studio and can include fields like name, email, dietary preferences, and more.

To provide a consistent and predictable developer experience, all form responses follow the same structure across the API, regardless of form type.

Form response structure

A form response object contains:

• formId (string): Versioned identifier of the form definition. Changes when the form is edited.
• submittedAt (string, ISO 8601, UTC): Timestamp of when the form was submitted.
• responses (array of Response objects): List of field responses.

Response object

Each entry in the responses array represents a single form field submission:

• fieldId (string): Identifier of the form field, as configured by the organizer.
• value (array of strings): The submitted value or values. Always an array, even for single values.

Value normalization

All values are normalized to arrays of strings:

• "Roger" becomes ["Roger"]
• 28 becomes ["28"]
• ["a", "b"] stays ["a", "b"]
• null becomes []

Example

{
  "ticketId": "tkt_01",
  "customer": {
    "customerId": "a987e136-c18a-420d-852c-30c55bd0c584",
    "firstName": "Billy",
    "lastName": "Bob",
    "email": "billybob@gmail.com"
  },
  "attendeeForm": {
    "formId": "af_01ABC:ev_01ABC:org_01ABC:2",
    "submittedAt": "2026-03-05T13:17:46.076463+00:00",
    "responses": [
      { "fieldId": "first-name", "value": ["Roger"] },
      { "fieldId": "last-name", "value": ["Chouette"] },
      { "fieldId": "dietary", "value": ["Vegetarian"] }
    ]
  }
}

When no form has been submitted for a ticket, the form field is null:

{
  "ticketId": "tkt_02",
  "attendeeForm": null
}