---
title: "Submit a form"
method: POST
path: "/api/v1/forms/{form_id}/submit"
tags: ["Forms"]
---

# Submit a form

`POST /api/v1/forms/{form_id}/submit`

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](/integrations/api/track/tag/track-customers/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.

## Path parameters

- `form_id` string, required

## Request body

- object — 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. **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. Additional 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.
  - `data` union, required — 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.
    - object — Identify the person who submitted your form by email.
      - `email` string, nullable, required — The email address of the customer.
    - object — Identify the person who submitted your form by ID.
      - `id` string, nullable, required — 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.

## Response `204`

Successful requests do not return anything.

## Other responses

- `400` — Invalid or malformed request. One or more form values may not be properly formatted as strings.

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)