openapi: 3.0.1
info:
  title: Onboarding API
  description: >

    The onboarding API allows you to refer your customers and personal contacts
    to Brex.
  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:
  - Client Credentials: []
tags:
  - name: Referrals
    description: >

      The onboarding API allows you to submit customer referrals to Brex and
      receive a customized Brex application URL. You can

      optionally submit additional information to help prefill their application
      with data you may have about the customer.

      You also can get visibility into the application approval status.
paths:
  /v1/referrals:
    get:
      tags:
        - Referrals
      summary: List referrals
      description: |
        Returns referrals created.
        *Note*: This doesn't include referrals that have expired.
      operationId: listReferrals
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralPage'
        '400':
          description: Invalid cursor
        '401':
          description: Unauthorized
    post:
      tags:
        - Referrals
      summary: Creates a referral
      description: >-
        This creates new referrals. The response will contain an identifier and
        a unique personalized link to an application flow. Many fields are
        optional and when they're provided they'll prefill the application flow
        for Brex.  You should handle and store these references securely as they
        contain sensitive information about the referral.
      operationId: createReferralRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReferralRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Unauthorized
  /v1/referrals/{id}:
    get:
      tags:
        - Referrals
      summary: Gets a referral by ID
      description: Returns a referral object by ID if it exists.
      operationId: getReferral
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Unauthorized
        '404':
          description: Referral not found
  /v1/referrals/{id}/document_upload:
    post:
      tags:
        - Referrals
      summary: Create a new document upload
      description: >

        The `uri` will be a presigned S3 URL allowing you to upload the referral
        doc securely. This URL can only be used for a `PUT` operation and
        expires 30 minutes after its creation. Once your upload is complete, we
        will use this to prefill the application.


        Refer to these
        [docs](https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html)
        on how to upload to this presigned S3 URL. We highly recommend using one
        of AWS SDKs if they're available for your language to upload these
        files.
      operationId: createDocument
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: Unauthorized
        '404':
          description: Referral not found
  /v1/referrals/{id}/process_ein_document:
    post:
      tags:
        - Referrals
      summary: Process a delayed EIN document after upload
      description: >

        Processes a delayed EIN document after it has been uploaded.


        This endpoint should be called after successfully uploading an IRS EIN
        Confirmation document (CP-575, CP-575 fax sheet, or 147C) using the

        standard document upload flow (`/v1/referrals/{id}/document_upload` with
        `type: IRS_EIN_CONFIRMATION`).


        The `document_id` should be the `id` returned from the document upload
        request.
      operationId: processDelayedEINDocument
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessDelayedEINDocumentRequest'
        required: true
      responses:
        '200':
          description: Document processed successfully
        '400':
          description: Document not uploaded or invalid
        '401':
          description: Unauthorized
        '404':
          description: Referral not found
