> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get company custom field definitions

> Retrieve custom attribute definitions for companies, including available tag options.

**Scope**: By default, returns only global (company-level) definitions. Pass `job_id` to also include job-specific definitions for that job. Pass `list_id` to also include list-specific definitions. Optionally filter by `is_client` status. Both `job_id` and `list_id` can be combined.

**When to use**: Call this to discover company-level attribute IDs and tag option IDs before using `current_company_attribute_filters` in person search endpoints.

**Response**: Each definition includes `job_id` and `list_id` fields. Global attributes have both as null. Job-specific attributes have `job_id` set. List-specific attributes have `list_id` set.



## OpenAPI

````yaml /api-reference/openapi-v1.json get /v1/custom-fields/companies
openapi: 3.1.0
info:
  title: Stardex API (v1)
  version: 1.0.0
  description: >-
    Stardex ATS API — manage candidates, jobs, companies, and recruiting
    workflows.
servers:
  - url: https://api.stardex.ai
    description: Production API server
security:
  - bearerAuth: []
tags:
  - name: Persons
    description: Manage person records — contacts, work history, and custom fields.
  - name: Jobs
    description: Manage job postings — pipeline stages, team members, and custom fields.
  - name: Candidates
    description: Manage candidate records and pipeline stage transitions.
  - name: Companies
    description: Browse and retrieve company records.
  - name: Lists
    description: Create, search, and retrieve saved person and company lists.
  - name: Person Activities
    description: Create and manage activity records (notes, emails, meetings) for persons.
  - name: Team Members
    description: List team members for use in search filters and assignments.
  - name: Custom Fields
    description: Retrieve custom field definitions and tag options for search filters.
