> ## 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 custom object > Creates a new Custom Object definition. Create a Custom Object definition **Permission:** requires `manage_custom_objects`. **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. **`schema` is not enforced.** The model marks `name`, `label` and `label_plural` required but not `schema`, so an object can be created with no fields defined. ## OpenAPI ````yaml /api-reference/specs/custom-objects.json post /api/custom/objects openapi: 3.1.0 info: title: ConveYour API — Custom Objects description: >- Define custom data schemas (object types) to extend ConveYour beyond its built-in contact model. 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: Custom Objects description: >- Define custom data schemas (object types) to extend ConveYour beyond its built-in contact model. paths: /api/custom/objects: post: tags: - Custom Objects summary: Create a custom object description: >- Creates a new Custom Object definition. Create a Custom Object definition **Permission:** requires `manage_custom_objects`. **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. **`schema` is not enforced.** The model marks `name`, `label` and `label_plural` required but not `schema`, so an object can be created with no fields defined. operationId: createACustomObjectDefinition parameters: - $ref: '#/components/parameters/teams' requestBody: required: true content: application/json: schema: type: object required: - name - label - label_plural properties: name: description: >- Short, singular identifier for this object type (e.g. `"vehicle"`) — think of it like a tag. Must be unique within your org. type: string label: description: >- The singular human-readable label (e.g. `"Vehicle"`). Must be unique. type: string label_plural: description: >- The plural human-readable label (e.g. `"Vehicles"`). Must be unique. type: string schema: description: >- A **map keyed by field name** — each key is the field's identifier and each value is `{ "title": "...", "type": "..." }`. `title` and `type` are required per field; `type` must be a StudlyCase value (see `GET /api/custom/objects/schema`). This is an object, **not** an array — passing an array creates fields named `0`, `1`, `2`. type: object additionalProperties: true example: name: vehicles label: Vehicle label_plural: Vehicles schema: make: title: Make type: Text model: title: Model type: Text year: title: Year type: Number responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: $ref: '#/components/schemas/CustomObject' example: status: ok message: Custom Object created data: id: 64a1b2c3d4e5f6a7b8c9d0e1 name: vehicle label: Vehicle label_plural: Vehicles '403': $ref: '#/components/responses/Forbidden' '429': description: >- Too many requests — plan quota exhausted. Applies to **POST only**. `data` carries the usage overview for the `custom_objects` 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. CustomObject: type: object description: >- A custom object definition. Reads the schema off the stored record, so the field set varies per organization. properties: id: type: string description: Custom object ID. org_id: type: integer description: Owning organization. user_id: type: integer description: User who created it. name: type: string description: Machine-readable name. label: type: string description: Singular display label. label_plural: type: string description: Plural display label. schema: type: object description: Field definitions for records of this object. Org-defined. standalone: type: boolean description: Whether records exist independently of a contact. portal_permissions: type: object description: Learner-portal permissions. etl: type: boolean description: Whether the object syncs to the warehouse. created_at: type: integer description: Unix timestamp. updated_at: type: integer description: Unix timestamp. required: - name - label additionalProperties: description: Any org-defined field on the custom object definition. 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.