Submit a form

Server

US region

Client Libraries

Shell Curl

Submit a form

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.

Path Parameters

form_id
Type: string
required

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.

Body

application/json

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
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.
Identify the person who submitted your form by email.
email
Type: string | null
required

The email address of the customer.

Form fields
Type: string

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.

Responses

204

Successful requests do not return anything.
application/json

post/api/v1/forms/{form_id}/submit

curl 'https://track.customer.io/api/v1/forms/{form_id}/submit' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "data": {
    "email": "cool.person@example.com",
    "first_name": "cool",
    "last_name": "person",
    "fav_food": "pizza"
  }
}'

No Body

Successful requests do not return anything.

Submit a form

Authentication

Submit a form