Brex Cards API

openapi: 3.2.0
info:
  title: Team Cards API
  description: The team API lets you manage users, departments, locations, and cards.
  contact:
    name: Admin
    url: https://brex.com
    email: developer-support@brex.com
  version: '1.0'
  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: Cards
  description: Endpoints for card management.
paths:
  /v2/cards:
    get:
      tags:
      - Cards
      summary: List cards
      description: 'Lists all cards by a `user_id`.

        Only cards with `limit_type = CARD` have `spend_controls`'
      operationId: listCardsByUserId
      parameters:
      - name: user_id
        in: query
        schema:
          type:
          - string
          - 'null'
      - name: cursor
        in: query
        schema:
          type:
          - string
          - 'null'
      - name: limit
        in: query
        schema:
          type:
          - integer
          - 'null'
          format: int32
      responses:
        '200':
          description: listCardsByUserId 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Card_'
      security:
      - OAuth2:
        - cards.readonly
        - cards
    post:
      tags:
      - Cards
      summary: Create card
      description: 'Creates a new card.

        The `spend_controls` field is required when `limit_type` = `CARD`.

        The `mailing_address` field is required for physical cards and is the shipping address used to send the card; it is not the same as the billing and mailing address used for online purchases.

        The first 2 lines of this address must be under 60 characters long. Each user can only have up to 10 active physical cards.

        For Empower accounts, this endpoint requires budget management. If your account does not have access to budget management features, a 403 response status will be returned.

        If this is the case and you want to gain access to this endpoint, please contact Brex support.'
      operationId: createCard
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardRequest'
        required: true
      responses:
        '200':
          description: createCard 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
      security:
      - OAuth2:
        - cards
  /v2/cards/{id}:
    get:
      tags:
      - Cards
      summary: Get card
      description: Retrieves a card by ID. Only cards with `limit_type = CARD` have `spend_controls`
      operationId: getCardById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: getCardById 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
      security:
      - OAuth2:
        - cards
        - cards.readonly
    put:
      tags:
      - Cards
      summary: Update card
      description: Update an existing vendor card
      operationId: updateCard
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCardRequest'
        required: true
      responses:
        '200':
          description: updateCard 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
      security:
      - OAuth2:
        - cards
  /v2/cards/{id}/lock:
    post:
      tags:
      - Cards
      summary: Lock card
      description: Locks an existing, unlocked card. And the card owner will receive a notification about it.
      operationId: lockCard
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockCardRequest'
        required: true
      responses:
        '200':
          description: lockCard 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
      security:
      - OAuth2:
        - cards
  /v2/cards/{id}/pan:
    get:
      tags:
      - Cards
      summary: Get card number
      description: Retrieves card number, CVV, and expiration date of a card by ID.
      operationId: getCardNumber
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: getCardNumber 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardNumberResponse'
      security:
      - OAuth2:
        - cards.pan
      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.)'
  /v2/cards/{id}/secure_email:
    post:
      tags:
      - Cards
      summary: Create secure email to send card number
      description: 'Creates a secure email to send card number, CVV, and expiration date of a card by ID to the specified email.


        This endpoint is currently gated. If you would like to request access, please reach out to

        developer-support@brex.com'
      operationId: emailCardNumber
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecureEmailForCardDetailsRequest'
        required: true
      responses:
        '200':
          description: emailCardNumber 200 response
      security:
      - OAuth2:
        - cards.pan
  /v2/cards/{id}/terminate:
    post:
      tags:
      - Cards
      summary: Terminate card
      description: Terminates an existing card. The card owner will receive a notification about it.
      operationId: terminateCard
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminateCardRequest'
        required: true
      responses:
        '200':
          description: terminateCard 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
      security:
      - OAuth2:
        - cards
  /v2/cards/{id}/unlock:
    post:
      tags:
      - Cards
      summary: Unlock card
      description: Unlocks an existing card.
      operationId: unlockCard
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type:
          - string
          - 'null'
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: unlockCard 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
      security:
      - OAuth2:
        - cards
