Customer.io Forms API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Forms API
  description: Customer.io provides REST APIs to send real-time customer data, retrieve data from your account, and trigger messages.
servers:
- url: https://track.customer.io
  description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://track-eu.customer.io
  description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://api.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Forms
  description: Connect forms to your workspace to identify people, apply form responses to people, and trigger automations for people who fill out forms on your website or in your app.
paths:
  /api/v1/forms/{form_id}/submit:
    servers:
    - url: https://track.customer.io
      description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
    - url: https://track-eu.customer.io
      description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
    post:
      operationId: submitForm
      tags:
      - Forms
      summary: Submit a form
      parameters:
      - name: form_id
        in: path
        required: true
        description: The identifier for a form. If Customer.io does not recognize the `form_id`, we create a new form connection (found on the *Data & Integrations* > *Forms* page). Use a value that makes sense to you, or something that you can trace to your backend system.
        schema:
          type: string
      description: 'Submit a form response. If Customer.io does not recognize the `form_id` we create a new form connection (found on the *Data & Integrations* > *Integrations* > *Forms* page). Form submissions with the same ID are treated as submissions from the same form.


        The `data` object _must_ contain at least one of `id` or `email` (depending on the identifiers supported in your workspace)—or a field that is mapped to one of these identifiers—to identify the form respondent. If the person who submitted the form does not already exist, we create them (like an identify request).


        Additional keys in the `data` object represent form fields and values from the form that a person submitted. By default, we map form fields in your request directly to attributes, e.g. if you have a form field called `first_name`, we map that field to the `first_name` attribute.


        **NOTES**:

        * You cannot disable fields that you send to this API. If you send a field (as `data`) to this API, we''ll include it in the form submission.

        * If an identifier in your form is called something like `email_address` rather than `email` in your initial request, you''ll receive a `400`, but we''ll still add your form on the **Data & Integrations** > **Integrations** > **Forms** page. You can then re-map your `email_address` field to `email`, and your form will begin working normally.

        * Customer.io reserves `form_id`, `form_name`, `form_type`, `form_url`, and `form_url_param` keys. If your request includes these keys, Customer.io ignores them.'
      servers:
      - url: https://track.customer.io
        description: This endpoint is a part of the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
      security:
      - Tracking-API-Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: "The body of the request contains key-value pairs representing form fields; these values are mapped to attributes. Your request must contain one of—and only one of—`email` or `id` to identify a person (depending on the identifiers supported in your workspace). If the person who filled out your form does not already exist, the request creates them. If your request includes more than one identifier, you'll receive an error.\n\n**NOTE**: If your form field is called something like `email_address`, you'll receive a `400`, but we'll still add your form on the **Data & Integrations** > **Integrations** > **Forms** page. You can then re-map your `email_address` field to `email`, and your form will begin working normally.\n \nAdditional keys in the `data` object represent form fields from the form that a person submitted. By default, we map form fields in your request directly to attributes, e.g. if you have a form field called `first_name`, we map that field to the `first_name` attribute. However, if you added or edited this form on the *Data & Integration* > *Forms* page, you can re-map form fields to attributes. If you turned off a form field on the *Forms* page, you can still include it in your request, but it is not applied to the person your form identifies.\n"
              required:
              - data
              properties:
                data:
                  description: 'Represents your form data. By default, we assume that form fields map directly to attributes (e.g. if your form field is called `name`, we assume it represents an attribute called "name"). However, you can re-map form fields to attributes on the **Forms** page in your workspace.


                    Values for form fields _must_ be formatted as strings.

                    '
                  oneOf:
                  - title: identify by email
                    type: object
                    description: Identify the person who submitted your form by email.
                    required:
                    - email
                    properties:
                      email:
                        $ref: '#/components/schemas/email_address'
                    additionalProperties:
                      x-additionalPropertiesName: Form fields
                      type: string
                      description: 'Fields from the form and associated values; values _must_ be formatted as strings. Each key represents an a form field. You can map form fields to attributes in the UI; by default, we assume that a form field maps directly to an attribute name.


                        Customer.io reserves `form_id`, `form_name`, `form_type`, `form_url`, and `form_url_param` keys. If your request includes these keys, Customer.io ignores them.

                        '
                    example:
                      email: cool.person@example.com
                      first_name: cool
                      last_name: person
                      fav_food: pizza
                  - title: identify by id
                    type: object
                    required:
                    - id
                    description: Identify the person who submitted your form by ID.
                    properties:
                      id:
                        $ref: '#/components/schemas/customer_id'
                    additionalProperties:
                      x-additionalPropertiesName: Form fields
                      type: string
                      description: 'Fields from the form and associated values; values _must_ be formatted as strings. Each key represents an a form field. You can map form fields to attributes in the UI; by default, we assume that a form field maps directly to an attribute name.


                        Customer.io reserves `form_id`, `form_name`, and `form_type` keys. If your request includes these keys, Customer.io ignores them.

                        '
                    example:
                      id: 12345
                      first_name: cool
                      last_name: person
                      fav_food: pizza
      responses:
        '204':
          description: Successful requests do not return anything.
        '400':
          description: Invalid or malformed request. One or more form values may not be properly formatted as strings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      errors:
                        type: array
                        description: An array of errors.
                        items:
                          type: string
                          description: Error descriptions.
components:
  schemas:
    email_address:
      x-scalar-ignore: true
      type:
      - string
      - 'null'
      description: The email address of the customer.
      example: test@example.com
    customer_id:
      x-scalar-ignore: true
      type:
      - string
      - 'null'
      description: The ID of a customer profile, analogous to a "person" in the UI. If your workspace supports multiple identifiers (email and ID), this value can be null.
      example: '42'
  securitySchemes:
    Tracking-API-Key:
      type: http
      scheme: basic
      description: 'The Track API uses a basic authentication scheme. Your credentials are your **Site ID** and your **API key**, **Base-64 encoded** in the format `site_id:api_key`.


        You can find your Site ID and API key on the [Track API Keys page](https://fly.customer.io/settings/api_credentials).

        '
    Bearer-Auth:
      type: http
      scheme: bearer
      description: 'The App API uses a bearer authentication scheme.


        You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).

        '
    ServiceAccount-Auth:
      x-scalar-ignore: true
      type: http
      scheme: bearer
      bearerFormat: sa_live_
      description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/whatsapp`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.


        Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.


        Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token.
x-tagGroups:
- name: Track API v2
  tags:
  - track_v2
  - Object Schemas
  - Person Schemas
  - Deliveries
- name: Track API
  tags:
  - trackOverview
  - trackJsOrBackend
  - trackLimit
  - trackRegion
  - Track Customers
  - Track Events
  - Forms
  - Track Segments
  - Track v1 Overview
- name: App API
  tags:
  - appOverview
  - appLimit
  - appAuth
  - Activities
  - Automations
  - Broadcasts
  - Collections
  - Customers
  - Data Index
  - ESP Suppression
  - Exports
  - Imports
  - Info
  - Live Notifications
  - Messages
  - Newsletters
  - Opt-outs
  - Reporting Webhooks
  - Segments
  - Sender Identities
  - Snippets
  - Subscription Center
  - Transactional
  - Workspaces
  - Send Messages
  - Objects
  - Newsletter Variants
  - Newsletter Metrics
  - Assets
- name: Design Studio API
  tags:
  - Folders
  - Components
  - Emails
  - Email link and publish
  - Email testing
  - SMS
  - SMS link and publish
x-provenance:
  method: harvested
  publisher: Customer.io
  source: https://docs.customer.io/files/journeys-track.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)