---
title: "Create form submission"
method: POST
path: "/forms/{form_id}/submissions"
tags: ["Forms"]
---

# Create form submission

`POST /forms/{form_id}/submissions`

## Request

- Base URL: `https://api.crevio.co/v1`
- URL: `https://api.crevio.co/v1/forms/{form_id}/submissions`
- Auth: API key in header `Authorization`

Submits an answer set to a specific Form. Customer is upserted by email; lead-magnet purpose forms also trigger delivery.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `email` string, required
  - `name` string, nullable
  - `answers` object, required: Map of form_field id → answer value. A `consent` field takes `true` when the person agreed.
  - `ip_address` string, nullable: The submitter's IP address, kept with the submission as a record of consent.

## Response `201`

Submission created

- FormSubmission
  - `id` string, required
  - `object` string, required
  - `answers` object[], required
    - `field_type` string, required
    - `label` string, required
    - `required` boolean, required
    - `value` union, required
      - string
      - string[]
    - `options` string[]
  - `respondent_type` string, required
  - `confirmation_requested_at` string, date-time, nullable, required
  - `confirmed_at` string, date-time, nullable, required
  - `delivered_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `respondent_id` string, required
  - `form_id` string, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `422`: Validation error
- `429`: Rate limit exceeded — 600 requests per minute per credential. Retry after the number of seconds in `Retry-After`.
- `500`: Internal server error

---

[API](https://skmtc.dev/crevio/apis/crevio-api-v1.md) · [All operations](https://skmtc.dev/crevio/apis/crevio-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/crevio/apis/crevio-api-v1/revisions/2219f18ad651?raw)