components:
  schemas:
    Account:
      required:
        - created_at
        - id
      type: object
      properties:
        id:
          type: string
          description: Brex Cash management account ID.
        instructions:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Instruction'
        created_at:
          type: string
          format: date-time
      description: >-
        If the application status is ACTIVE, array of bank cash management
        accounts (note there is currently only one account per customer).
    Address:
      type: object
      properties:
        line1:
          type: string
          description: Address line 1, no PO Box.
          nullable: true
        line2:
          type: string
          description: Address line 2 (e.g., apartment, suite, unit, or building).
          nullable: true
        city:
          type: string
          description: City, district, suburb, town, or village.
          nullable: true
        state:
          type: string
          description: >-
            For US-addressed the 2-letter State abbreviation. For
            international-addresses the county, providence, or region.
          nullable: true
        country:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2).
          nullable: true
        postal_code:
          type: string
          description: ZIP or postal code.
          nullable: true
        phone_number:
          type: string
          description: Phone number.
          nullable: true
      description: >-
        Company business address (must be in the US; no PO box or
        virtual/forwarding addresses allowed).
    Applicant:
      required:
        - email
        - first_name
        - last_name
      type: object
      properties:
        last_name:
          type: string
          description: Last name of the applying customer.
          example: Smith
        first_name:
          type: string
          description: First name of the applying customer.
          example: Jane
        email:
          type: string
          description: Business email of the applying customer.
          format: email
          example: jane.smith@example.com
      description: Required information about the referred prospect.
    Application:
      required:
        - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApplicationStatus'
    ApplicationStatus:
      type: string
      description: >
        Application status of a product.


        `NO_ACCOUNT` - There is no active application, and the product account
        is not provisioned.


        `ACTIVE` - The application is approved, and the product account is
        provisioned.


        `NOT_SUBMITTED` - The application is started but not yet submitted.


        `INFORMATION_PENDING` - The application is submitted and additional
        information is requested.


        `MANUAL_REVIEW` - The application is under manual review.


        `PROCESSING` - The application is submitted and is under review.


        `REJECTED` - The application is rejected.


        `CLOSED` - The product account is closed.
      enum:
        - NO_ACCOUNT
        - ACTIVE
        - NOT_SUBMITTED
        - INFORMATION_PENDING
        - MANUAL_REVIEW
        - PROCESSING
        - REJECTED
        - CLOSED
    BeneficialOwner:
      required:
        - legal_name
        - prong
      type: object
      properties:
        legal_name:
          type: string
          description: Legal full name.
        company_relationship:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CompanyRelationship'
        date_of_birth:
          type: string
          description: Date of birth.
          format: date
          nullable: true
        identity_document:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/IdentityDocument'
        address:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Address'
            - description: Personal address of the owner (US-based or international)
        prong:
          $ref: '#/components/schemas/Prong'
        ownership_percentage:
          maximum: 100
          minimum: 25
          type: integer
          description: >-
            Ownership percentage (25-100). Only populated for individuals with
            ownership stakes (25% or more).
          format: int32
          nullable: true
          example: 25
      description: >-
        Federal law requires us to collect information for anyone who owns 25%
        or more of the company.
    Business:
      type: object
      properties:
        legal_name:
          type: string
          description: Company legal name.
          nullable: true
          example: Acme Corporation
        incorporation_type:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/IncorporationType'
        employer_identification_number:
          maxLength: 9
          minLength: 9
          type: string
          description: Company Employer Identification Number(EIN).
          nullable: true
          example: '123456789'
        website_url:
          type: string
          description: Business website (or link to ecommerce store for sellers).
          nullable: true
          example: https://www.acmecorp.com
        activity_description:
          type: string
          description: Brief description of the business activity.
          nullable: true
          example: Software as a Service platform for project management
        incorporation_year:
          type: integer
          description: Year of incorporation (YYYY format).
          format: int32
          nullable: true
          example: 2023
        incorporation_state:
          type: string
          description: State of incorporation (US state abbreviation).
          nullable: true
          example: CA
        address:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Address'
        beneficial_owners:
          type: array
          description: List of beneficial owners of the company
          nullable: true
          items:
            $ref: '#/components/schemas/BeneficialOwner'
        alternate_address:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Address'
      description: >
        Information about the business the application is for.


        You can optionally set the `alternate_address`, if the business has an
        additional address which is different from the 

        registration address. For instance, for international companies where
        their operational address may be different 

        than where the company was incorporated.
    Cash:
      required:
        - application
      type: object
      properties:
        accounts:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Account'
        application:
          $ref: '#/components/schemas/Application'
      description: Available if customer applied for Brex Cash.
    CompanyRelationship:
      type: string
      description: Relationship of this beneficial owner for this company.
      enum:
        - FOUNDER
        - EXECUTIVE
        - SENIOR_LEADERSHIP
        - OTHER
    ContactPreference:
      type: string
      description: >-
        When set to `EMAIL_OUTBOUND`, Brex will email the referred prospective
        customer directly to prompt them to create their account rather than
        rely on you to direct them to claim the account. If not provided, you
        are responsible for contacting the prospect and the value defaults to
        `NO_OUTBOUND`.
      enum:
        - NO_OUTBOUND
        - EMAIL_OUTBOUND
    CreateDocumentRequest:
      required:
        - type
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DocumentType'
      description: Request for creating new document upload URL.
    CreateReferralRequest:
      required:
        - applicant
        - referral_code
      type: object
      properties:
        referral_code:
          type: string
          description: >-
            Referral code that attributes credit to you if the prospect signs up
            for a Brex account.
          example: partner_abc123
        applicant:
          $ref: '#/components/schemas/Applicant'
        business:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Business'
        contact_preference:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ContactPreference'
      description: Submit a new referral to Brex for onboarding.
    Document:
      required:
        - id
        - uri
      type: object
      properties:
        uri:
          type: string
          description: >-
            This is a presigned S3 link that should be used to attach the
            document.

            The maximum size accepted for this document is 50 MB.
          example: >-
            https://brex-documents.s3.amazonaws.com/upload/abc123?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Expires=1234567890&Signature=example
        id:
          type: string
          description: Unique identifier for the document.
          example: prefdoc_a1b2c3d4e5
    DocumentType:
      type: string
      description: |
        Type of document being submitted. Allowable types:
        - ARTICLES_OF_INCORPORATION
        - IRS_EIN_CONFIRMATION (IRS CP 575, CP 575 fax sheet, or 147C form)
        - IRS_EIN_APPLICATION (IRS SS4 form)
        - CERTIFICATE_GOOD_STANDING
      enum:
        - ARTICLES_OF_INCORPORATION
        - IRS_EIN_CONFIRMATION
        - IRS_EIN_APPLICATION
        - CERTIFICATE_GOOD_STANDING
    DomesticInstruction:
      required:
        - account_type
        - bank_account_number
        - bank_address
        - bank_name
        - bank_routing_number
        - beneficiary_address
        - beneficiary_name
      type: object
      properties:
        account_type:
          type: string
        bank_account_number:
          type: string
        bank_routing_number:
          type: string
        beneficiary_name:
          type: string
        beneficiary_address:
          type: string
        bank_name:
          type: string
        bank_address:
          type: string
      description: Domestic ACH/wire instructions.
    IdentityDocument:
      required:
        - country
        - number
        - type
      type: object
      properties:
        country:
          type: string
          description: Country where the identity document was issued.
        type:
          $ref: '#/components/schemas/IdentityDocumentType'
        number:
          type: string
          description: US SSN or passport number.
      description: Document identifying the owner.
    IdentityDocumentType:
      type: string
      description: Either a US SSN or US/international passport.
      enum:
        - SSN
        - PASSPORT
    IncorporationType:
      type: string
      description: Incorporation type of the company referred.
      enum:
        - C_CORP
        - S_CORP
        - B_CORP
        - LLC
        - LLP
        - SOLE_PROP
        - ORG_501C3
        - LP
    Instruction:
      required:
        - domestic
        - international
      type: object
      properties:
        domestic:
          $ref: '#/components/schemas/DomesticInstruction'
        international:
          $ref: '#/components/schemas/InternationalInstruction'
      description: Domestic and international ACH/wire instructions.
    InternationalInstruction:
      required:
        - account_type
        - bank_address
        - bank_name
        - beneficiary_address
        - beneficiary_name
        - special_instructions
        - swift_account_number
        - swift_bank_number
      type: object
      properties:
        account_type:
          type: string
        swift_account_number:
          type: string
        swift_bank_number:
          type: string
        beneficiary_name:
          type: string
        beneficiary_address:
          type: string
        bank_name:
          type: string
        bank_address:
          type: string
        special_instructions:
          type: string
      description: International wire instructions.
    ProcessDelayedEINDocumentRequest:
      required:
        - document_id
      type: object
      properties:
        document_id:
          type: string
          description: The document ID returned from the initial document creation request
      description: Request for processing a delayed EIN document
    Product:
      required:
        - cash
      type: object
      properties:
        cash:
          $ref: '#/components/schemas/Cash'
      description: >-
        Array of Brex products that the customer has applied for. This is a
        gated feature available to select clients only.
    Prong:
      type: string
      description: >
        When using `CONTROL` prong, the beneficial owner is a single individual
        with 

        significant responsibility to control, manage, or direct a legal entity
        customer. This includes, an

        executive officer or senior manager (Chief Executive Officer, Chief
        Financial Officer, Chief

        Operating Officer, President), or any other individual who regularly
        performs similar

        functions. 


        Under the `OWNERSHIP` prong, a beneficial owner is each individual, if
        any, who, directly or

        indirectly, through any contract, arrangement, understanding,
        relationship or otherwise, owns

        25 percent or more of the equity interests of a legal entity customer.
        If a trust owns directly

        or indirectly, through any contract, arrangement, understanding,
        relationship or otherwise, 25

        percent or more of the equity interests of a legal entity customer, the
        beneficial owner is the

        trustee.


        Under the `BOTH` prong, the beneficial owner represents both.
      enum:
        - OWNERSHIP
        - CONTROL
        - BOTH
    Referral:
      required:
        - expires_at
        - id
        - products
        - referral_signup_url
        - status
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the referral.
          example: a1b2c3d4e5f6g7
        referral_signup_url:
          type: string
          description: >
            Signup URL to redirect prospects to complete their onboarding flow.


            *Note*: Necessary disclosures must be shown when the prospect clicks
            on this link.
          example: https://brex.com/signup?pref_token=a1b2c3d4e5f6g7
        expires_at:
          type: string
          description: The time at which this referral link expires.
          format: date-time
        customer_email:
          type: string
          description: >
            Customer's email address registered for the Brex application. This
            field is available only if there's a signup completed.
          format: email
          nullable: true
        status:
          $ref: '#/components/schemas/ReferralStatus'
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    ReferralPage:
      required:
        - items
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/Referral'
    ReferralStatus:
      type: string
      description: >-
        Status of the referral. `UNCLAIMED` or `EXPIRED` unless the customer
        completes signup. Customers are attributed once `ACTIVE` until the
        account is `CLOSED`.
      enum:
        - UNCLAIMED
        - EXPIRED
        - ACTIVE
        - CLOSED
  securitySchemes:
    Client Credentials:
      type: oauth2
      description: >

        Refer to
        [these](https://developer.brex.com/docs/partner_authentication/) docs on
        how to use client credentials.
      flows:
        clientCredentials:
          tokenUrl: https://accounts-api.brex.com/oauth2/default/v1/token
          scopes:
            openid: openid
            offline_access: offline access
            https://onboarding.brexapis.com/referrals: View and manage referral data.
x-explorer-enabled: false