paths:
  /v1/custom-fields/companies:
    get:
      tags:
        - Custom Fields
      summary: Get company custom field definitions
      description: >-
        Retrieve custom attribute definitions for companies, including available
        tag options.


        **Scope**: By default, returns only global (company-level) definitions.
        Pass `job_id` to also include job-specific definitions for that job.
        Pass `list_id` to also include list-specific definitions. Optionally
        filter by `is_client` status. Both `job_id` and `list_id` can be
        combined.


        **When to use**: Call this to discover company-level attribute IDs and
        tag option IDs before using `current_company_attribute_filters` in
        person search endpoints.


        **Response**: Each definition includes `job_id` and `list_id` fields.
        Global attributes have both as null. Job-specific attributes have
        `job_id` set. List-specific attributes have `list_id` set.
      operationId: getCompanyCustomFieldDefinitions
      parameters:
        - schema:
            type: boolean
            description: Filter definitions by client/non-client company type.
          required: false
          name: is_client
          in: query
        - schema:
            type: string
            format: uuid
            description: >-
              Job UUID. When provided, returns global company attributes PLUS
              job-specific attributes for this job. Without this parameter, only
              global company attributes are returned.
          required: false
          name: job_id
          in: query
        - schema:
            type: string
            format: uuid
            description: >-
              List UUID. When provided, returns global company attributes PLUS
              list-specific attributes for this list. Without this parameter,
              only global company attributes are returned.
          required: false
          name: list_id
          in: query
      responses:
        '200':
          description: Custom field definitions fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDefinitionsResponse'
              example:
                success: true
                data:
                  - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: Seniority Level
                    description: Candidate seniority classification
                    data_type: single-select
                    job_id: null
                    list_id: null
                    tags:
                      - id: f1e2d3c4-b5a6-7890-abcd-ef1234567890
                        name: Junior
                        color: '#86efac'
                        description: null
                      - id: f2e3d4c5-b6a7-8901-bcde-f12345678901
                        name: Mid
                        color: '#93c5fd'
                        description: null
                      - id: f3e4d5c6-b7a8-9012-cdef-g12345678902
                        name: Senior
                        color: '#d8b4fe'
                        description: null
                  - id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                    name: Tags
                    description: General-purpose tags for categorization
                    data_type: multi-select
                    job_id: null
                    list_id: null
                    tags:
                      - id: a1b2c3d4-1234-5678-9abc-def012345678
                        name: Banking
                        color: '#fde68a'
                        description: null
                      - id: a2b3c4d5-2345-6789-0abc-def123456789
                        name: Fintech
                        color: '#a5f3fc'
                        description: null
                      - id: a3b4c5d6-3456-7890-1abc-def234567890
                        name: Referred
                        color: '#fca5a5'
                        description: null
                  - id: c3d4e5f6-a7b8-9012-cdef-123456789012
                    name: Years of Experience
                    description: Total years of professional experience
                    data_type: integer
                    job_id: null
                    list_id: null
                    tags: []
                  - id: d4e5f6a7-b8c9-0123-defa-234567890123
                    name: Available From
                    description: Earliest start date
                    data_type: date
                    job_id: null
                    list_id: null
                    tags: []
                  - id: e5f6a7b8-c9d0-1234-efab-345678901234
                    name: Stage Rating
                    description: Candidate rating for this specific job
                    data_type: single-select
                    job_id: 11223344-5566-7788-99aa-bbccddeeff00
                    list_id: null
                    tags:
                      - id: b1c2d3e4-5678-9012-abcd-ef0123456789
                        name: A
                        color: '#86efac'
                        description: null
                      - id: b2c3d4e5-6789-0123-bcde-f01234567890
                        name: B
                        color: '#fde68a'
                        description: null
                      - id: b3c4d5e6-7890-1234-cdef-012345678901
                        name: C
                        color: '#fca5a5'
                        description: null
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Always false for error responses.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g. "VALIDATION_ERROR",
                          "NOT_FOUND").
                      message:
                        type: string
                        description: Human-readable error description.
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Always false for error responses.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g. "VALIDATION_ERROR",
                          "NOT_FOUND").
                      message:
                        type: string
                        description: Human-readable error description.
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Always false for error responses.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g. "VALIDATION_ERROR",
                          "NOT_FOUND").
                      message:
                        type: string
                        description: Human-readable error description.
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
components:
  schemas:
    CustomFieldDefinitionsResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldDefinition'
      required:
        - success
        - data
    CustomFieldDefinition:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Attribute definition UUID. Use as attribute_id in search filters
            (select_attribute_filters, numeric_attribute_filters, etc.) and in
            custom field updates.
        name:
          type: string
          description: >-
            Attribute display name (e.g. "Tags", "Seniority Level", "Years of
            Experience").
        description:
          type:
            - string
            - 'null'
          description: Attribute description explaining its intended use.
        data_type:
          type: string
          enum:
            - string
            - integer
            - decimal
            - multi-select
            - single-select
            - boolean
            - date
            - multi-team-member
            - url
          description: >-
            Attribute data type. Determines which filter type to use: string/url
            → text match, integer/decimal → numeric_attribute_filters, date →
            date_attribute_filters, single-select/multi-select →
            select_attribute_filters, multi-team-member →
            team_member_attribute_filters, boolean → select_attribute_filters.
        job_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Job UUID this attribute is scoped to. Null for global (person-level)
            attributes. Job-specific attributes apply only when the person is a
            candidate on that job.
        list_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            List UUID this attribute is scoped to. Null for global
            (person-level) attributes.
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: >-
                  Tag option UUID. Use this ID in select_attribute_filters →
                  values when filtering by this tag.
              name:
                type: string
                description: Tag display name (e.g. "Senior", "Banking", "High Priority").
              color:
                type:
                  - string
                  - 'null'
                description: Hex color code for UI display (e.g. "#86efac").
              description:
                type:
                  - string
                  - 'null'
                description: Optional tag description.
            required:
              - id
              - name
              - color
              - description
          description: >-
            Available tag options for select-type attributes. Empty array for
            non-select types.
      required:
        - id
        - name
        - description
        - data_type
        - job_id
        - list_id
        - tags
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Authenticate with a Bearer token: API key, OAuth token, or session
        token.

````