components:
  schemas:
    LockedMerchantDetails:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: The name of the merchant.
          example: Github
      description: '

        Merchant details used for restricting or blocking transactions.

        '
    LimitType:
      type: string
      description: "\n`limit_type = CARD` for vendor cards. Vendor cards must have a `card_type` of `VIRTUAL` \nand do not rely on the user specific limit. \n\nFor corporate cards, `limit_type = USER`.\n\nLearn more about different card types [here](https://support.brex.com/what-are-the-different-types-of-cards-i-can-get/).\n"
      enum:
      - CARD
      - USER
    ThreeDomainSecureEnabledPreference:
      type: string
      description: "\nWhether to enable 3-D secure protocol on this card. \n"
      enum:
      - THREE_DOMAIN_SECURE_ENABLED
      - THREE_DOMAIN_SECURE_DISABLED
    SecureEmailForCardDetailsRequest:
      required:
      - recipient_email
      - sender_name
      type: object
      properties:
        recipient_email:
          type: string
          description: Email address to send card details to
        sender_name:
          type: string
          description: Sender name. Shows up in the subject of the email
        message:
          type:
          - string
          - 'null'
          description: Message to send with the card details
        expiry_days:
          maximum: 30
          type:
          - integer
          - 'null'
          description: Link expiry in number of days. Defaults to 30
          format: int32
    CardType:
      type: string
      enum:
      - VIRTUAL
      - PHYSICAL
    OwnerType:
      type: string
      enum:
      - USER
    CardAttributePreferences:
      type: object
      properties:
        three_domain_secure_enabled_preference:
          allOf:
          - $ref: '#/components/schemas/ThreeDomainSecureEnabledPreference'
    SpendControlUpdateRequest:
      type: object
      properties:
        spend_limit:
          allOf:
          - $ref: '#/components/schemas/Money'
        spend_duration:
          allOf:
          - $ref: '#/components/schemas/SpendDuration'
        reason:
          type:
          - string
          - 'null'
        lock_after_date:
          type:
          - string
          - 'null'
          format: date
        allowed_merchant_details:
          maxItems: 50
          type:
          - array
          - 'null'
          description: "\nList of merchants where card transactions are allowed. Cannot be used together with blocked_merchant_details. Maximum 50 \nmerchant details.\n"
          example: '[{"name": "Github"}, {"name": "AWS"}]'
          items:
            $ref: '#/components/schemas/LockedMerchantDetails'
        blocked_merchant_details:
          maxItems: 50
          type:
          - array
          - 'null'
          description: "\nList of merchants where card transactions are blocked. Cannot be used together with allowed_merchant_details. Maximum 50 \nmerchant details.\n"
          example: '[{"name": "Apple"}, {"name": "Amazon"}]'
          items:
            $ref: '#/components/schemas/LockedMerchantDetails'
    SpendControlRequest:
      required:
      - spend_duration
      - spend_limit
      type: object
      properties:
        spend_limit:
          $ref: '#/components/schemas/Money'
        spend_duration:
          $ref: '#/components/schemas/SpendDuration'
        reason:
          type:
          - string
          - 'null'
        lock_after_date:
          type:
          - string
          - 'null'
          format: date
        parent_budget_id:
          type:
          - string
          - 'null'
          description: '

            If using the Empower platform, a new `budget` will be created for this card. You can specify a `parent_budget` that your new

            `budget` will be nested under. If `parent_budget_id` is null, we will nest the new budget under the top-level account `budget`.

            '
        policy_id:
          type:
          - string
          - 'null'
        allowed_merchant_details:
          maxItems: 50
          type:
          - array
          - 'null'
          description: "\nList of merchants where card transactions are allowed. Cannot be used together with blocked_merchant_details. Maximum 50 \nmerchant details.\n"
          example: '[{"name": "Github"}, {"name": "AWS"}]'
          items:
            $ref: '#/components/schemas/LockedMerchantDetails'
        blocked_merchant_details:
          maxItems: 50
          type:
          - array
          - 'null'
          description: "\nList of merchants where card transactions are blocked. Cannot be used together with allowed_merchant_details. Maximum 50 \nmerchant details.\n"
          example: '[{"name": "Apple"}, {"name": "Amazon"}]'
          items:
            $ref: '#/components/schemas/LockedMerchantDetails'
      description: '

        When `limit_type = CARD`, `spend_controls` must be set. When `limit type = USER`, `spend_controls` must be `null`.

        '
    UserOwner:
      type: object
      allOf:
      - $ref: '#/components/schemas/CardOwner'
      - required:
        - type
        - user_id
        properties:
          type:
            $ref: '#/components/schemas/OwnerType'
          user_id:
            type: string
    CardStatus:
      type: string
      enum:
      - ACTIVE
      - SHIPPED
      - LOCKED
      - TERMINATED
    Address:
      type: object
      properties:
        line1:
          type:
          - string
          - 'null'
          description: Address line 1, no PO Box.
        line2:
          type:
          - string
          - 'null'
          description: Address line 2 (e.g., apartment, suite, unit, or building).
        city:
          type:
          - string
          - 'null'
          description: City, district, suburb, town, or village.
        state:
          type:
          - string
          - 'null'
          description: For US-addressed the 2-letter State abbreviation. For international-addresses the county, providence, or region.
        country:
          type:
          - string
          - 'null'
          description: Two-letter country code (ISO 3166-1 alpha-2).
        postal_code:
          type:
          - string
          - 'null'
          description: ZIP or postal code.
        phone_number:
          type:
          - string
          - 'null'
          description: Phone number.
      description: Company business address (must be in the US; no PO box or virtual/forwarding addresses allowed).
    Page_Card_:
      required:
      - items
      type: object
      properties:
        next_cursor:
          type:
          - string
          - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Card'
    Money:
      required:
      - amount
      type: object
      properties:
        amount:
          type: integer
          description: The amount of money, in the smallest denomination of the currency indicated by currency. For example, when currency is USD, amount is in cents.
          format: int64
          example: 700
        currency:
          type:
          - string
          - 'null'
          description: The type of currency, in ISO 4217 format.
          example: USD
          default: USD
      description: '

        Money fields can be signed or unsigned. Fields are signed (an unsigned value will be interpreted as positive). The amount of money will be represented in the smallest denomination

        of the currency indicated. For example, USD 7.00 will be represented in cents with an amount of 700.

        '
    CreateCardRequest:
      required:
      - card_name
      - card_type
      - limit_type
      - owner
      type: object
      properties:
        owner:
          $ref: '#/components/schemas/CardOwner'
        card_name:
          minLength: 1
          type: string
        card_type:
          $ref: '#/components/schemas/CardType'
        limit_type:
          $ref: '#/components/schemas/LimitType'
        spend_controls:
          allOf:
          - $ref: '#/components/schemas/SpendControlRequest'
        mailing_address:
          allOf:
          - $ref: '#/components/schemas/Address'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: "\nSet of key value pairs associated with this object. Please do not store any personally identifiable or sensitive information here.\nLimitations: maximum of 50 keys, keys cannot exceed 40 characters, values cannot exceed 500 characters. \n"
        card_attribute_preferences:
          allOf:
          - $ref: '#/components/schemas/CardAttributePreferences'
      description: '

        The `spend_controls` field is required when `limit_type` = `CARD`.

        The `shipping_address` field is required for physical cards, and the first 2 lines of the address must be under 60 characters long.

        '
    Card:
      required:
      - billing_address
      - created_at
      - expiration_date
      - id
      - last_four
      - limit_type
      - owner
      type: object
      properties:
        id:
          type: string
        owner:
          $ref: '#/components/schemas/CardOwner'
        status:
          allOf:
          - $ref: '#/components/schemas/CardStatus'
        last_four:
          type: string
        card_name:
          type:
          - string
          - 'null'
        card_type:
          allOf:
          - $ref: '#/components/schemas/CardType'
        limit_type:
          $ref: '#/components/schemas/LimitType'
        spend_controls:
          allOf:
          - $ref: '#/components/schemas/SpendControl'
        billing_address:
          $ref: '#/components/schemas/Address'
        mailing_address:
          allOf:
          - $ref: '#/components/schemas/Address'
        expiration_date:
          $ref: '#/components/schemas/CardExpiration'
        has_been_transferred:
          type: boolean
          description: '

            Indicates whether a card has been transferred. Transferred cards have a spending restriction: we only allow transactions \

            at online vendors where this card was previously used before the transfer.

            '
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: "\nSet of key value pairs associated with this object. Please do not store any personally identifiable or sensitive information here.\nLimitations: maximum of 50 keys, keys cannot exceed 40 characters, values cannot exceed 500 characters. \n"
        budget_id:
          type:
          - string
          - 'null'
        partner:
          type:
          - string
          - 'null'
          description: '

            The partner that manages this card, if any.

            '
        created_at:
          type: string
          description: The timestamp when the card was created
          example: '2019-08-24T14:15:22Z'
      description: '

        Only cards with limit_type = CARD have spend_controls

        '
    CardNumberResponse:
      required:
      - cvv
      - expiration_date
      - holder_name
      - id
      - number
      type: object
      properties:
        id:
          type: string
        number:
          type: string
        cvv:
          type: string
        expiration_date:
          $ref: '#/components/schemas/CardExpiration'
        holder_name:
          type: string
      description: '

        Card number, CVV, and expiration date of a card.

        '
    CardExpiration:
      required:
      - month
      - year
      type: object
      properties:
        month:
          type: integer
          format: int32
        year:
          type: integer
          format: int32
      description: '

        Card expiration year and month. Cards expire on the last day of the expiration month.


        The expiration date is in UTC for cards starting with 555671, 428803 and 485932.

        And the expiration date is in PST for cards starting with 511572.

        '
    CardOwner:
      type: object
      discriminator:
        propertyName: type
        mapping:
          USER: '#/components/schemas/UserOwner'
      oneOf:
      - $ref: '#/components/schemas/UserOwner'
    LockCardRequest:
      required:
      - reason
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: Description for locking a card
        reason:
          $ref: '#/components/schemas/ChangeCardReason'
      description: Parameters for locking a card.
    TerminateCardRequest:
      required:
      - reason
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: Description for terminating a card
        reason:
          $ref: '#/components/schemas/ChangeCardReason'
      description: Parameters for terminating a card.
    ChangeCardReason:
      type: string
      description: '

        Reason for card termination.

        '
      enum:
      - CARD_DAMAGED
      - CARD_LOST
      - CARD_NOT_RECEIVED
      - DO_NOT_NEED_PHYSICAL_CARD
      - DO_NOT_NEED_VIRTUAL_CARD
      - FRAUD
      - OTHER
    SpendControl:
      type: object
      properties:
        spend_limit:
          allOf:
          - $ref: '#/components/schemas/Money'
        spend_available:
          allOf:
          - $ref: '#/components/schemas/Money'
        spend_duration:
          allOf:
          - $ref: '#/components/schemas/SpendDuration'
        reason:
          type:
          - string
          - 'null'
        lock_after_date:
          type:
          - string
          - 'null'
          description: The `lock_after_date` is in UTC.
          format: date
        allowed_merchant_details:
          type:
          - array
          - 'null'
          description: '

            List of merchant details where card transactions are allowed. Empty if no allowed merchant details are configured.

            '
          example: '[{"name": "Github"}, {"name": "AWS"}]'
          items:
            $ref: '#/components/schemas/LockedMerchantDetails'
        blocked_merchant_details:
          type:
          - array
          - 'null'
          description: '

            List of merchant details where card transactions are blocked. Empty if no blocked merchant details are configured.

            '
          example: '[{"name": "Apple"}, {"name": "Amazon"}]'
          items:
            $ref: '#/components/schemas/LockedMerchantDetails'
    UpdateCardRequest:
      type: object
      properties:
        spend_controls:
          allOf:
          - $ref: '#/components/schemas/SpendControlUpdateRequest'
        metadata:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: "\nSet of key value pairs associated with this object. Please do not store any personally identifiable or sensitive information here.\nLimitations: maximum of 50 keys, keys cannot exceed 40 characters, values cannot exceed 500 characters. \n"
    SpendDuration:
      type: string
      description: "\n    Spend limit refresh frequency\n    - MONTHLY: The spend limit refreshes every month\n    - QUARTERLY: The spend limit refreshes every quarter\n    - YEARLY: The spend limit refreshes every year\n    - ONE_TIME: The limit does not refresh\n"
      enum:
      - MONTHLY
      - QUARTERLY
      - YEARLY
      - ONE_TIME
  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
            users.readonly: View user data
            users: View and manage user data
            locations.readonly: View location data
            locations: View and manage location data
            departments.readonly: View department data
            departments: View and manage department data
            titles: View and manage title data
            titles.readonly: View title data
            cost_centers: View and manage cost center data
            cost_centers.readonly: View cost center data
            cards: View and manage card data
            cards.readonly: View card data
            cards.pan: View and Send card number data
            legal_entities: View and manage legal entities
            legal_entities.readonly: View legal entities
x-explorer-enabled: false
x-provenance:
  method: harvested
  publisher: Brex
  source: https://developer.brex.com/_bundle/openapi/team_api.yaml?download
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)