> ## 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 fields > Returns contact field definitions for the org, organized by **bucket** (a logical grouping). The response is a nested object keyed by bucket name, not a flat array. Get contact field definitions **Response shape:** `data` is a **flat array** of records. This endpoint ignores `page` — the full matching set comes back in one response. ## OpenAPI ````yaml /api-reference/specs/fields.json get /api/fields openapi: 3.1.0 info: title: ConveYour API — Fields description: Create and manage custom contact fields for your org. 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: Fields description: Create and manage custom contact fields for your org. paths: /api/fields: get: tags: - Fields summary: List fields description: >- Returns contact field definitions for the org, organized by **bucket** (a logical grouping). The response is a nested object keyed by bucket name, not a flat array. Get contact field definitions **Response shape:** `data` is a **flat array** of records. This endpoint ignores `page` — the full matching set comes back in one response. operationId: getContactFieldDefinitions parameters: - name: bucket in: query description: >- Filter to a specific bucket by name. Omit to return all buckets. Common values: `contact`, `communication`, `system`. schema: type: string - name: event in: query description: >- Filter to fields relevant to a specific event type. Returns a subset of fields keyed by event-specific identifiers. schema: type: string - $ref: '#/components/parameters/teams' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: oneOf: - type: array items: $ref: '#/components/schemas/FieldBucket' - $ref: '#/components/schemas/FieldBucket' description: >- An array of every visible bucket. If bucket= is passed, Returns that ONE bucket as a bare object instead of an array; an unmatched id yields a "bucket does not exist" error. '403': $ref: '#/components/responses/ForbiddenToken' 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. FieldBucket: type: object description: >- A field bucket (section) with its field definitions. Verified against a live GET /api/fields response. The `fields` map is org-defined — keys are field names configured for that organization. properties: id: type: integer description: Bucket ID. Used as the section key in contact responses. title: type: string description: Section title, e.g. `Profile`. type: type: string description: Section type, e.g. `profile`. order: type: integer description: Display order. addable: type: boolean description: Whether fields may be added to this bucket. editable: type: boolean description: Whether the bucket is editable. deletable: type: boolean description: Whether the bucket may be deleted. owned: type: boolean description: Whether the org owns this bucket. fields: type: object description: Field definitions keyed by field name. Keys are org-defined. additionalProperties: $ref: '#/components/schemas/Field' Field: type: object description: A field definition, plus computed permission flags. properties: id: type: integer description: Field ID. name: type: string description: Machine name; the key this field appears under in a contact record. label: type: string description: Display label. type: type: string description: Field type, e.g. text, select, id_number, related_contacts. order: type: integer description: Display order within the bucket. section: type: string description: Section name. Null is returned as an empty string. active: type: boolean description: Whether the field is active. active_profile: type: boolean description: Whether it shows on the contact profile. editable: type: boolean description: Stored editable flag from the record. visible: type: boolean description: Whether the field is visible. parent_id: type: - integer - 'null' description: Parent field ID for sub-fields; null otherwise. iskey: type: boolean description: Whether the field is a key field. rep_visible: type: boolean description: Whether it is visible in rep views. default_value: type: string description: Default value. suffix: type: string description: Display suffix. is_event: type: boolean description: Whether the field records an event. is_property: type: boolean description: Whether the field is a property. format: type: string description: Display format. values: type: array description: Allowed values. Computed from the field's configured values. values_enabled: type: boolean description: Whether the allowed-value list is enforced. owned: type: boolean description: Always true. Legacy flag from cross-org field sharing. field_editable: type: boolean description: >- Whether the field itself may be edited. False for the name field and the campaigns field. field_enabled: type: boolean description: Whether the field may be enabled or disabled. field_deletable: type: boolean description: >- Whether the field may be deleted. False for sub-fields, rep fields and all default fields. editable_type: type: boolean description: Whether the field type may be changed. form_hidden: type: boolean description: Whether the field is hidden on forms. filters: type: array description: Contact filters. Present only when type is related_contacts. custom_object_id: type: string description: Present only when type is related_custom_object. custom_object_field: type: string description: Present only when type is related_custom_object. custom_object_field_map: type: object description: Present only when type is related_custom_object. responses: ForbiddenToken: description: >- The token is missing, expired, or not permitted for this HTTP method. **This endpoint enforces no named permission**, so a 403 here never carries a `permission` field. content: application/json: example: status: failed message: Token is either expired or does not have the correct permissions data: [] 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.