openapi: 3.0.1
info:
  title: Fields API
  description: >-
    The Fields API allows you to manage fields and field values information. The
    Fields API is currently in Beta and is available for use. Customers do not
    need to explicitly opt-in to Beta. However, the API is subject to changes as
    per the expectations set regarding Beta APIs in the API Launch Stages
    documentation: https://developer.brex.com/docs/api-launch-stages/.


    **Supported field types:** The Fields API currently supports only
    single-select dropdown fields. Each field exposes a list of field values
    from which exactly one value can be selected. Multi-select fields and other
    input types (such as free-form text, date, numeric, or boolean fields) are
    not currently supported.


    **Using the `ERP` group:** Fields in the `ERP` group are managed with an
    external ERP/accounting system. Setting up an Accounting Integration is a
    prerequisite for creating `ERP` fields, and each `ERP` field must be
    associated with that integration through its `integration_id`. See the
    `group` and `integration_id` properties below for details.
  contact:
    name: Admin
    url: https://brex.com
    email: developer-support@brex.com
  version: 1.0.0-beta
  x-logo:
    altText: Brex Logo
    url: https://www.brex.com/logo.png
servers:
  - url: https://api.brex.com
    description: Production
  - url: https://api-staging.brex.com
    description: >-
      Staging (Note: This is not a sandbox. It will not work with customer
      tokens.)
security:
  - OAuth2: []
tags:
  - name: Fields
    description: View and manage fields data.
paths:
  /v1/fields:
    get:
      tags:
        - Fields
      summary: List custom fields
      description: List custom fields under the same account
      operationId: listFields
      parameters:
        - name: field_id[]
          in: query
          description: The Brex identifiers of the field to filter by
          schema:
            type: array
            nullable: true
            items:
              type: string
          example: extended_field_foobar
        - name: cursor
          in: query
          description: >-
            The cursor to use for pagination. This is the `next_cursor` value
            returned from the previous response.
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: >-
            Controls the maximum number of field values returned in the
            response. It can't be greater than 1000.
          schema:
            type: integer
            format: int32
            nullable: true
      responses:
        '200':
          description: List custom fields response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Field_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - fields.read
            - fields.write
    post:
      tags:
        - Fields
      summary: Create a custom field
      description: Create a custom field
      operationId: createField
      parameters:
        - name: Idempotency-Key
          in: header
          description: Idempotency key for this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldCreateBody'
        required: true
      responses:
        '200':
          description: Create custom field response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - fields.write
  /v1/fields/{field_id}/values:
    get:
      tags:
        - Field Values
      summary: List custom field values
      description: List values under the same custom field
      operationId: listFieldValues
      parameters:
        - name: field_id
          in: path
          description: The Field Brex identifier
          required: true
          schema:
            type: string
          example: extended_field_foobar
        - name: brex_id[]
          in: query
          description: Field value Brex identifier(s) to filter by
          schema:
            type: array
            nullable: true
            items:
              type: string
          example: efo_foobar
        - name: value_id[]
          in: query
          description: Field value identifier(s) to filter by
          schema:
            type: array
            nullable: true
            items:
              type: string
          example: FooBar
        - name: remote_id[]
          in: query
          description: Field value remote identifier(s) to filter by
          schema:
            type: array
            nullable: true
            items:
              type: string
          example: foo_bar
        - name: cursor
          in: query
          description: >-
            The cursor to use for pagination. This is the `next_cursor` value
            returned from the previous response.
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: >-
            Controls the maximum number of field values returned in the
            response. It can't be greater than 1000.
          schema:
            type: integer
            format: int32
            nullable: true
        - name: value
          in: query
          description: Field value's value to filter by
          schema:
            type: string
            nullable: true
          example: Foobar
      responses:
        '200':
          description: List custom field values response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_FieldValue_'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - field_values.read
            - field_values.write
    put:
      tags:
        - Field Values
      summary: Update custom field values
      description: >-
        Update custom field values (up to 1000 values at once) for a specific
        field
      operationId: updateFieldValues
      parameters:
        - name: field_id
          in: path
          description: The Field Brex identifier
          required: true
          schema:
            type: string
          example: extended_field_foobar
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFieldValueListBody'
        required: true
      responses:
        '200':
          description: Update custom field value list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateFieldValueListResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - field_values.write
    post:
      tags:
        - Field Values
      summary: Create custom field values
      description: >-
        Create custom field values (up to 1000 values at once) for a specific
        field
      operationId: createFieldValues
      parameters:
        - name: field_id
          in: path
          description: The Field Brex identifier
          required: true
          schema:
            type: string
          example: extended_field_foobar
        - name: Idempotency-Key
          in: header
          description: Idempotency key for this request.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFieldValueListBody'
        required: true
      responses:
        '200':
          description: Create custom field values response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFieldValueListResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - field_values.write
    delete:
      tags:
        - Field Values
      summary: Delete custom field values
      description: >-
        Delete custom field values (up to 1000 values at once) for a specific
        field
      operationId: deleteFieldValues
      parameters:
        - name: field_id
          in: path
          description: The Field Brex identifier
          required: true
          schema:
            type: string
          example: extended_field_foobar
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteFieldValueListBody'
        required: true
      responses:
        '200':
          description: Delete custom field value list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedFieldValueListResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - fields.write
  /v1/fields/{field_id}/values/{brex_id}:
    get:
      tags:
        - Field Values
      summary: Get a field value
      description: Get a field value by field ID and field value ID
      operationId: getFieldValueById
      parameters:
        - name: field_id
          in: path
          description: The Field Brex identifier
          required: true
          schema:
            type: string
          example: extended_field_foobar
        - name: brex_id
          in: path
          description: The field value ID (`brex_id`) to retrieve.
          required: true
          schema:
            type: string
          example: efo_foobar
      responses:
        '200':
          description: Get a field value response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldValue'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - field_values.read
            - field_values.write
  /v1/fields/{id}:
    get:
      tags:
        - Fields
      summary: Get custom field
      description: Get a custom field by Brex ID
      operationId: getFieldById
      parameters:
        - name: id
          in: path
          description: The Brex identifier of the field to retrieve
          required: true
          schema:
            type: string
          example: extended_field_foobar
      responses:
        '200':
          description: Get custom field response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - fields.read
            - fields.write
    put:
      tags:
        - Fields
      summary: Update a custom field
      description: Update a field by ID
      operationId: updateField
      parameters:
        - name: id
          in: path
          description: The Brex identifier of the field to update
          required: true
          schema:
            type: string
          example: extended_field_foobar
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldUpdateBody'
        required: true
      responses:
        '200':
          description: Update custom field response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - fields.write
    delete:
      tags:
        - Fields
      summary: Delete a custom field
      description: Delete a custom field by Brex ID
      operationId: deleteField
      parameters:
        - name: id
          in: path
          description: The Brex identifier of the field to delete
          required: true
          schema:
            type: string
          example: extended_field_foobar
      responses:
        '200':
          description: Delete custom field response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
        - OAuth2:
            - fields.write
