> ## Documentation Index > Fetch the complete documentation index at: https://formcarry.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List submissions > Returns a form's submissions, newest first (unless you ask for the oldest). Narrow the list with the filters below; several filters combine with AND. To 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. ## OpenAPI ````yaml https://api.formcarry.com/docs-json get /v1/forms/{form_id}/submissions openapi: 3.0.0 info: title: formcarry API description: >- Welcome to the formcarry API. Authenticate every request with an API key from your team's API page in the dashboard, sent as `Authorization: Bearer fc_live_...`. Requests and responses are JSON. Lists are paginated with a cursor: pass a response's `next_cursor` as `cursor` to get the next page, until `next_cursor` is null. Errors 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: {} servers: - url: https://api.formcarry.com security: [] 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 paths: /v1/forms/{form_id}/submissions: get: tags: - submissions summary: List submissions description: >- Returns a form's submissions, newest first (unless you ask for the oldest). Narrow the list with the filters below; several filters combine with AND. To 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. operationId: SubmissionsController_list 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 security: - api_key: [] components: schemas: 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 ErrorEnvelope: type: object properties: error: $ref: '#/components/schemas/ErrorBody' required: - error 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 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 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 securitySchemes: api_key: scheme: bearer bearerFormat: fc_live_... type: http ```` ## Related topics - [Legacy Formcarry API Overview](/docs/api/legacy/overview.md) - [Legacy Submissions API — List and Filter Submissions](/docs/api/legacy/submissions.md) - [List deliveries](/docs/api-reference/forms/list-deliveries.md) - [List forms](/docs/api-reference/forms/list-forms.md) - [List a form's fields](/docs/api-reference/forms/list-a-forms-fields.md)