Bindbee Custom Fields API

openapi: 3.2.0
info:
  title: Bindbee Custom Fields API
  version: 0.1.0
tags:
- name: Custom Fields
paths:
  /api/v1/custom-fields:
    post:
      tags:
      - Custom Fields
      summary: Create Custom Field
      description: Create a new custom field.
      operationId: create_custom_field_api_v1_custom_fields_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldCreateExternal'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Custom Field Api V1 Custom Fields Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Custom Fields
      summary: List Custom Fields
      description: List custom fields for the caller's organization.
      operationId: list_custom_fields_api_v1_custom_fields_get
      security:
      - HTTPBearer: []
      parameters:
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Category'
          - type: 'null'
          description: Filter by category, e.g. HRIS.
          examples:
          - HRIS
          title: Category
        description: Filter by category, e.g. HRIS.
      - name: model
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^[a-z][a-z0-9_-]*$
          - type: 'null'
          description: Filter by model slug, e.g. employee.
          examples:
          - employee
          title: Model
        description: Filter by model slug, e.g. employee.
      - name: source
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CustomFieldSource'
          - type: 'null'
          description: 'Filter by origin: ''API'' for fields created via the public API, ''DASHBOARD'' for fields created from the Bindbee dashboard.'
          examples:
          - API
          title: Source
        description: 'Filter by origin: ''API'' for fields created via the public API, ''DASHBOARD'' for fields created from the Bindbee dashboard.'
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Number of results to return per page. Maximum size is 200.
          default: 50
          title: Page Size
        description: Number of results to return per page. Maximum size is 200.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The pagination cursor value.
          title: Cursor
        description: The pagination cursor value.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_CustomFieldExternal_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/custom-fields/mapping:
    post:
      tags:
      - Custom Fields
      summary: Create Custom Field Mapping
      description: Create a custom field mapping. Provide exactly one of `integration_slug` (organization scope) or `connector_token` (connector scope).
      operationId: create_custom_field_mapping_api_v1_custom_fields_mapping_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldMappingCreateExternal'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Custom Field Mapping Api V1 Custom Fields Mapping Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Custom Fields
      summary: List Custom Field Mappings
      description: List mappings for an integration slug or connector token. Provide exactly one of `integration_slug` or `connector_token`.
      operationId: list_custom_field_mappings_api_v1_custom_fields_mapping_get
      security:
      - HTTPBearer: []
      parameters:
      - name: integration_slug
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Integration slug — return organization-scoped mappings for this integration.
          examples:
          - workday
          title: Integration Slug
        description: Integration slug — return organization-scoped mappings for this integration.
      - name: connector_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Connector token — return connector-scoped mappings for this connector.
          examples:
          - i5kqe8bSedEdPLX9pHhFojKdo7Uzvue0f7I4NVhaDfV0GTxF0uAgwa_COb3zZU3T
          title: Connector Token
        description: Connector token — return connector-scoped mappings for this connector.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFieldMappingExternal'
                title: Response List Custom Field Mappings Api V1 Custom Fields Mapping Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/custom-fields/mapping/{custom_field_mapping_id}:
    patch:
      tags:
      - Custom Fields
      summary: Update Custom Field Mapping
      description: Update a custom field mapping (json_path only).
      operationId: update_custom_field_mapping_api_v1_custom_fields_mapping__custom_field_mapping_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: custom_field_mapping_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Custom Field Mapping Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldMappingUpdateExternal'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldMappingExternal'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Custom Fields
      summary: Delete Custom Field Mapping
      description: Delete a custom field mapping.
      operationId: delete_custom_field_mapping_api_v1_custom_fields_mapping__custom_field_mapping_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: custom_field_mapping_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Custom Field Mapping Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/custom-fields/raw-data:
    get:
      tags:
      - Custom Fields
      summary: Get Raw Data
      description: Inspect the raw upstream payload for a connector + (category, model). Use this to discover the field structure before writing a JMESPath. Returns the latest synced row's raw_data; falls back to the integration's canned sample if the connector has never synced. Provide exactly one of `connector_token` or `integration_slug`.
      operationId: get_raw_data_api_v1_custom_fields_raw_data_get
      security:
      - HTTPBearer: []
      parameters:
      - name: category
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Category'
          description: Category of the model.
          examples:
          - HRIS
        description: Category of the model.
      - name: model
        in: query
        required: true
        schema:
          type: string
          maxLength: 64
          pattern: ^[a-z][a-z0-9_-]*$
          description: Model slug whose raw payload should be returned.
          examples:
          - employee
          title: Model
        description: Model slug whose raw payload should be returned.
      - name: connector_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Connector token used to return the connector's latest synced row. Exactly one of `connector_token` or `integration_slug` is required.
          examples:
          - i5kqe8bSedEdPLX9pHhFojKdo7Uzvue0f7I4NVhaDfV0GTxF0uAgwa_COb3zZU3T
          title: Connector Token
        description: Connector token used to return the connector's latest synced row. Exactly one of `connector_token` or `integration_slug` is required.
      - name: integration_slug
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Integration slug used to return the canned integration sample. Exactly one of `connector_token` or `integration_slug` is required.
          examples:
          - workday
          title: Integration Slug
        description: Integration slug used to return the canned integration sample. Exactly one of `connector_token` or `integration_slug` is required.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  additionalProperties: true
                - type: 'null'
                title: Response Get Raw Data Api V1 Custom Fields Raw Data Get
        '422':
          description: Request validation failed. Exactly one of `connector_token` or `integration_slug` must be provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-query-parameter-constraints:
        exactlyOne:
        - connector_token
        - integration_slug
  /api/v1/custom-fields/preview:
    post:
      tags:
      - Custom Fields
      summary: Preview Custom Field
      description: Dry-run a JMESPath against a connector's data, without creating a mapping. Useful for validating an expression before persisting it as a mapping.
      operationId: preview_custom_field_api_v1_custom_fields_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldPreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - HTTPBearer: []
  /api/v1/custom-fields/configuration:
    get:
      tags:
      - Custom Fields
      summary: Get Custom Fields Configuration
      description: 'For a connector + (category, model), return the full custom-field configuration: every custom field with its effective mapping (connector overrides organization) and the source. Unmapped fields are included with null json_path so callers can see what is left to configure.'
      operationId: get_custom_fields_configuration_api_v1_custom_fields_configuration_get
      security:
      - HTTPBearer: []
      parameters:
      - name: connector_token
        in: query
        required: true
        schema:
          type: string
          description: Connector token to compute the configuration for.
          examples:
          - i5kqe8bSedEdPLX9pHhFojKdo7Uzvue0f7I4NVhaDfV0GTxF0uAgwa_COb3zZU3T
          title: Connector Token
        description: Connector token to compute the configuration for.
      - name: category
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Category'
          description: Category to filter custom fields by.
          examples:
          - HRIS
        description: Category to filter custom fields by.
      - name: model
        in: query
        required: true
        schema:
          type: string
          maxLength: 64
          pattern: ^[a-z][a-z0-9_-]*$
          description: Model slug to filter custom fields by.
          examples:
          - employee
          title: Model
        description: Model slug to filter custom fields by.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EffectiveCustomFieldResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/custom-fields/{custom_field_id}:
    get:
      tags:
      - Custom Fields
      summary: Get Custom Field
      description: Get a custom field with all its mappings.
      operationId: get_custom_field_api_v1_custom_fields__custom_field_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: custom_field_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Custom Field Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDetailExternal'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Missing or invalid bearer authentication credentials.
          headers:
            WWW-Authenticate:
              description: Bearer authentication challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The credentials are valid but do not permit access to this resource, e.g. a connector token used on a different API category or a model whose writes are disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed in the current window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp (seconds since epoch) at which the current rate-limit window resets.
              schema:
                type: integer
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Custom Fields
      summary: Update Custom Field
      description: Update a custom field. `category` and `model` can only be changed while the field has no mappings.
      operationId: update_custom_field_api_v1_custom_fields__custom_field_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: custom_field_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Custom Field Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldUpdateExternal'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDetailExternal'
        '422':
          description: Validation Error
          content:
            application/json:
              sc

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bindbee/refs/heads/main/openapi/bindbee-custom-fields-api-openapi.yml