> ## 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. # Create a submission collection > Creates a new form definition. Create a form definition **Permission:** Requires `manage_forms`. **Field definitions go in `schema`, not `fields`.** `schema` is an object **keyed by field name**, each value shaped `{title, type, ...}` — e.g. `{"make": {"title": "Make", "type": "Text"}}`. A `fields` key is not part of the model and is silently dropped, so a payload using it creates the record with no fields at all. ## OpenAPI ````yaml /api-reference/specs/forms.json post /api/form/submission_collections 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/submission_collections: post: tags: - Forms summary: Create a submission collection description: >- Creates a new form definition. Create a form definition **Permission:** Requires `manage_forms`. **Field definitions go in `schema`, not `fields`.** `schema` is an object **keyed by field name**, each value shaped `{title, type, ...}` — e.g. `{"make": {"title": "Make", "type": "Text"}}`. A `fields` key is not part of the model and is silently dropped, so a payload using it creates the record with no fields at all. operationId: createAFormDefinition parameters: - $ref: '#/components/parameters/teams' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: description: Display name for the form. type: string fields: description: >- Array of field definitions for the form. Each field has a `key`, `label`, and `type`. type: array items: type: string example: name: site_survey label: Site Survey label_plural: Site Surveys schema: name: title: Form Name type: Text validators: - required locked: true answer: title: Answer type: Text responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: $ref: '#/components/schemas/SubmissionCollection' example: status: ok message: Submission Collection created data: id: 64a1b2c3d4e5f6a7b8c9d0e1 name: Annual Safety Acknowledgment '403': $ref: '#/components/responses/Forbidden' '429': description: >- Too many requests — plan quota exhausted. Applies to **POST only**. `data` carries the usage overview for the `form_submission_collections` limit (used / unused / overage) so you can show what was hit. content: application/json: schema: type: object properties: status: type: string enum: - failed description: Always `failed`. message: type: string description: Human-readable explanation. data: type: object description: >- Usage overview for the limit that was hit — used, unused and overage counts. 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. SubmissionCollection: type: object description: >- A submission collection (form definition). `schema` holds the org-defined field definitions that submissions against this collection carry. properties: id: type: string name: type: string description: Machine-readable name. label: type: string description: Singular display label. label_plural: type: string description: Plural display label. org_id: type: integer schema: type: object description: Org-defined field definitions for submissions. sections: type: array items: type: object description: Form sections. type: type: string description: Collection type. status: type: string description: Default status for new submissions. email_alert: type: boolean description: Whether submissions raise an email alert. standalone: type: boolean description: Whether submissions exist independently of a contact. portal_permissions: type: object description: Learner-portal permissions. created_at: type: integer updated_at: type: integer required: - id - name 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.