{"openapi":"3.0.0","paths":{"/v1/forms":{"get":{"operationId":"FormsController_list","summary":"List forms","description":"Returns the forms your key can access, newest first, each with its full configuration.","parameters":[{"name":"limit","required":false,"in":"query","description":"Results per page.","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"The next_cursor value from the previous page.","schema":{"type":"string"}},{"name":"team_id","required":false,"in":"query","description":"Only this team (must be one the credential covers). Useful for connections that span several teams.","example":"64b000000000000000000001","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormList"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]},"post":{"operationId":"FormsController_create","summary":"Create a form","description":"Creates a form and returns it with its endpoint URL.\n\nSend `name` (required) and any of the configuration blocks. Excluded configuration blocks return defaults in the response. If you try to configure something your plan does not include, the request is refused and no form gets created.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFormBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormResource"}}}},"400":{"description":"The body has a field that is missing, unknown or has the wrong value. `param` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"No email server with that id belongs to your team.","param":"self_email_notification.sender.server_id","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not create this form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the forms:write scope.","required":["forms:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"plan_restricted":{"summary":"plan_restricted","value":{"error":{"type":"permission_error","code":"plan_restricted","message":"You have reached your form limit, please upgrade to create a new form","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}":{"get":{"operationId":"FormsController_get","summary":"Retrieve a form","description":"Returns the form and its full configuration.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormResource"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]},"patch":{"operationId":"FormsController_update","summary":"Update a form","description":"Changes only what you send.\n\nNested objects are merged, so `{\"after_submit\": {\"page\": {\"headline\": \"Thanks!\"}}}` changes the headline and nothing else. Lists (`recipients`, `rules`) are replaced as a whole. Every rule that applies when you save a form in the dashboard applies here too.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFormBody"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormResource"}}}},"400":{"description":"The body has a field that is unknown, read-only or has the wrong value. `param` names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"No email server with that id belongs to your team.","param":"self_email_notification.sender.server_id","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not make this change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the forms:write scope.","required":["forms:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"plan_restricted":{"summary":"plan_restricted","value":{"error":{"type":"permission_error","code":"plan_restricted","message":"Please upgrade your plan to use Custom thank you page","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]},"delete":{"operationId":"FormsController_remove","summary":"Delete a form","description":"Permanently deletes the form. Its submissions, exports and connected integrations are not deleted. This cannot be undone.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormDeleted"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/self-email-notification/recipients":{"post":{"operationId":"FormsController_addRecipient","summary":"Add a recipient","description":"Adds one address to the list that receives the email on every submission and keeps the others. Adding an address that is already on the list changes nothing. To replace the whole list, PATCH `self_email_notification.recipients` instead. The free plan allows one address.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRecipientBody"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientList"}}}},"400":{"description":"The address is missing or not an email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"email must be an email","param":"email","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not change the list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the forms:write scope.","required":["forms:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"plan_restricted":{"summary":"plan_restricted","value":{"error":{"type":"permission_error","code":"plan_restricted","message":"Please upgrade your plan to add multiple email addresses.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/self-email-notification/recipients/{email}":{"delete":{"operationId":"FormsController_removeRecipient","summary":"Remove a recipient","description":"Removes one address from the list that receives the email on every submission and keeps the others.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"email","required":true,"in":"path","description":"The address to remove, percent-encoded (a `+` becomes `%2B`).","example":"me@company.com","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientList"}}}},"400":{"description":"The path does not hold an email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"email must be an email","param":"email","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or the address is not on the list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"recipient_not_found":{"summary":"recipient_not_found","value":{"error":{"type":"invalid_request_error","code":"recipient_not_found","message":"That address is not on the list.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/images":{"post":{"operationId":"FormsController_uploadImage","summary":"Upload an image","description":"Uploads a logo and returns a URL. The upload does not change the form. You must put the response `url` into the corresponding field with a PATCH.\n\nSend the request as `multipart/form-data` with two parts: `file`, the image, and `use`, where it will be shown.\n\n| `use` | Put the returned `url` in |\n|---|---|\n| `self_email_notification_logo` | `self_email_notification.logo_url` (the email you get on every submission) |\n| `auto_response_logo` | `auto_response.logo_url` (the reply the person who submitted receives) |\n| `after_submit_logo` | `after_submit.page.logo_url` (the thank you page) |\n| `after_submit_logo_dark` | `after_submit.page.logo_dark_url` (the thank you page in its dark look) |\n\nUploads need a paid plan. Images may be up to 5 MB.\n\n`self_email_notification_logo` and `auto_response_logo` only accept PNG, JPEG or GIF because email clients do not display WebP or SVG. The thank you page placements take all five.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","use"],"properties":{"file":{"type":"string","format":"binary","description":"PNG, JPEG or GIF, up to 5 MB. The thank you page placements also take WebP and SVG; the email placements refuse them because email clients do not display those formats."},"use":{"type":"string","enum":["self_email_notification_logo","auto_response_logo","after_submit_logo","after_submit_logo_dark"],"description":"Where the image will be shown. One of `self_email_notification_logo` (the email you get on every submission), `auto_response_logo` (the reply the person who submitted receives), `after_submit_logo` (the thank you page) or `after_submit_logo_dark` (the thank you page in its dark look)."},"name":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"A name for the file. Letters, digits, dashes and underscores."}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedImage"}}}},"400":{"description":"The image part is missing, not an image, of a format the placement does not take, or `use` is unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"Email clients do not display WebP or SVG images. Use a PNG, JPEG or GIF for email logos.","param":"file","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not upload here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the forms:write scope.","required":["forms:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"plan_restricted":{"summary":"plan_restricted","value":{"error":{"type":"permission_error","code":"plan_restricted","message":"You need to upgrade your plan to upload your logo & files","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"413":{"description":"The image is larger than 5 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payload_too_large":{"summary":"payload_too_large","value":{"error":{"type":"invalid_request_error","code":"payload_too_large","message":"The request body is too large. JSON bodies may be up to 1 MB, image uploads up to 5 MB.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/fields":{"get":{"operationId":"FormsController_fields","summary":"List a form's fields","description":"Returns the field names carried by the newest 2,000 submissions of this form, sorted by most used first. Each field returns with how many of them carry it and when the newest one arrived. Only the first 200 names are shown.\n\nUse the counts to tell a name the form still collects from one that was renamed. For example, a name on 11 of 2,000 submissions that was last seen in March is probably a renamed or outdated field, and not the one to filter on.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormFields"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/webhooks":{"get":{"operationId":"WebhooksController_list","summary":"List webhooks","description":"The form's webhooks. One per form for now; the list shape stays when more are allowed.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]},"post":{"operationId":"WebhooksController_create","summary":"Add a webhook","description":"Adds a webhook that receives every submission as a JSON POST. The response carries the signing `secret` once; store it.\n\nA form takes up to 10 webhooks (`webhook_limit_reached` past that) and one webhook per URL (`webhook_url_taken`).\n\nTo add webhooks, you need a plan that includes them.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWebhookResource"}}}},"400":{"description":"The url is missing or not an http(s) URL, or an event is unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"url must be an http or https URL","param":"url","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not add a webhook.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the forms:write scope.","required":["forms:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"plan_restricted":{"summary":"plan_restricted","value":{"error":{"type":"permission_error","code":"plan_restricted","message":"Please upgrade your plan to enable Webhooks","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"409":{"description":"The form is at its limit, or another webhook already posts to this URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"webhook_limit_reached":{"summary":"webhook_limit_reached","value":{"error":{"type":"invalid_request_error","code":"webhook_limit_reached","message":"This form has its 10 webhooks. Delete one to add another.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_url_taken":{"summary":"webhook_url_taken","value":{"error":{"type":"invalid_request_error","code":"webhook_url_taken","message":"Another webhook on this form already posts to this URL. Change the URL, or update that webhook.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/webhooks/{webhook_id}":{"get":{"operationId":"WebhooksController_get","summary":"Retrieve a webhook","description":"One webhook, without its secret.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"webhook_id","required":true,"in":"path","description":"The webhook's id, from the list or from the response that created it","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResource"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such webhook on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_not_found":{"summary":"webhook_not_found","value":{"error":{"type":"invalid_request_error","code":"webhook_not_found","message":"No webhook with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]},"patch":{"operationId":"WebhooksController_update","summary":"Update a webhook","description":"Changes only what you send: url, enabled, description, events. The secret does not change.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"webhook_id","required":true,"in":"path","description":"The webhook's id, from the list or from the response that created it","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookBody"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResource"}}}},"400":{"description":"A field has the wrong value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"url must be an http or https URL","param":"url","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not change this webhook.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the forms:write scope.","required":["forms:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"plan_restricted":{"summary":"plan_restricted","value":{"error":{"type":"permission_error","code":"plan_restricted","message":"Please upgrade your plan to enable Webhooks","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such webhook on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_not_found":{"summary":"webhook_not_found","value":{"error":{"type":"invalid_request_error","code":"webhook_not_found","message":"No webhook with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]},"delete":{"operationId":"WebhooksController_remove","summary":"Delete a webhook","description":"Removes the webhook, so no later submission is delivered to it. A delivery already queued or being retried can still complete. Adding it again issues a new secret.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"webhook_id","required":true,"in":"path","description":"The webhook's id, from the list or from the response that created it","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeleted"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such webhook on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_not_found":{"summary":"webhook_not_found","value":{"error":{"type":"invalid_request_error","code":"webhook_not_found","message":"No webhook with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/webhooks/{webhook_id}/deliveries":{"get":{"operationId":"WebhooksController_deliveries","summary":"List deliveries","description":"The delivery log of the webhook, sorted by newest first.\n\nOne entry per submission with its latest outcome: the HTTP status your endpoint returned, plus the error text if it failed. Filter with `status`; page with `limit` and `before`.\n\nDeliveries are kept for 18 months.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"webhook_id","required":true,"in":"path","description":"The webhook's id, from the list or from the response that created it","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Only deliveries in this state. retrying means another attempt is scheduled.","schema":{"enum":["succeeded","failed","retrying","pending","skipped"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Page size, 1 to 100. Defaults to 25.","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"before","required":false,"in":"query","example":"2026-09-13T12:00:00.000Z","description":"Deliveries before this time: pass the previous page's last occurred_at to get the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"description":"A filter has the wrong value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"status must be one of the following values: succeeded, failed, retrying, pending, skipped","param":"status","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such webhook on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_not_found":{"summary":"webhook_not_found","value":{"error":{"type":"invalid_request_error","code":"webhook_not_found","message":"No webhook with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"503":{"description":"The delivery log could not be read. Try again in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"delivery_log_unavailable":{"summary":"delivery_log_unavailable","value":{"error":{"type":"api_error","code":"delivery_log_unavailable","message":"The delivery log could not be read just now. Try again in a minute.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/webhooks/{webhook_id}/deliveries/{submission_id}":{"get":{"operationId":"WebhooksController_delivery","summary":"Retrieve a delivery","description":"The latest outcome of one submission's delivery to this webhook.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"webhook_id","required":true,"in":"path","description":"The webhook's id, from the list or from the response that created it","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","schema":{"type":"string"}},{"name":"submission_id","required":true,"in":"path","description":"The submission's id, from the submissions list or from a delivery","example":"64c000000000000000000001","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryResource"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form, webhook or delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_not_found":{"summary":"webhook_not_found","value":{"error":{"type":"invalid_request_error","code":"webhook_not_found","message":"No webhook with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"delivery_not_found":{"summary":"delivery_not_found","value":{"error":{"type":"invalid_request_error","code":"delivery_not_found","message":"No delivery of that submission to this webhook is on record. Deliveries are kept for 18 months.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"503":{"description":"The delivery log could not be read. Try again in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"delivery_log_unavailable":{"summary":"delivery_log_unavailable","value":{"error":{"type":"api_error","code":"delivery_log_unavailable","message":"The delivery log could not be read just now. Try again in a minute.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/webhooks/{webhook_id}/deliveries/{submission_id}/redeliver":{"post":{"operationId":"WebhooksController_redeliver","summary":"Send a submission again","description":"Queues the submission for the delivery worker again, for this webhook only.\n\nThe delivery body is rebuilt and signed just like the first delivery, with a fresh timestamp. Even a paused webhook receives it, because you targeted it directly by name.\n\nThe response confirms the submission was queued, not that it was delivered: read the delivery for the outcome. Sending again repeats whatever the endpoint does with it.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"webhook_id","required":true,"in":"path","description":"The webhook's id, from the list or from the response that created it","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","schema":{"type":"string"}},{"name":"submission_id","required":true,"in":"path","description":"The submission's id, from the submissions list or from a delivery","example":"64c000000000000000000001","schema":{"type":"string"}}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedeliveryQueued"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form, webhook or submission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"webhook_not_found":{"summary":"webhook_not_found","value":{"error":{"type":"invalid_request_error","code":"webhook_not_found","message":"No webhook with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"409":{"description":"The form keeps no submissions, so there is nothing to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"submission_not_stored":{"summary":"submission_not_stored","value":{"error":{"type":"invalid_request_error","code":"submission_not_stored","message":"This form keeps no submissions, so there is nothing to send again. Turn on storage to retry deliveries.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"503":{"description":"The delivery could not be started. Try again in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"redelivery_unavailable":{"summary":"redelivery_unavailable","value":{"error":{"type":"api_error","code":"redelivery_unavailable","message":"Could not send it again just now. Try in a minute.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/email-servers":{"get":{"operationId":"EmailServersController_list","summary":"List email servers","description":"The email servers your teams have set up in the dashboard, to use as a form's notification sender: `email_server` is your own SMTP server, `premium_server` a sending domain verified with formcarry. Put the `id` in `self_email_notification.sender.server_id`. Servers are managed in the dashboard.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailServerList"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["forms"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/submissions":{"get":{"operationId":"SubmissionsController_list","summary":"List submissions","description":"Returns a form's submissions, newest first (unless you ask for the oldest).\n\nNarrow the list with the filters below; several filters combine with AND.\n\nTo get the next page, pass a response's next_cursor as cursor and keep going until next_cursor is null. A page can occasionally hold fewer than limit results even when more exist, so rely on next_cursor, not on the page size.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Which submissions to include: the inbox (default), spam, or both.","schema":{"default":"inbox","enum":["inbox","spam","all"],"type":"string"}},{"name":"read","required":false,"in":"query","description":"Only submissions that have (true) or have not (false) been read in the dashboard.","schema":{"enum":["true","false"],"type":"string"}},{"name":"has_attachments","required":false,"in":"query","description":"Only submissions with (true) or without (false) uploaded files.","schema":{"enum":["true","false"],"type":"string"}},{"name":"created_after","required":false,"in":"query","description":"Only submissions created at or after this time (RFC 3339, or milliseconds since the epoch).","example":"2026-01-01T00:00:00Z","schema":{"type":"string"}},{"name":"created_before","required":false,"in":"query","description":"Only submissions created before this time (RFC 3339, or milliseconds since the epoch).","example":"2026-02-01T00:00:00Z","schema":{"type":"string"}},{"name":"country","required":false,"in":"query","description":"Only submissions sent from this country. Two-letter uppercase code. For several, separate them with commas. Max 20.","example":"DE,AT,CH","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","description":"Only submissions where any field contains this text, matched literally and without case. 2 to 512 characters. On some forms a field that only appeared in very old submissions may be missed, so name that field with a field filter.","example":"pricing","schema":{"type":"string"}},{"name":"order","required":false,"in":"query","description":"Newest first (the default) or oldest first.","schema":{"default":"newest","enum":["newest","oldest"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Results per page.","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"The next_cursor value from the previous page.","schema":{"type":"string"}},{"name":"fields","required":false,"in":"query","description":"Only return these submitted fields, separated by commas. Everything else about the submission still comes back.","example":"email,name","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionList"}}}},"400":{"description":"A query parameter is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"limit must not be greater than 100","param":"limit","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_cursor":{"summary":"invalid_cursor","value":{"error":{"type":"invalid_request_error","code":"invalid_cursor","message":"The cursor is malformed or was issued for a different query.","param":"cursor","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"422":{"description":"The request took too long; narrow the date range and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"query_timeout":{"summary":"query_timeout","value":{"error":{"type":"invalid_request_error","code":"query_timeout","message":"The request did not finish in time. Narrow the date range with created_after and created_before and try again.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/submissions/summary":{"get":{"operationId":"SubmissionsController_summary","summary":"Count submissions","description":"Counts the submissions matching the filters instead of returning them, so you can see the size of an answer before you page through it. Takes the same filters as the list.\n\nPass group_by to count by day, week, month, country, spam, read or a submitted field, and the largest 20 groups come back with the rest in `other`. A count that does not finish in time returns what it reached with `exact: false`; narrow the date range for an exact one.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Which submissions to include: the inbox (default), spam, or both.","schema":{"default":"inbox","enum":["inbox","spam","all"],"type":"string"}},{"name":"read","required":false,"in":"query","description":"Only submissions that have (true) or have not (false) been read in the dashboard.","schema":{"enum":["true","false"],"type":"string"}},{"name":"has_attachments","required":false,"in":"query","description":"Only submissions with (true) or without (false) uploaded files.","schema":{"enum":["true","false"],"type":"string"}},{"name":"created_after","required":false,"in":"query","description":"Only submissions created at or after this time (RFC 3339, or milliseconds since the epoch).","example":"2026-01-01T00:00:00Z","schema":{"type":"string"}},{"name":"created_before","required":false,"in":"query","description":"Only submissions created before this time (RFC 3339, or milliseconds since the epoch).","example":"2026-02-01T00:00:00Z","schema":{"type":"string"}},{"name":"country","required":false,"in":"query","description":"Only submissions sent from this country. Two-letter uppercase code. For several, separate them with commas. Max 20.","example":"DE,AT,CH","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","description":"Only submissions where any field contains this text, matched literally and without case. 2 to 512 characters. On some forms a field that only appeared in very old submissions may be missed, so name that field with a field filter.","example":"pricing","schema":{"type":"string"}},{"name":"group_by","required":false,"in":"query","description":"Count by this instead of returning one total: day, week, month, country, spam, read, or field:<name> for a submitted field. Leave it out for the total alone.","example":"country","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionSummary"}}}},"400":{"description":"A query parameter is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"group_by must be one of day, week, month, country, spam, read, or field:<name>.","param":"group_by","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"422":{"description":"The request took too long; narrow the date range and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"query_timeout":{"summary":"query_timeout","value":{"error":{"type":"invalid_request_error","code":"query_timeout","message":"The request did not finish in time. Narrow the date range with created_after and created_before and try again.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/submissions/deliveries":{"get":{"operationId":"SubmissionsController_deliveries","summary":"Read what happened to submissions","description":"Returns what happened to up to 20 submissions after they arrived: every email, webhook, Zapier zap and integration each one was sent to, along with the latest outcome of each.\n\nOne row per target, and each submission gets a status rolled up from its rows. Rows land within seconds of the submission, so one received a moment ago can have none yet. The log is kept 18 months, so an older submission responds with no rows and a null status rather than 404. Any ids the form does not have are left out.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"submission_ids","required":true,"in":"query","description":"The submissions to read, separated by commas. 1 to 20 ids of this form. Ids the form does not have are left out.","example":"64c000000000000000000001,64c000000000000000000002","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionDeliveriesList"}}}},"400":{"description":"A query parameter is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"submission_ids takes 1 to 20 submission ids, separated by commas.","param":"submission_ids","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"503":{"description":"The delivery log could not be read. Try again in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"delivery_log_unavailable":{"summary":"delivery_log_unavailable","value":{"error":{"type":"api_error","code":"delivery_log_unavailable","message":"The delivery log could not be read just now. Try again in a minute.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/submissions/{submission_id}":{"get":{"operationId":"SubmissionsController_get","summary":"Retrieve a submission","description":"Returns one submission with its fields and uploaded files.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"submission_id","required":true,"in":"path","description":"The submission's id","example":"64c000000000000000000001","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResource"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]},"delete":{"operationId":"SubmissionsController_remove","summary":"Delete a submission","description":"Permanently deletes the submission. Files uploaded with it are not deleted. This cannot be undone.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"submission_id","required":true,"in":"path","description":"The submission's id","example":"64c000000000000000000001","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionDeleted"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/submissions/{submission_id}/spam":{"post":{"operationId":"SubmissionsController_spam","summary":"Mark a submission as spam","description":"Moves the submission to spam. Spam is left out of lists unless you ask for it with status=spam or status=all.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"submission_id","required":true,"in":"path","description":"The submission's id","example":"64c000000000000000000001","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResource"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/forms/{form_id}/submissions/{submission_id}/restore":{"post":{"operationId":"SubmissionsController_restore","summary":"Restore a submission from spam","description":"Moves a spam submission back to the inbox.","parameters":[{"name":"form_id","required":true,"in":"path","description":"The form's id, as shown in the dashboard and in the form's endpoint URL","example":"AbC123xyz","schema":{"type":"string"}},{"name":"submission_id","required":true,"in":"path","description":"The submission's id","example":"64c000000000000000000001","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResource"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"404":{"description":"No such form for this key, or no such submission on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"form_not_found":{"summary":"form_not_found","value":{"error":{"type":"invalid_request_error","code":"form_not_found","message":"No form with that id is accessible with this key.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"submission_not_found":{"summary":"submission_not_found","value":{"error":{"type":"invalid_request_error","code":"submission_not_found","message":"No submission with that id exists on this form.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/submissions":{"get":{"operationId":"SubmissionSearchController_search","summary":"Search submissions across forms","description":"Searches the 25 most recently active forms this key can read and returns the matches with the form each one came from.\n\nTakes the same filters as a form's own list. Matches come grouped by form, and the response carries `complete: false` when the search did not reach every form or every match; narrow it with form_ids, team_id or a date range.\n\nFor one form, use its own list, which pages through everything with a cursor.","parameters":[{"name":"status","required":false,"in":"query","description":"Which submissions to include: the inbox (default), spam, or both.","schema":{"default":"inbox","enum":["inbox","spam","all"],"type":"string"}},{"name":"read","required":false,"in":"query","description":"Only submissions that have (true) or have not (false) been read in the dashboard.","schema":{"enum":["true","false"],"type":"string"}},{"name":"has_attachments","required":false,"in":"query","description":"Only submissions with (true) or without (false) uploaded files.","schema":{"enum":["true","false"],"type":"string"}},{"name":"created_after","required":false,"in":"query","description":"Only submissions created at or after this time (RFC 3339, or milliseconds since the epoch).","example":"2026-01-01T00:00:00Z","schema":{"type":"string"}},{"name":"created_before","required":false,"in":"query","description":"Only submissions created before this time (RFC 3339, or milliseconds since the epoch).","example":"2026-02-01T00:00:00Z","schema":{"type":"string"}},{"name":"country","required":false,"in":"query","description":"Only submissions sent from this country. Two-letter uppercase code. For several, separate them with commas. Max 20.","example":"DE,AT,CH","schema":{"type":"string"}},{"name":"q","required":false,"in":"query","description":"Only submissions where any field contains this text, matched literally and without case. 2 to 512 characters. On some forms a field that only appeared in very old submissions may be missed, so name that field with a field filter.","example":"pricing","schema":{"type":"string"}},{"name":"order","required":false,"in":"query","description":"Newest first (the default) or oldest first.","schema":{"default":"newest","enum":["newest","oldest"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Matches to return in total across every form searched. This search has no pages.","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"fields","required":false,"in":"query","description":"Only return these submitted fields, separated by commas. Everything else about the submission still comes back.","example":"email,name","schema":{"type":"string"}},{"name":"team_id","required":false,"in":"query","description":"Search this team only. Defaults to every team the key covers.","example":"64b000000000000000000001","schema":{"type":"string"}},{"name":"form_ids","required":false,"in":"query","description":"Search only these forms, separated by commas. Forms the key cannot read are left out whether or not you name them. Defaults to the 25 most recently active forms the key can read.","example":"AbC123xyz,DeF456uvw","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionSearchList"}}}},"400":{"description":"A query parameter is wrong.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_parameter":{"summary":"invalid_parameter","value":{"error":{"type":"invalid_request_error","code":"invalid_parameter","message":"This key or connection does not cover that team.","param":"team_id","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Too many searches at once for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["submissions"],"security":[{"api_key":[]}]}},"/v1/me":{"get":{"operationId":"MeController_me","summary":"Retrieve the current key or connection","description":"Returns the key or app connection used for this request: its scopes, and which teams and forms it can access. Handy to check what a credential is allowed to do.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"The request carried no usable key or token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing_bearer":{"summary":"missing_bearer","value":{"error":{"type":"authentication_error","code":"missing_bearer","message":"Send your key as \"Authorization: Bearer fc_live_...\" on every request.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"invalid_key":{"summary":"invalid_key","value":{"error":{"type":"authentication_error","code":"invalid_key","message":"This API key or access token is unknown, revoked or expired.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"wrong_audience":{"summary":"wrong_audience","value":{"error":{"type":"authentication_error","code":"wrong_audience","message":"This access token was issued for a different resource. Authorize again for this server.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"403":{"description":"The key is valid but may not do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"permission_error","code":"insufficient_scope","message":"This key is missing the submissions:write scope.","required":["submissions:write"],"request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"form_access_restricted":{"summary":"form_access_restricted","value":{"error":{"type":"permission_error","code":"form_access_restricted","message":"This key is restricted to specific forms and cannot create new ones.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"team_inactive":{"summary":"team_inactive","value":{"error":{"type":"permission_error","code":"team_inactive","message":"The team that owns this key is not active.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"owner_unverified":{"summary":"owner_unverified","value":{"error":{"type":"permission_error","code":"owner_unverified","message":"The team owner must verify their email address before the API can be used.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}},"429":{"description":"Slow down and retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}},"scan_concurrency":{"summary":"scan_concurrency","value":{"error":{"type":"rate_limit_error","code":"scan_concurrency","message":"At most 2 filtered submission requests may run at once per key. Wait for the running ones to finish.","request_id":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}}}}}}}},"tags":["me"],"security":[{"api_key":[]}]}},"/v1/health":{"get":{"operationId":"HealthController_health","summary":"Check that the API is up","description":"No authentication needed.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"example":{"status":"ok"}}}}}},"tags":["health"]}}},"info":{"title":"formcarry API","description":"Welcome to the formcarry API.\n\nAuthenticate every request with an API key from your team's API page in the dashboard, sent as `Authorization: Bearer fc_live_...`.\nRequests and responses are JSON.\n\nLists are paginated with a cursor: pass a response's `next_cursor` as `cursor` to get the next page, until `next_cursor` is null.\n\nErrors return a `code` you can act on and a `message` you can show. Every response includes an `X-Request-Id` header; quote it when you contact support.","version":"1","contact":{}},"tags":[{"name":"forms","description":"Your forms"},{"name":"submissions","description":"Submissions received by a form"},{"name":"me","description":"The key you are using"},{"name":"health","description":"Service status"}],"servers":[{"url":"https://api.formcarry.com"}],"components":{"securitySchemes":{"api_key":{"scheme":"bearer","bearerFormat":"fc_live_...","type":"http"}},"schemas":{"SubmissionCounts":{"type":"object","properties":{"this_month":{"type":"number","description":"Submissions received this calendar month."},"all_time":{"type":"number","nullable":true,"description":"Submissions received since the form was created."}},"required":["this_month","all_time"]},"StorageBlock":{"type":"object","properties":{"store_submissions":{"type":"boolean","description":"When false, submissions are forwarded by email and webhook but nothing is stored."},"keep_for":{"type":"string","enum":["30_days","60_days","90_days","180_days","365_days","forever"],"description":"How long stored submissions are kept before they are removed."}}},"CaptchaBlock":{"type":"object","properties":{"provider":{"type":"string","enum":["none","recaptcha","hcaptcha","turnstile"],"description":"Which captcha your form embeds. formcarry verifies the response with this secret key."},"secret_key":{"type":"string","nullable":true,"maxLength":512,"description":"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.","writeOnly":true},"secret_key_set":{"type":"boolean","readOnly":true,"description":"Whether a secret key is stored. Read only: ignored on a write, so a form read and sent back whole is fine."}}},"SpamBlock":{"type":"object","properties":{"protection":{"type":"boolean","description":"formcarry's built-in spam filter."},"captcha":{"$ref":"#/components/schemas/CaptchaBlock"}}},"SelfEmailNotificationTemplateBlock":{"type":"object","properties":{"type":{"type":"string","enum":["formcarry","custom"],"description":"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":{"type":"string","enum":["formal","fancy"],"description":"The built-in theme, used when type is formcarry."},"html":{"type":"string","nullable":true,"maxLength":200000,"description":"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."}}},"SenderBlock":{"type":"object","properties":{"type":{"type":"string","enum":["formcarry","email_server","premium_server"],"description":"formcarry: sent from formcarry. email_server: one of your own SMTP servers. premium_server: one of your verified sending domains."},"server_id":{"type":"string","nullable":true,"maxLength":64,"description":"The id of the server, from GET /v1/email-servers. Required for email_server and premium_server, null for formcarry."},"name":{"type":"string","nullable":true,"maxLength":128,"description":"Sender name, premium_server only. Null for the other types."},"email":{"type":"string","nullable":true,"maxLength":320,"description":"Sender address, premium_server only. Must belong to the verified domain. Null for the other types."}}},"SelfEmailNotificationBlock":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Send an email to the recipients on every submission."},"recipients":{"description":"Who receives the email. Replaces the whole list. The free plan allows one address.","example":["me@company.com"],"type":"array","items":{"type":"string"}},"include_spam":{"type":"boolean","description":"Also send the email for submissions the spam filter flagged."},"subject":{"type":"string","nullable":true,"maxLength":256,"description":"Email subject. null uses formcarry's default."},"logo_url":{"type":"string","nullable":true,"maxLength":2048,"description":"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.","example":"https://example.com/logo.png"},"logo_height":{"type":"number","nullable":true,"minimum":16,"maximum":400,"description":"Logo height in pixels. null lets the template decide."},"template":{"$ref":"#/components/schemas/SelfEmailNotificationTemplateBlock"},"sender":{"$ref":"#/components/schemas/SenderBlock"}}},"AutoResponseTemplateBlock":{"type":"object","properties":{"type":{"type":"string","enum":["formcarry","custom"],"description":"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":{"type":"string","enum":["formal","fancy"],"description":"The built-in theme, used when type is formcarry."},"message":{"type":"string","nullable":true,"maxLength":20000,"description":"The message body, used when type is formcarry."},"html":{"type":"string","nullable":true,"maxLength":200000,"description":"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."}}},"AutoResponseBlock":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Send a reply to the person who submitted the form (their email field is used as the address)."},"subject":{"type":"string","nullable":true,"maxLength":256,"description":"Subject of the reply."},"from_name":{"type":"string","nullable":true,"maxLength":128,"description":"The name the reply appears to come from."},"logo_url":{"type":"string","nullable":true,"maxLength":2048,"description":"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.","example":"https://example.com/logo.png"},"logo_height":{"type":"number","nullable":true,"minimum":16,"maximum":400,"description":"Logo height in pixels. null lets the template decide."},"template":{"$ref":"#/components/schemas/AutoResponseTemplateBlock"}}},"PageButtonBlock":{"type":"object","properties":{"text":{"type":"string","nullable":true,"maxLength":64,"description":"Button label. null hides the button."},"url":{"type":"string","nullable":true,"maxLength":2048,"description":"Where the button leads.","example":"https://example.com/thanks"}}},"AfterSubmitPageBlock":{"type":"object","properties":{"theme":{"type":"string","enum":["sweet","fancy","formal"]},"mode":{"type":"string","enum":["light","dark","system"],"description":"Light or dark colours, or follow the visitor's system setting."},"headline":{"type":"string","nullable":true,"maxLength":256,"description":"The page title.","example":"Thank you!"},"message":{"type":"string","nullable":true,"maxLength":2000,"description":"The text under the title.","example":"We have received your submission"},"logo_url":{"type":"string","nullable":true,"maxLength":2048,"description":"Logo for the light look.","example":"https://example.com/thanks"},"logo_dark_url":{"type":"string","nullable":true,"maxLength":2048,"description":"Logo for the dark look.","example":"https://example.com/thanks"},"logo_size":{"type":"string","enum":["normal","big"]},"primary_color":{"type":"string","nullable":true,"maxLength":32,"description":"A CSS colour.","example":"#0f766e"},"secondary_color":{"type":"string","nullable":true,"maxLength":32,"description":"A CSS colour.","example":"#f0fdfa"},"return_button":{"description":"The button that sends the visitor back to your site.","allOf":[{"$ref":"#/components/schemas/PageButtonBlock"}]},"download_button":{"description":"An optional second button, for example to a file.","allOf":[{"$ref":"#/components/schemas/PageButtonBlock"}]}}},"AfterSubmitRedirectBlock":{"type":"object","properties":{"success_url":{"type":"string","nullable":true,"maxLength":2048,"description":"Where the visitor goes after a successful submission.","example":"https://example.com/thanks"},"fail_url":{"type":"string","nullable":true,"maxLength":2048,"description":"Where the visitor goes when the submission is rejected. null uses success_url.","example":"https://example.com/thanks"},"append_submission_to_url":{"type":"boolean","description":"Append the submitted fields to the redirect URL as query parameters."}}},"AfterSubmitBlock":{"type":"object","properties":{"type":{"type":"string","enum":["formcarry_page","redirect"],"description":"formcarry_page: show formcarry's thank you page. redirect: send the visitor to your own URL."},"page":{"$ref":"#/components/schemas/AfterSubmitPageBlock"},"redirect":{"$ref":"#/components/schemas/AfterSubmitRedirectBlock"}}},"WebhookSigning":{"type":"object","properties":{"algorithm":{"type":"string","example":"hmac-sha256"},"header":{"type":"string","example":"X-Formcarry-Signature"}},"required":["algorithm","header"]},"WebhookLastDelivery":{"type":"object","properties":{"at":{"type":"string","example":"2026-09-13T12:00:00.000Z"},"status":{"type":"string","enum":["succeeded","failed"]},"response_status":{"type":"number","nullable":true,"example":200},"attempt":{"type":"number","example":1}},"required":["at","status","response_status","attempt"]},"WebhookResource":{"type":"object","properties":{"id":{"type":"string","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","readOnly":true},"url":{"type":"string","example":"https://example.com/hooks/formcarry"},"enabled":{"type":"boolean"},"description":{"type":"string","nullable":true,"example":"CRM sync"},"events":{"example":["submission.created"],"type":"array","items":{"type":"string"}},"signing":{"description":"How deliveries are signed: an HMAC-SHA256 of \"<timestamp>.<raw body>\" with the secret, sent as \"t=<unix seconds>,v1=<hex>\" in this header. Recompute it over the raw body you received, compare in constant time, and refuse a timestamp older than a few minutes. Retries are signed again with a fresh timestamp.","allOf":[{"$ref":"#/components/schemas/WebhookSigning"}]},"last_delivery":{"nullable":true,"readOnly":true,"description":"Always null: the delivery log is the record, at GET .../webhooks/{webhook_id}/deliveries.","allOf":[{"$ref":"#/components/schemas/WebhookLastDelivery"}]},"created_at":{"type":"string","example":"2026-09-13T12:00:00.000Z","readOnly":true}},"required":["id","url","enabled","description","events","signing","last_delivery","created_at"]},"ValidationCheck":{"type":"object","properties":{"type":{"type":"string","enum":["required","email","url","phone_number","integer","min_length","max_length","contains","not_contains"]},"value":{"type":"string","nullable":true,"maxLength":256,"description":"The argument for min_length, max_length, contains and not_contains."},"message":{"type":"string","nullable":true,"maxLength":512,"description":"Replaces the default error message shown to the visitor."}},"required":["type"]},"ValidationRule":{"type":"object","properties":{"field":{"type":"string","maxLength":128,"description":"The name of the field in your HTML form.","example":"email"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ValidationCheck"}}},"required":["field","checks"]},"ValidationBlock":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Reject submissions that fail the rules."},"rules":{"description":"Replaces the whole list.","type":"array","items":{"$ref":"#/components/schemas/ValidationRule"}}}},"FormResource":{"type":"object","properties":{"id":{"type":"string","example":"AbC123xyz","readOnly":true},"team_id":{"type":"string","readOnly":true},"name":{"type":"string","example":"Contact form"},"endpoint":{"type":"string","example":"https://formcarry.com/s/AbC123xyz","readOnly":true,"description":"Where your HTML form posts."},"active":{"type":"boolean","description":"Inactive forms reject submissions."},"avatar":{"type":"string","example":"🚀","readOnly":true},"folder_id":{"type":"string","nullable":true,"description":"The folder the form is filed in, or null for none."},"created_at":{"type":"string","example":"2026-01-15T10:00:00.000Z","readOnly":true},"last_submission_at":{"type":"string","nullable":true,"readOnly":true,"description":"When the newest submission arrived, or null before the first."},"submissions":{"readOnly":true,"allOf":[{"$ref":"#/components/schemas/SubmissionCounts"}]},"storage":{"$ref":"#/components/schemas/StorageBlock"},"spam":{"$ref":"#/components/schemas/SpamBlock"},"self_email_notification":{"$ref":"#/components/schemas/SelfEmailNotificationBlock"},"auto_response":{"$ref":"#/components/schemas/AutoResponseBlock"},"after_submit":{"$ref":"#/components/schemas/AfterSubmitBlock"},"webhooks":{"readOnly":true,"description":"Managed at /v1/forms/{form_id}/webhooks; one per form for now.","type":"array","items":{"$ref":"#/components/schemas/WebhookResource"}},"validation":{"$ref":"#/components/schemas/ValidationBlock"}},"required":["id","team_id","name","endpoint","active","avatar","folder_id","created_at","last_submission_at","submissions","storage","spam","self_email_notification","auto_response","after_submit","webhooks","validation"]},"FormList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormResource"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["data","has_more","next_cursor"]},"CreateFormBody":{"type":"object","properties":{"active":{"type":"boolean","description":"Inactive forms reject submissions."},"folder_id":{"type":"string","nullable":true,"description":"The folder the form is filed in. null for no folder."},"storage":{"$ref":"#/components/schemas/StorageBlock"},"spam":{"$ref":"#/components/schemas/SpamBlock"},"self_email_notification":{"description":"The email you get on every submission.","allOf":[{"$ref":"#/components/schemas/SelfEmailNotificationBlock"}]},"auto_response":{"description":"The email the person who submitted receives.","allOf":[{"$ref":"#/components/schemas/AutoResponseBlock"}]},"after_submit":{"description":"What the visitor sees after submitting.","allOf":[{"$ref":"#/components/schemas/AfterSubmitBlock"}]},"validation":{"description":"Rules a submission must pass.","allOf":[{"$ref":"#/components/schemas/ValidationBlock"}]},"team_id":{"type":"string","description":"Team that owns the new form. Required when the credential covers several teams (OAuth connections).","example":"64b000000000000000000001"},"name":{"type":"string","maxLength":128,"example":"Contact form"}},"required":["name"]},"UpdateFormBody":{"type":"object","properties":{"name":{"type":"string","maxLength":128},"active":{"type":"boolean","description":"Inactive forms reject submissions."},"folder_id":{"type":"string","nullable":true,"description":"The folder the form is filed in. null for no folder."},"storage":{"$ref":"#/components/schemas/StorageBlock"},"spam":{"$ref":"#/components/schemas/SpamBlock"},"self_email_notification":{"description":"The email you get on every submission.","allOf":[{"$ref":"#/components/schemas/SelfEmailNotificationBlock"}]},"auto_response":{"description":"The email the person who submitted receives.","allOf":[{"$ref":"#/components/schemas/AutoResponseBlock"}]},"after_submit":{"description":"What the visitor sees after submitting.","allOf":[{"$ref":"#/components/schemas/AfterSubmitBlock"}]},"validation":{"description":"Rules a submission must pass.","allOf":[{"$ref":"#/components/schemas/ValidationBlock"}]}}},"FormDeleted":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","example":true}},"required":["id","deleted"]},"AddRecipientBody":{"type":"object","properties":{"email":{"type":"string","example":"me@company.com","description":"The address to add."}},"required":["email"]},"RecipientList":{"type":"object","properties":{"recipients":{"example":["me@company.com","sales@company.com"],"description":"The whole list after the change.","type":"array","items":{"type":"string"}}},"required":["recipients"]},"UploadedImage":{"type":"object","properties":{"url":{"type":"string","example":"https://cdn.formcarry.com/.../logo.png"}},"required":["url"]},"FormFieldUsage":{"type":"object","properties":{"name":{"type":"string","example":"email"},"count":{"type":"number","example":1984,"description":"How many of the submissions read carry this field"},"last_seen":{"type":"string","example":"2026-09-15T10:04:11.000Z","nullable":true,"description":"When the newest submission carrying it arrived"}},"required":["name","count","last_seen"]},"FormFields":{"type":"object","properties":{"data":{"description":"Most used first, at most 200 names.","type":"array","items":{"$ref":"#/components/schemas/FormFieldUsage"}},"submissions_read":{"type":"number","example":2000,"description":"How many submissions were read, newest first. Max 2,000."}},"required":["data","submissions_read"]},"WebhookList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookResource"}}},"required":["data"]},"CreateWebhookBody":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/hooks/formcarry","maxLength":2048,"description":"Where every submission is POSTed as JSON."},"enabled":{"type":"boolean","default":true,"description":"A webhook that is off keeps its settings but receives nothing."},"description":{"type":"string","nullable":true,"maxLength":128,"description":"A label for your own reference."},"events":{"type":"array","description":"What the webhook receives. Only submission.created exists today.","items":{"type":"string","enum":["submission.created"]}}},"required":["url"]},"CreatedWebhookResource":{"type":"object","properties":{"id":{"type":"string","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","readOnly":true},"url":{"type":"string","example":"https://example.com/hooks/formcarry"},"enabled":{"type":"boolean"},"description":{"type":"string","nullable":true,"example":"CRM sync"},"events":{"example":["submission.created"],"type":"array","items":{"type":"string"}},"signing":{"description":"How deliveries are signed: an HMAC-SHA256 of \"<timestamp>.<raw body>\" with the secret, sent as \"t=<unix seconds>,v1=<hex>\" in this header. Recompute it over the raw body you received, compare in constant time, and refuse a timestamp older than a few minutes. Retries are signed again with a fresh timestamp.","allOf":[{"$ref":"#/components/schemas/WebhookSigning"}]},"last_delivery":{"nullable":true,"readOnly":true,"description":"Always null: the delivery log is the record, at GET .../webhooks/{webhook_id}/deliveries.","allOf":[{"$ref":"#/components/schemas/WebhookLastDelivery"}]},"created_at":{"type":"string","example":"2026-09-13T12:00:00.000Z","readOnly":true},"secret":{"type":"string","example":"whsec_...","description":"Only in this response. Store it: it is never shown again. Every delivery carries a signature made with it (see signing)."}},"required":["id","url","enabled","description","events","signing","last_delivery","created_at","secret"]},"UpdateWebhookBody":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/hooks/formcarry","maxLength":2048},"enabled":{"type":"boolean","description":"A webhook that is off keeps its settings but receives nothing."},"description":{"type":"string","nullable":true,"maxLength":128},"events":{"type":"array","items":{"type":"string","enum":["submission.created"]}}}},"WebhookDeleted":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","example":true}},"required":["id","deleted"]},"WebhookDeliveryResource":{"type":"object","properties":{"submission_id":{"type":"string","example":"64c000000000000000000001"},"webhook_id":{"type":"string","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","description":"Empty on deliveries from before webhooks had ids."},"status":{"type":"string","enum":["succeeded","failed","retrying","pending","skipped"],"description":"The latest outcome for this submission. Retries run for up to 3 days, then the state is failed."},"code":{"type":"string","example":"ERROR_WEBHOOK_HTTP_5XX","description":"SUCCESS, or the error family of the last attempt."},"attempt":{"type":"number","nullable":true,"example":3,"description":"Attempts so far."},"http_status":{"type":"number","nullable":true,"example":502,"description":"The HTTP status your endpoint answered, when it answered."},"node_error_code":{"type":"string","nullable":true,"example":"ECONNREFUSED","description":"The network error when the endpoint did not answer."},"message":{"type":"string","nullable":true,"description":"The error text of the last attempt, up to 1024 characters."},"occurred_at":{"type":"string","example":"2026-09-13T12:00:00.000Z","description":"When the last attempt ended."}},"required":["submission_id","webhook_id","status","code","attempt","http_status","node_error_code","message","occurred_at"]},"WebhookDeliveryList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliveryResource"}},"has_more":{"type":"boolean","description":"More deliveries exist before the last one listed. Pass its occurred_at as before."}},"required":["data","has_more"]},"RedeliveryQueued":{"type":"object","properties":{"submission_id":{"type":"string","example":"64c000000000000000000001"},"webhook_id":{"type":"string","example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0"},"queued":{"type":"boolean","example":true,"description":"Queued for the delivery worker. Read the delivery for the outcome."}},"required":["submission_id","webhook_id","queued"]},"EmailServerResource":{"type":"object","properties":{"id":{"type":"string","example":"64b0000000000000000000a1"},"team_id":{"type":"string","example":"64b000000000000000000001","description":"The team the server belongs to"},"kind":{"type":"string","enum":["email_server","premium_server"],"description":"email_server: your own SMTP server. premium_server: a sending domain verified with formcarry."},"name":{"type":"string","example":"Company SMTP"},"host_or_domain":{"type":"string","example":"smtp.company.com","description":"The SMTP host, or the verified domain."},"active":{"type":"boolean","description":"Whether the server can be used as a sender right now."}},"required":["id","team_id","kind","name","host_or_domain","active"]},"EmailServerList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailServerResource"}}},"required":["data"]},"SubmissionField":{"type":"object","properties":{"key":{"type":"string","example":"email"},"value":{"type":"string","example":"ann@example.com"}},"required":["key","value"]},"SubmissionAttachment":{"type":"object","properties":{"key":{"type":"string","example":"cv"},"url":{"type":"string"},"mime_type":{"type":"string","example":"application/pdf","nullable":true}},"required":["key","url","mime_type"]},"SubmissionResource":{"type":"object","properties":{"id":{"type":"string","example":"64c000000000000000000001"},"form_id":{"type":"string","example":"AbC123xyz"},"created_at":{"type":"string","example":"2026-01-15T10:00:00.000Z"},"spam":{"type":"boolean"},"read":{"type":"boolean"},"ip":{"type":"string","nullable":true,"description":"The address the submission came from, or null when unknown."},"country":{"type":"string","nullable":true,"example":"DE","description":"Two letter uppercase code from the address, or null when unknown."},"user_agent":{"type":"string","nullable":true,"description":"The visitor's browser, as it announced itself, or null."},"referer":{"type":"string","nullable":true,"description":"The page the form was on, as the browser reported it, or null."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SubmissionField"}},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SubmissionAttachment"}}},"required":["id","form_id","created_at","spam","read","ip","country","user_agent","referer","fields","attachments"]},"SubmissionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubmissionResource"}},"has_more":{"type":"boolean","description":"Whether another page exists. When true, request it with next_cursor."},"next_cursor":{"type":"string","nullable":true}},"required":["data","has_more","next_cursor"]},"SubmissionBucket":{"type":"object","properties":{"key":{"type":"string","example":"DE","description":"The value counted. \"\" is the group with no value."},"count":{"type":"number","example":120}},"required":["key","count"]},"SubmissionSummary":{"type":"object","properties":{"total":{"type":"number","example":428,"description":"Submissions matching the filters."},"exact":{"type":"boolean","description":"False when the count did not finish in time, so total and the counts are a floor rather than the whole set. Narrow the date range for an exact answer."},"group_by":{"type":"string","nullable":true,"example":"country","description":"What the counts are grouped by, or null for the total alone."},"buckets":{"description":"Largest first, up to 20.","type":"array","items":{"$ref":"#/components/schemas/SubmissionBucket"}},"other":{"type":"number","example":12,"description":"Submissions in groups outside the 20 returned."},"truncated":{"type":"boolean","description":"True when group_by passed 10,000 distinct values, so some are missing from buckets though their submissions still count in total and other. Always false without group_by."}},"required":["total","exact","group_by","buckets","other","truncated"]},"DeliveryResource":{"type":"object","properties":{"channel":{"type":"string","enum":["self_email_notification","auto_response","webhook","zapier","integration"],"description":"Which setting of the form sent it."},"target":{"type":"string","example":"ann@example.com","description":"Who or what received it: the address for the email channels, the url for a webhook or a zap, the instance id for an integration."},"webhook_id":{"type":"string","nullable":true,"example":"whk_3f9Kq2bLm8xZpQ1rT7vWc0","description":"On webhook rows. Null on deliveries from before webhooks had ids."},"name":{"type":"string","nullable":true,"example":"Slack: new leads","description":"On integration rows: the name it has in the dashboard."},"status":{"type":"string","enum":["succeeded","failed","retrying","pending","skipped","bounced"],"description":"The latest outcome. retrying means another attempt is scheduled, for up to 3 days. bounced is email only: the receiving server accepted it and rejected it later."},"code":{"type":"string","example":"ERROR_WEBHOOK_HTTP_5XX","description":"SUCCESS, PENDING, or the reason: SKIPPED_ codes say why nothing was sent, ERROR_ codes what failed."},"attempt":{"type":"number","nullable":true,"example":3,"description":"Attempts so far."},"http_status":{"type":"number","nullable":true,"example":502,"description":"The HTTP status the endpoint answered, when it answered."},"smtp_code":{"type":"number","nullable":true,"example":550,"description":"The SMTP reply code, on email rows that got one."},"node_error_code":{"type":"string","nullable":true,"example":"ECONNREFUSED","description":"The network error when the endpoint did not answer."},"message":{"type":"string","nullable":true,"description":"The error text of the last attempt, up to 1024 characters."},"occurred_at":{"type":"string","example":"2026-09-16T10:04:12.000Z","description":"When the last attempt ended."}},"required":["channel","target","webhook_id","name","status","code","attempt","http_status","smtp_code","node_error_code","message","occurred_at"]},"SubmissionDeliveriesResource":{"type":"object","properties":{"submission_id":{"type":"string","example":"64c000000000000000000001"},"status":{"type":"string","enum":["succeeded","failed","retrying","pending","skipped","bounced","partial"],"nullable":true,"description":"One status for the submission. Skipped rows do not count against it, so a delivered email beside a switched off auto response reads succeeded. partial: some targets reached, some not. Null when nothing is on record: rows land seconds after the submission, and the log is kept 18 months."},"deliveries":{"description":"One row per target.","type":"array","items":{"$ref":"#/components/schemas/DeliveryResource"}}},"required":["submission_id","status","deliveries"]},"SubmissionDeliveriesList":{"type":"object","properties":{"data":{"description":"In the order asked, without the ids the form does not have.","type":"array","items":{"$ref":"#/components/schemas/SubmissionDeliveriesResource"}}},"required":["data"]},"SubmissionDeleted":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","example":true}},"required":["id","deleted"]},"SubmissionSearchList":{"type":"object","properties":{"data":{"description":"Matches across the forms searched, each carrying its form_id.","type":"array","items":{"$ref":"#/components/schemas/SubmissionResource"}},"forms_searched":{"type":"number","example":12,"description":"How many of forms_matched were read before the search stopped."},"forms_matched":{"type":"number","example":14,"description":"Forms picked for the search: the ones the key can read that matched form_ids, at most 25."},"complete":{"type":"boolean","description":"False when the search did not reach every form or every match. Narrow it with form_ids, a date range or team_id."}},"required":["data","forms_searched","forms_matched","complete"]},"MeKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string","example":"fc_live_1pcvCQca"},"last4":{"type":"string"},"kind":{"type":"string","enum":["standard","legacy"],"description":"standard: made on the API keys page. legacy: the team's original key, kept working under the same secret."}},"required":["id","name","prefix","last4","kind"]},"MeApp":{"type":"object","properties":{"id":{"type":"string","description":"OAuth client id"},"name":{"type":"string"}},"required":["id","name"]},"MeFormAccess":{"type":"object","properties":{"mode":{"type":"string","enum":["all","list"],"description":"all: every form of the team. list: only the forms listed in forms."},"forms":{"description":"The forms this key is limited to, when mode is list","type":"array","items":{"type":"string"}}},"required":["mode","forms"]},"MeTeam":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"example":["forms:read","submissions:read"],"type":"array","items":{"type":"string"}},"form_access":{"$ref":"#/components/schemas/MeFormAccess"}},"required":["id","name","scopes","form_access"]},"MeResponse":{"type":"object","properties":{"type":{"type":"string","enum":["key","app"],"description":"key: an API key; app: an OAuth connection"},"key":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MeKey"}]},"app":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MeApp"}]},"scopes":{"description":"Union of the per-team scopes","type":"array","items":{"type":"string"}},"teams":{"description":"Every team this credential can act on, with its own scopes","type":"array","items":{"$ref":"#/components/schemas/MeTeam"}}},"required":["type","key","app","scopes","teams"]},"ErrorBody":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","permission_error","invalid_request_error","rate_limit_error","api_error"],"example":"invalid_request_error"},"code":{"type":"string","example":"invalid_parameter"},"message":{"type":"string","example":"limit must not be greater than 100"},"param":{"type":"string","description":"The offending parameter, when there is one","example":"limit"},"required":{"description":"On insufficient_scope: the scopes the request needs. Reissue the key with them.","example":["submissions:write"],"type":"array","items":{"type":"string"}},"retry_after":{"type":"number","description":"On scan_concurrency: seconds to wait before trying again.","example":2},"request_id":{"type":"string","description":"Echoes X-Request-Id. Quote it when contacting support.","example":"2f9c1a7e-5b31-4d2e-9c0a-8e7f6d5c4b3a"}},"required":["type","code","message","request_id"]},"ErrorEnvelope":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"required":["error"]}}}}