> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # List submissions > Returns all form submissions. Filter by form or contact. List submissions (supports filters, pagination, CSV export) **Permission:** Requires `manage_forms`, `view_form_submissions` **or** `create_form_submissions`. Denials read `view_form_submissions`. **Response shape:** `data` is an object with `count`, `page`, `pages`, `per_page`, `has_more`, `has_less` and `results`. `per_page` is honoured. ## OpenAPI ````yaml /api-reference/specs/forms.json get /api/form/submissions openapi: 3.1.0 info: title: ConveYour API — Forms description: Retrieve form definitions and manage form submissions. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Forms description: Retrieve form definitions and manage form submissions. paths: /api/form/submissions: get: tags: - Forms summary: List submissions description: >- Returns all form submissions. Filter by form or contact. List submissions (supports filters, pagination, CSV export) **Permission:** Requires `manage_forms`, `view_form_submissions` **or** `create_form_submissions`. Denials read `view_form_submissions`. **Response shape:** `data` is an object with `count`, `page`, `pages`, `per_page`, `has_more`, `has_less` and `results`. `per_page` is honoured. operationId: listSubmissionsSupportsFiltersPaginationCsvExport parameters: - name: obj_id in: query description: Filter submissions by submission collection (form) ID. schema: type: string - name: obj_name in: query description: Alternative to `obj_id` — filter by form name/slug. schema: type: string - name: search in: query description: Text search across submission data. schema: type: string - name: page in: query description: >- Page number (1-based). When omitted or `0`, returns a **flat array** with no pagination wrapper. When `1` or higher, returns a paginated envelope. Default: `0`. schema: type: integer - name: per_page in: query description: 'Records per page when `page` ≥ 1. Default: `100`.' schema: type: integer - name: format in: query description: Pass `csv` to download as a CSV file. schema: type: string - $ref: '#/components/parameters/teams' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: results: type: array items: $ref: '#/components/schemas/FormSubmission' page: type: integer description: Current page number. pages: type: integer description: Total number of pages. count: type: integer description: Total matching records across all pages. example: status: ok message: success data: - id: 64a1b2c3d4e5f6a7b8c9d0e1 obj_id: 64a1b2c3d4e5f6a7b8c9d0e2 contact_id: 64a1b2c3d4e5f6a7b8c9d0e3 status: completed progress: 1 '403': $ref: '#/components/responses/Forbidden' components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. FormSubmission: type: object description: >- A form submission. Fields come from the parent submission collection's org-defined schema, so the field set varies per organization. properties: id: type: string description: Submission ID. obj_id: type: string description: >- Parent submission collection. Required — the submission is rejected without it. org_id: type: integer description: Owning organization. con_id: type: array description: Contacts the submission belongs to. status: type: string description: Submission status. due: type: string description: Due date. sections: type: array description: Section definitions carried from the collection. created_at: type: integer description: Unix timestamp. updated_at: type: integer description: Unix timestamp. required: - obj_id additionalProperties: description: Any field defined on the parent submission collection's schema. responses: Forbidden: description: >- The token is missing or invalid, or the service account behind it lacks the permission this endpoint requires. content: application/json: example: status: failed message: Lacking necessary permission add_contacts data: permission: add_contacts securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.