Customer.io Forms API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Track Forms API
  description: '# Overview


    Our Track API provides ways to send real-time customer data to your Customer.io workspace including customer identification and event tracking.'
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.
tags:
- name: Forms
  description: Connect forms to your workspace to identify people, apply form responses to people, and trigger campaigns for people who fill out forms on your website or in your app.
paths:
  /api/v1/forms/{form_id}/submit:
    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.
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"data\": {\n    \"email\": \"cool.person@example.com\",\n    \"first_name\": \"cool\",\n    \"last_name\": \"person\",\n    \"fav_food\": \"pizza\"\n  }\n}"
components:
  schemas:
    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'
    email_address:
      x-scalar-ignore: true
      type:
      - string
      - 'null'
      description: The email address of the customer.
      example: test@example.com
  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).

        '