Pre-fill appointment booking fields

Use a booking-page URL to carry values your integration already knows, such as a customer's name or email, into the booking flow. Add query parameters using a field's durable key. When the visitor completes the booking, Mateo stores the answers with the appointment, where your integration can retrieve them through additional_fields.

Before you begin

You need a booking page whose status is published. Retrieve its public booking link from the API rather than constructing it from a booking-page ID:

curl --get 'https://api.getmateo.com/v1/booking-pages' \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01"

Select the page you want from data. A published page returns its full public link:

{
  "object": "list",
  "data": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789aa",
      "name": "Consultation",
      "status": "published",
      "link": "https://app.getmateo.com/b/<sqid>"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Use the returned link directly. Its value after /b/ is the <sqid> used in the customer-facing booking URL. Use the booking page's id for public API requests.

Prefilling applies only to fields in the current published forms. It does not create fields or bypass validation. Use booking_fields for the contact fields returned by the booking page and additional_fields for the scheduler fields returned by the appointment type.

Booking URLs can contain personal data. Treat them as sensitive: do not put them in public logs, analytics, or channels that are not appropriate for the customer data they contain.

Inspect the fields you can pre-fill

Booking-page contact fields

Read the booking page through the public API to find the contact fields configured on that page:

curl --get "https://api.getmateo.com/v1/booking-pages/$BOOKING_PAGE_ID" \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01"

The response exposes the page's current booking_fields:

{
  "id": "018f2f82-4f7a-7a2f-9c4e-0123456789aa",
  "status": "published",
  "link": "https://app.getmateo.com/b/<sqid>",
  "booking_fields": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
      "key": "first_name",
      "label": "First name",
      "value_type": "string"
    },
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ac",
      "key": "email",
      "label": "Email address",
      "value_type": "string"
    }
  ]
}

Use the returned booking_fields array as the source of truth when generating booking_fields[<key>] parameters. Use each field's durable key, not its version-specific element id.

Appointment-type scheduler fields

Before generating a booking link, request the selected appointment type with its scheduler included:

curl --get "https://api.getmateo.com/v1/appointment-types/$APPOINTMENT_TYPE_ID" \
  --data-urlencode 'include=scheduler' \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01"

The scheduler's additional_fields are the custom keys that can be sent through additional_fields:

{
  "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ad",
  "scheduler": {
    "additional_fields": [
      {
        "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ae",
        "key": "preferred_date",
        "label": "Preferred date",
        "value_type": "string"
      },
      {
        "id": "018f2f82-4f7a-7a2f-9c4e-0123456789af",
        "key": "remote",
        "label": "Remote appointment",
        "value_type": "boolean"
      }
    ]
  }
}

Use each field's durable key in an additional_fields[<key>] parameter. Republishing a form can change an element ID, while the key remains the durable integration identifier. In the appointment-type response, scheduler is null when scheduling is disabled and scheduler.additional_fields is [] when no eligible questions exist.

Create a pre-filled booking link

Use bracketed query parameter names:

• booking_fields[<key>] for standard booking-page contact fields.
• additional_fields[<key>] for appointment-type scheduler questions.

For example, this link pre-fills four standard fields and two appointment-type-specific fields:

https://app.getmateo.com/b/<sqid>?booking_fields[first_name]=Ada&booking_fields[last_name]=Lovelace&booking_fields[email]=ada%40example.com&booking_fields[city]=Berlin&additional_fields[preferred_date]=2026-09-01&additional_fields[remote]=true

Generate the URL with a URL builder so values are encoded correctly:

const bookingUrl = new URL('https://app.getmateo.com/b/<sqid>');

bookingUrl.searchParams.set('booking_fields[first_name]', 'Ada');
bookingUrl.searchParams.set('booking_fields[last_name]', 'Lovelace');
bookingUrl.searchParams.set('booking_fields[email]', 'ada@example.com');
bookingUrl.searchParams.set('booking_fields[city]', 'Berlin');
bookingUrl.searchParams.set('additional_fields[preferred_date]', '2026-09-01');
bookingUrl.searchParams.set('additional_fields[remote]', 'true');

console.log(bookingUrl.toString());

The booking page accepts text, date, and boolean form values. Send boolean values as the literal strings true or false; invalid boolean values are not applied. A value is applied only when its key matches a field returned for the booking page or selected appointment type.

Unknown, removed, repeated, or incompatible values are ignored. Do not use historical element IDs, send null, or assume a URL parameter overrides a visitor's final answer.

Retrieve the submitted values from the appointment

After the visitor books, request the appointment with the additional_fields include. The values are not exposed as a separate prefill property: they are the historical form answers saved with the appointment.

curl --get "https://api.getmateo.com/v1/appointments/$APPOINTMENT_ID" \
  --data-urlencode 'include=additional_fields' \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01"

The response combines booking-page contact fields and scheduler-form answers linked to the appointment:

{
  "id": "018f2f82-4f7a-7a2f-9c4e-0123456789af",
  "additional_fields": [
    { "key": "first_name", "value": "Ada" },
    { "key": "last_name", "value": "Lovelace" },
    { "key": "email", "value": "ada@example.com" },
    { "key": "city", "value": "Berlin" },
    { "key": "preferred_date", "value": "2026-09-01" },
    { "key": "remote", "value": true }
  ]
}

Use the returned key to map each answer to your integration. Text, date, and select values are strings; boolean values are booleans; unanswered or explicitly null values are null. The same include is available when listing appointments and when reading one through the appointment locator.

additional_fields reflects submitted values, not merely the query string. If a visitor changes a pre-filled answer, the submitted answer is returned. If multiple linked submissions use the same key, the most recently finalised value wins. Keep keys unique across booking and scheduler forms when your integration needs an unambiguous value.

additional_fields is read-only on appointment create and update requests. It is separate from the legacy appointment custom-field property returned through include_details=fields.