> ## Documentation Index > Fetch the complete documentation index at: https://docs.formitto.com/llms.txt > Use this file to discover all available pages before exploring further. # Ingest a submission > Programmatically create a submission for a form. Runs the same pipeline as the public widget (webhooks, confirmation emails, PHI handling). Supply an optional `Idempotency-Key` header to safely retry: within 24h, the same key replays the original result (HTTP 200) instead of creating a duplicate. ## OpenAPI ````yaml /api/openapi.yaml post /forms/{id}/submissions openapi: 3.1.0 info: title: Formitto API version: 1.0.0 description: > The Formitto public API (v1). Read and manage your forms, submissions, calendars, bookings, shop widgets, and orders programmatically. Authenticate with an API key created in the Formitto dashboard (Settings → API keys). Pass it as a Bearer token: `Authorization: Bearer fmt_live_...`. Keys are scoped — a key only reaches the endpoints its scopes allow (e.g. `read:forms`, `write:submissions`). All responses are JSON. List endpoints return a `{ data, pagination }` envelope; single-resource endpoints return the object directly. Requests are rate-limited per API key; see the `X-RateLimit-*` response headers. contact: name: Formitto Support url: https://formitto.com license: name: Proprietary url: https://formitto.com/terms servers: - url: https://formitto.com/v1 description: Production security: - bearerAuth: [] tags: - name: forms description: Create, read, update, and archive forms. - name: submissions description: Read and programmatically ingest form submissions. - name: calendars description: Read calendar widgets. - name: bookings description: Read calendar bookings. - name: ecommerce description: Read shop widgets. - name: orders description: Read shop orders. - name: webhooks description: Manage event subscriptions (REST Hooks) for integrations. paths: /forms/{id}/submissions: parameters: - $ref: '#/components/parameters/ResourceId' post: tags: - submissions summary: Ingest a submission description: > Programmatically create a submission for a form. Runs the same pipeline as the public widget (webhooks, confirmation emails, PHI handling). Supply an optional `Idempotency-Key` header to safely retry: within 24h, the same key replays the original result (HTTP 200) instead of creating a duplicate. operationId: createSubmission parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmissionCreate' responses: '200': description: > Idempotent replay — the original submission for this `Idempotency-Key`, returned verbatim. content: application/json: schema: $ref: '#/components/schemas/Submission' '201': description: The created submission. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Submission' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: parameters: ResourceId: name: id in: path description: The resource id. required: true schema: type: integer IdempotencyKey: name: Idempotency-Key in: header description: > Optional. A client-chosen unique string (≤256 chars). Within 24h, retrying with the same key replays the original result instead of creating a duplicate submission. required: false schema: type: string maxLength: 256 schemas: SubmissionCreate: type: object required: - formData properties: formData: type: object description: Field values (label → value). Max 50 keys, max 50KB serialized. additionalProperties: true wcClientCurrent: type: - string - 'null' description: Optional WhatConverts attribution cookie value. Submission: type: object required: - id - formId - formData - createdAt properties: id: type: integer formId: type: integer formData: type: object description: The submitted field values (label → value). additionalProperties: true sourceDomain: type: - string - 'null' description: >- The page hostname the submission originated from (null for API ingestion). createdAt: type: string format: date-time Error: type: object description: > Standard error envelope. `code` is a stable machine-readable string (e.g. invalid_api_key, insufficient_scope, not_found, rate_limited, domain_required, forbidden_field). Some errors carry extra context fields (candidates, required, fields, invalid, retryAfter). required: - error additionalProperties: true properties: error: type: string description: Human-readable message. code: type: string description: Stable machine-readable error code. headers: RateLimitLimit: description: The per-API-key request budget for the current 1-hour window. schema: type: integer RateLimitRemaining: description: Requests remaining in the current window after this request. schema: type: integer RateLimitReset: description: Unix timestamp (seconds) at which the rate-limit window resets. schema: type: integer RetryAfter: description: Seconds to wait before retrying. Present on 429 responses. schema: type: integer responses: BadRequest: description: >- The request was invalid (validation error, bad domain, forbidden field, etc.). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: The API key is missing, malformed, revoked, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The API key is valid but lacks the scope this endpoint requires. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- No such resource on this account (also returned for resources owned by another account). content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: The per-API-key request budget for the current window is exhausted. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: An unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: fmt_live_* description: > A Formitto API key created in the dashboard (Settings → API keys). Pass it as `Authorization: Bearer fmt_live_...`. ````