HTTP ingestion API

The HTTP ingestion API lets your backend submit form data programmatically without a browser or form widget. One POST per submission — you get a submission ID back, and the result is indistinguishable from a user filling the form manually.

Endpoint

POST /api/v1/tenant/forms/:form_id/submissions

:form_id is the UUID of the form definition. The form must be in published status; submitting to a draft or archived form returns 422 form_not_accepting_submissions.

Authentication

Pass a tenant API token as a Bearer token in the Authorization header.

Authorization: Bearer fy_pat_<your-token>

The token must carry the forms:ingest scope. Tokens with admin:* are also accepted. To mint a token with the correct scope, go to Settings → API tokens in the admin portal.

If the token is missing or does not have the required scope, the endpoint returns 401 Unauthorized or 403 Forbidden respectively.

Request

Headers

Body

{
  "payload": {
    "field_key": "value"
  }
}

The field values in payload are validated against the form's published schema. Required fields must be present; type constraints (text, number, email, etc.) are enforced. Validation failures return 422 validation_failed with a per-field error list.

Response

201 Created — new submission

{
  "submission_id": "01jx3p...",
  "was_idempotent_replay": false
}

200 OK — idempotent replay

When an Idempotency-Key header was supplied and a matching prior submission exists, the endpoint returns 200 instead of 201 with the original submission_id and "was_idempotent_replay": true. No duplicate row is written.

{
  "submission_id": "01jx3p...",
  "was_idempotent_replay": true
}

Idempotency

Include an Idempotency-Key header to make requests safe to retry.

Idempotency-Key: order-12345-attempt-1

Key format: 1–128 characters, allowed characters A-Z a-z 0-9 . _ -. Any other characters return 400 bad_idempotency_key_format.

How it works:

1. On the first request with a given key, the submission is written and the key is associated with the resulting submission_id.
2. Retrying with the same key and the same payload returns 200 with the original submission_id. No second submission is created.
3. Retrying with the same key but a different payload returns 409 idempotency_key_payload_mismatch. The key cannot be reused with different data.

TTL: Idempotency records expire after 24 hours. After expiry, the same key may be reused and will be treated as a fresh submission.

Payload hashing: Sameness is determined by a canonical SHA-256 hash of the payload object. Object key ordering is normalized before hashing, so {"b": 2, "a": 1} and {"a": 1, "b": 2} are treated as identical.

Concurrency: If two requests arrive simultaneously with the same key, one wins and proceeds; the other spins briefly and then returns 200 with the winner's submission_id. If the key is still in flight after the retry budget is exhausted, a 422 in_flight response is returned — wait a moment and retry.

Rate limiting

The endpoint is rate-limited to a burst of 60 requests per (token, form) pair. After exhausting the burst, requests return 429 Too Many Requests with a Retry-After header and a retry_after_secs field in the response body.

HTTP/1.1 429 Too Many Requests
Retry-After: 3

{
  "error": {
    "code": "rate_limited",
    "retry_after_secs": 3,
    "message": "rate limited"
  }
}

Error reference

All errors share the envelope shape { "error": { "code": "...", "message": "..." } }. Some codes include additional fields noted below.

Example

curl -X POST https://app.fastyoke.io/api/v1/tenant/forms/FORM_ID/submissions \
  -H "Authorization: Bearer fy_pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-batch-job-row-42" \
  -d '{
    "payload": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }'

Successful response:

{
  "submission_id": "01jx3pabcdefghijklmn",
  "was_idempotent_replay": false
}