---
title: "Retrieve a form"
method: GET
path: "/v1/forms/{form_id}"
tags: ["forms"]
---

# Retrieve a form

`GET /v1/forms/{form_id}`

## Request

- Base URL: `https://api.formcarry.com`
- URL: `https://api.formcarry.com/v1/forms/{form_id}`
- Auth: HTTP bearer

Returns the form and its full configuration.

## Path parameters

- `form_id` string, required

## Response `200`

- FormResource
  - `id` string, required
  - `team_id` string, required
  - `name` string, required
  - `endpoint` string, required: Where your HTML form posts.
  - `active` boolean, required: Inactive forms reject submissions.
  - `avatar` string, required
  - `folder_id` string, nullable, required: The folder the form is filed in, or null for none.
  - `created_at` string, required
  - `last_submission_at` string, nullable, required: When the newest submission arrived, or null before the first.
  - `submissions` SubmissionCounts, required
    - `this_month` number, required: Submissions received this calendar month.
    - `all_time` number, nullable, required: Submissions received since the form was created.
  - `storage` StorageBlock, required
    - `store_submissions` boolean: When false, submissions are forwarded by email and webhook but nothing is stored.
    - `keep_for` '30_days' | '60_days' | '90_days' | '180_days' | '365_days' | 'forever': How long stored submissions are kept before they are removed.
  - `spam` SpamBlock, required
    - `protection` boolean: formcarry's built-in spam filter.
    - `captcha` CaptchaBlock
      - `provider` 'none' | 'recaptcha' | 'hcaptcha' | 'turnstile': Which captcha your form embeds. formcarry verifies the response with this secret key.
      - `secret_key` string, nullable: The secret key from your captcha provider's dashboard. Write only: a read carries secret_key_set instead, and null on a write keeps the stored one. To drop it, set the provider to none.
      - `secret_key_set` boolean: Whether a secret key is stored. Read only: ignored on a write, so a form read and sent back whole is fine.
  - `self_email_notification` SelfEmailNotificationBlock, required
    - `enabled` boolean: Send an email to the recipients on every submission.
    - `recipients` string[]: Who receives the email. Replaces the whole list. The free plan allows one address.
    - `include_spam` boolean: Also send the email for submissions the spam filter flagged.
    - `subject` string, nullable: Email subject. null uses formcarry's default.
    - `logo_url` string, nullable: The logo of the email, shown by the built-in themes and available to a custom template. Upload one with the images endpoint (use `self_email_notification_logo`) or use any public PNG, JPEG or GIF URL.
    - `logo_height` number, nullable: Logo height in pixels. null lets the template decide.
    - `template` SelfEmailNotificationTemplateBlock
      - `type` 'formcarry' | 'custom': formcarry: one of the built-in themes. custom: your own template, sent in `html`. A custom template is not plain HTML: it is a Mustache template that formcarry fills in for every submission. See the documentation on custom email templates for how it works.
      - `theme` 'formal' | 'fancy': The built-in theme, used when type is formcarry.
      - `html` string, nullable: Your own template, used when type is custom. Not plain HTML: a Mustache template with tags such as {{email}} that formcarry fills in for every submission. See the documentation on custom email templates for the tags and the rules.
    - `sender` SenderBlock
      - `type` 'formcarry' | 'email_server' | 'premium_server': formcarry: sent from formcarry. email_server: one of your own SMTP servers. premium_server: one of your verified sending domains.
      - `server_id` string, nullable: The id of the server, from GET /v1/email-servers. Required for email_server and premium_server, null for formcarry.
      - `name` string, nullable: Sender name, premium_server only. Null for the other types.
      - `email` string, nullable: Sender address, premium_server only. Must belong to the verified domain. Null for the other types.
  - `auto_response` AutoResponseBlock, required
    - `enabled` boolean: Send a reply to the person who submitted the form (their email field is used as the address).
    - `subject` string, nullable: Subject of the reply.
    - `from_name` string, nullable: The name the reply appears to come from.
    - `logo_url` string, nullable: The logo of the reply, shown by the built-in themes and available to a custom template. Upload one with the images endpoint (use `auto_response_logo`) or use any public PNG, JPEG or GIF URL.
    - `logo_height` number, nullable: Logo height in pixels. null lets the template decide.
    - `template` AutoResponseTemplateBlock
      - `type` 'formcarry' | 'custom': formcarry: one of the built-in themes with your message. custom: your own template, sent in `html`. A custom template is not plain HTML: it is a Mustache template that formcarry fills in for every submission. See the documentation on custom email templates for how it works.
      - `theme` 'formal' | 'fancy': The built-in theme, used when type is formcarry.
      - `message` string, nullable: The message body, used when type is formcarry.
      - `html` string, nullable: Your own template, used when type is custom. Not plain HTML: a Mustache template with tags such as {{email}} that formcarry fills in for every submission. See the documentation on custom email templates for the tags and the rules.
  - `after_submit` AfterSubmitBlock, required
    - `type` 'formcarry_page' | 'redirect': formcarry_page: show formcarry's thank you page. redirect: send the visitor to your own URL.
    - `page` AfterSubmitPageBlock
      - `theme` 'sweet' | 'fancy' | 'formal'
      - `mode` 'light' | 'dark' | 'system': Light or dark colours, or follow the visitor's system setting.
      - `headline` string, nullable: The page title.
      - `message` string, nullable: The text under the title.
      - `logo_url` string, nullable: Logo for the light look.
      - `logo_dark_url` string, nullable: Logo for the dark look.
      - `logo_size` 'normal' | 'big'
      - `primary_color` string, nullable: A CSS colour.
      - `secondary_color` string, nullable: A CSS colour.
      - `return_button` PageButtonBlock
        - `text` string, nullable: Button label. null hides the button.
        - `url` string, nullable: Where the button leads.
      - `download_button` PageButtonBlock
        - `text` string, nullable: Button label. null hides the button.
        - `url` string, nullable: Where the button leads.
    - `redirect` AfterSubmitRedirectBlock
      - `success_url` string, nullable: Where the visitor goes after a successful submission.
      - `fail_url` string, nullable: Where the visitor goes when the submission is rejected. null uses success_url.
      - `append_submission_to_url` boolean: Append the submitted fields to the redirect URL as query parameters.
  - `webhooks` WebhookResource[], required: Managed at /v1/forms/{form_id}/webhooks; one per form for now.
    - `id` string, required
    - `url` string, required
    - `enabled` boolean, required
    - `description` string, nullable, required
    - `events` string[], required
    - `signing` WebhookSigning, required
      - `algorithm` string, required
      - `header` string, required
    - `last_delivery` WebhookLastDelivery, required
      - `at` string, required
      - `status` 'succeeded' | 'failed', required
      - `response_status` number, nullable, required
      - `attempt` number, required
    - `created_at` string, required
  - `validation` ValidationBlock, required
    - `enabled` boolean: Reject submissions that fail the rules.
    - `rules` ValidationRule[]: Replaces the whole list.
      - `field` string, required: The name of the field in your HTML form.
      - `checks` ValidationCheck[], required
        - `type` 'required' | 'email' | 'url' | 'phone_number' | 'integer' | 'min_length' | 'max_length' | 'contains' | 'not_contains', required
        - `value` string, nullable: The argument for min_length, max_length, contains and not_contains.
        - `message` string, nullable: Replaces the default error message shown to the visitor.

## Other responses

- `401`: The request carried no usable key or token.
- `403`: The key is valid but may not do this.
- `404`: No such form for this key.
- `429`: Slow down and retry after the Retry-After header.

---

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