components:
  schemas:
    CreateFieldValueBody:
      title: Field value creation
      required:
        - value
      type: object
      properties:
        value:
          type: string
          description: The display name of the field value
        value_id:
          type: string
          description: >-
            The value ID or code of the field value; Usually it is a unique
            identifier for the custom field value in the remote system
          nullable: true
          example: FooBar
        remote_id:
          type: string
          description: >-
            Remote/external ID of custom field value from external system (e.g.
            ERP or HRIS system)
          nullable: true
          example: foo_bar
        is_disabled:
          type: boolean
          description: >-
            Indicates whether the field value is disabled. A disabled value is
            not selectable: it no longer appears as a selectable option in the
            dropdown and cannot be chosen on new transactions. Records that
            already use the value are unaffected.
          nullable: true
      description: Represents the data needed to create a field value
    CreateFieldValueListBody:
      title: Field value list creation
      required:
        - items
      type: object
      properties:
        items:
          minItems: 1
          type: array
          description: The list of field values to be created
          items:
            $ref: '#/components/schemas/CreateFieldValueBody'
      description: >-
        Represents the data needed to create multiple field values. It can't
        contain more than 1000 values at once.
    CreateFieldValueListResponse:
      title: Field value list
      required:
        - items
      type: object
      properties:
        items:
          type: array
          description: The list of created field values
          items:
            $ref: '#/components/schemas/FieldValue'
      description: Represents a list of field values definition
    DeleteFieldValue.ByBrexId:
      title: by `brex_id`
      required:
        - brex_id
      type: object
      properties:
        brex_id:
          type: string
          description: The internal Brex ID of the field value
          example: efo_foobar
      description: Represents the data needed to delete a field value using its `brex_id`.
    DeleteFieldValue.ByRemoteId:
      title: by `remote_id`
      required:
        - remote_id
      type: object
      properties:
        remote_id:
          type: string
          description: >-
            Remote/external ID of custom field value from external system (e.g.
            ERP or HRIS system)
          example: foo_bar
      description: >-
        Represents the data needed to delete a field value using its
        `remote_id`.
    DeleteFieldValue.ByValueId:
      title: by `value_id`
      required:
        - value_id
      type: object
      properties:
        value_id:
          type: string
          description: >-
            The value ID or code of the field value; Usually it is a unique
            identifier for the custom field value in the remote system
          example: FooBar
      description: Represents the data needed to delete a field value using its `value_id`.
    DeleteFieldValueBody:
      title: Field value to delete
      type: object
      description: Represents the data needed to delete a field value.
      oneOf:
        - $ref: '#/components/schemas/DeleteFieldValue.ByBrexId'
        - $ref: '#/components/schemas/DeleteFieldValue.ByValueId'
        - $ref: '#/components/schemas/DeleteFieldValue.ByRemoteId'
    DeleteFieldValueListBody:
      title: Field value list deletion
      required:
        - items
      type: object
      properties:
        items:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/DeleteFieldValueBody'
      description: >-
        Represents the data needed to delete field values. It can't contain more
        than 1000 values at once.
    DeletedFieldValueListResponse:
      title: Field value deleted response
      type: object
      description: Represents the confirmation of number of deleted field values
    Field:
      title: Field
      required:
        - brex_id
        - is_disabled
        - name
        - updated_at
      type: object
      properties:
        brex_id:
          type: string
          description: The internal Brex ID of the field
          example: extended_field_foobar
        name:
          type: string
          description: The name of the field
          nullable: true
        remote_id:
          type: string
          description: >-
            Remote/external ID of custom field from external system (e.g. ERP or
            HRIS system)
          nullable: true
          example: foo_bar
        updated_at:
          type: string
          description: The last updated timestamp of the field
          format: date-time
        is_disabled:
          type: boolean
          description: >-
            Indicates whether the field is disabled. A disabled field is not
            selectable: it is no longer offered as an option in the Brex
            dropdown and cannot be applied to new transactions. Records that
            already reference the field are unaffected.
        group:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/FieldGroup'
            - description: >-
                The category of the field, indicating its purpose or context.
                For example, it could belong to accounting-related fields or
                user-related fields.
      description: Represents a field definition
    FieldCreateBody:
      title: Field creation
      required:
        - group
        - name
      type: object
      properties:
        name:
          type: string
          description: The name of the field
        group:
          allOf:
            - $ref: '#/components/schemas/FieldGroup'
            - description: >-
                The category of the field, indicating its purpose or context.
                For example, it could belong to accounting-related fields or
                user-related fields.
        remote_id:
          type: string
          description: >-
            Remote/external ID of custom field from external system (e.g. ERP or
            HRIS system)
          nullable: true
          example: foo_bar
        integration_id:
          type: string
          description: >-
            The ID of the Accounting Integration to associate this field with.
            This property is **required** when `group` is `ERP`: it must
            reference an existing Accounting Integration, and requests that omit
            it or send `null` for an `ERP` field are rejected. For all other
            groups (`ACCOUNTING`, `USER`, `TRAVEL`) `integration_id` is not
            applicable and should be left null.
          nullable: true
          example: int_123
        is_disabled:
          type: boolean
          description: >-
            Indicates whether the field is disabled. A disabled field is not
            selectable: it is no longer offered as an option in the Brex
            dropdown and cannot be applied to new transactions. Records that
            already reference the field are unaffected.
          nullable: true
      description: >-
        Represents the data needed to create a field. To create a field in the
        `ERP` group you must first set up an Accounting Integration and supply
        its `integration_id`.
    FieldGroup:
      type: string
      description: >-
        The category of the field, indicating its purpose or context. Supported
        groups are:


        * `ACCOUNTING` — Fields used to categorize transactions for accounting
        purposes (for example, expense categories or cost centers) that are
        managed directly within Brex.


        * `USER` — Fields associated with users, used to capture user-specific
        attributes.


        * `ERP` — Fields that are synced with an external ERP/accounting system
        through an Accounting Integration. Creating an Accounting Integration is
        a prerequisite for creating fields in the `ERP` group, and each `ERP`
        field must reference that integration through `integration_id`.


        * `TRAVEL` — Fields used in the context of travel bookings and expenses.
      enum:
        - ACCOUNTING
        - USER
        - ERP
        - TRAVEL
    FieldUpdateBody:
      title: Field update
      type: object
      properties:
        name:
          type: string
          description: The name of the field
          nullable: true
        is_disabled:
          type: boolean
          description: >-
            Indicates whether the field is disabled. A disabled field is not
            selectable: it is no longer offered as an option in the Brex
            dropdown and cannot be applied to new transactions. Records that
            already reference the field are unaffected.
          nullable: true
      description: Represents the data needed to update a field
    FieldValue:
      title: Field value
      required:
        - brex_id
        - field_id
        - is_disabled
        - updated_at
        - value
      type: object
      properties:
        brex_id:
          type: string
          description: The internal Brex ID of the field value
          example: efo_foobar
        remote_id:
          type: string
          description: >-
            Remote/external ID of custom field value from external system (e.g.
            ERP or HRIS system)
          nullable: true
          example: foo_bar
        value_id:
          type: string
          description: >-
            The value ID or code of the field value; Usually it is a unique
            identifier for the custom field value in the remote system
          nullable: true
          example: foo_bar
        value:
          type: string
          description: The display name of the field value
        field_id:
          type: string
          description: The ID of the parent field this value belongs to
          example: extended_field_foobar
        updated_at:
          type: string
          description: The last updated timestamp of the field value
          format: date-time
        is_disabled:
          type: boolean
          description: >-
            Indicates whether the field value is disabled. A disabled value is
            not selectable: it no longer appears as a selectable option in the
            dropdown and cannot be chosen on new transactions. Records that
            already use the value are unaffected.
      description: Represents a field value definition
    Page_FieldValue_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/FieldValue'
    Page_Field_:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/Field'
    UpdateFieldValue.ByBrexId:
      title: by `brex_id`
      required:
        - brex_id
        - data
      type: object
      properties:
        brex_id:
          type: string
          description: The internal Brex ID of the field value
          example: efo_foobar
        data:
          allOf:
            - $ref: '#/components/schemas/UpdateFieldValueDataBody'
            - description: Field value data to update
      description: Represents the data needed to update a field value using its `brex_id`.
    UpdateFieldValue.ByRemoteId:
      title: by `remote_id`
      required:
        - data
        - remote_id
      type: object
      properties:
        remote_id:
          type: string
          description: >-
            Remote/external ID of custom field value from external system (e.g.
            ERP or HRIS system)
          example: foo_bar
        data:
          allOf:
            - $ref: '#/components/schemas/UpdateFieldValueDataBody'
            - description: Field value data to update
      description: >-
        Represents the data needed to update a field value using its
        `remote_id`.
    UpdateFieldValue.ByValueId:
      title: by `value_id`
      required:
        - data
        - value_id
      type: object
      properties:
        value_id:
          type: string
          description: >-
            The value ID or code of the field value; Usually it is a unique
            identifier for the custom field value in the remote system
          example: FooBar
        data:
          allOf:
            - $ref: '#/components/schemas/UpdateFieldValueDataBody'
            - description: Field value data to update
      description: Represents the data needed to update a field value using its `value_id`.
    UpdateFieldValueBody:
      title: Field value to update
      type: object
      description: Represents the data needed to update a field value.
      oneOf:
        - $ref: '#/components/schemas/UpdateFieldValue.ByBrexId'
        - $ref: '#/components/schemas/UpdateFieldValue.ByValueId'
        - $ref: '#/components/schemas/UpdateFieldValue.ByRemoteId'
    UpdateFieldValueDataBody:
      title: Field value update data
      type: object
      properties:
        value:
          type: string
          description: The display name of the field value
          nullable: true
        is_disabled:
          type: boolean
          description: >-
            Indicates whether the field value is disabled. A disabled value is
            not selectable: it no longer appears as a selectable option in the
            dropdown and cannot be chosen on new transactions. Records that
            already use the value are unaffected.
          nullable: true
      description: Represents the updated data of a field value
    UpdateFieldValueListBody:
      title: Field value list update
      required:
        - items
      type: object
      properties:
        items:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/UpdateFieldValueBody'
      description: >-
        Represents the data needed to update multiple field values. It can't
        contain more than 1000 values at once.
    UpdateFieldValueListResponse:
      title: Field value updated list
      required:
        - items
      type: object
      properties:
        items:
          type: array
          description: The list of updated field values
          items:
            $ref: '#/components/schemas/FieldValue'
      description: Represents a list of updated field values
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 security scheme
      flows:
        authorizationCode:
          authorizationUrl: https://accounts-api.brex.com/oauth2/default/v1/authorize
          tokenUrl: https://accounts-api.brex.com/oauth2/default/v1/token
          scopes:
            openid: openid
            offline_access: offline access
            fields.read: View custom fields
            fields.write: View and manage custom fields
            field_values.read: View custom field values
            field_values.write: View and manage custom field values
x-explorer-enabled: false
