---
title: "Submit a web form"
method: POST
path: "/api/web-forms/{formId}"
tags: ["WebForms"]
---

# Submit a web form

`POST /api/web-forms/{formId}`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/web-forms/{formId}`
- Auth: API key in header `x-token`
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/web-forms/:formId/post.ts> (a function with typed inputs; its response is checked against the schema)

Submits data to an Aptly Web Form. The request must use the API key
issued for this exact form and that key must have insert access to the
form's board.

Submitted board-field values are keyed by field UUID. Depending on the
form's configuration, the submission creates a card or updates a card
whose configured match fields have the same values. Unknown properties
are ignored. Contact shortcut properties can link the card to an
existing contact or create a new contact when the form and board allow it.

## Path parameters

- `formId` string, required

## Request body

- object
  - `name` string: Card name. Takes precedence over `title`.
  - `title` string: Card name when `name` is omitted.
  - `contactFirstName` string: Contact first name used by automatic contact linking.
  - `contactLastName` string: Contact last name used by automatic contact linking.
  - `contactFullName` string: Contact full name used by automatic contact linking.
  - `contactEmail` string, email: Contact email used for lookup or creation.
  - `contactPhone` string: Contact phone number used for lookup or creation.

## Response `200`

Submission accepted and its card created or updated.

- object
  - `data` object
    - `_id` string, required: ID of the created or updated card.
    - `action` 'created' | 'updated', required

## Other responses

- `400`: The board API is disabled or the submitted data is invalid.
- `401`: Invalid or missing API key.
- `403`: The API key lacks insert or board access, or was not issued for this form.
- `404`: Form or board not found.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)