Skip to content
APIs/Onboarding/
/
Gets a referral by ID

Onboarding API (1.0)

The onboarding API allows you to refer your customers and personal contacts to Brex.

Download OpenAPI description
onboarding_api.json
onboarding_api.yaml
Overview
URL
https://brex.com
Admin
developer-support@brex.com
Languages
Servers
Production
https://api.brex.com
Staging (Note: This is not a sandbox. It will not work with customer tokens.)
https://api-staging.brex.com

Referrals

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.

Operations

List referrals

Request

Returns referrals created. Note: This doesn't include referrals that have expired.

Security
oAuth2ClientCredentials
Query
cursorstring or null
curl -i -X GET \
  https://api.brex.com/v1/referrals \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

listReferrals 200 response

Bodyapplication/json
next_cursorstring or null
itemsArray of objects(Referral)required
items[].​idstringrequired

Unique identifier for the referral.

items[].​referral_signup_urlstringrequired

Signup URL to redirect prospects to complete their onboarding flow.

Note: Necessary disclosures must be shown when the prospect clicks on this link.

items[].​expires_atstring(date-time)required

The time at which this referral link expires.

items[].​customer_emailstring or null(email)

Customer's email address registered for the Brex application. This field is available only if there's a signup completed.

items[].​statusstring(ReferralStatus)required

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"
items[].​productsArray of objects(Product)required
items[].​products[].​cashobject(Cash)required

Available if customer applied for Brex Cash.

items[].​products[].​cash.​accountsArray of objects or null(Account)
items[].​products[].​cash.​applicationobject(Application)required
items[].​products[].​cash.​application.​statusstring(ApplicationStatus)required

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"
Response
application/json
{
  "next_cursor": "string",
  "items": [
    { … }
  ]
}

Creates a referral

Request

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.

Security
oAuth2ClientCredentials
Bodyapplication/jsonrequired
referral_codestringrequired

Referral code that attributes credit to you if the prospect signs up for a Brex account.

applicantobject(Applicant)required

Required information about the referred prospect.

applicant.​last_namestringrequired

Last name of the applying customer.

applicant.​first_namestringrequired

First name of the applying customer.

applicant.​emailstring(email)required

Business email of the applying customer.

businessobject or null

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.

contact_preferencestring or null

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"
curl -i -X POST \
  https://api.brex.com/v1/referrals \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "referral_code": "string",
    "applicant": {
      "last_name": "string",
      "first_name": "string",
      "email": "user@example.com"
    },
    "business": {
      "legal_name": "string",
      "incorporation_type": "C_CORP",
      "employer_identification_number": "stringstr",
      "website_url": "string",
      "activity_description": "string",
      "incorporation_year": 2023,
      "incorporation_state": "CA",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "string",
        "country": "string",
        "postal_code": "string",
        "phone_number": "string"
      },
      "beneficial_owners": [
        {
          "legal_name": "string",
          "company_relationship": "FOUNDER",
          "date_of_birth": "2019-08-24",
          "identity_document": {
            "country": "string",
            "type": "SSN",
            "number": "string"
          },
          "address": {
            "line1": "string",
            "line2": "string",
            "city": "string",
            "state": "string",
            "country": "string",
            "postal_code": "string",
            "phone_number": "string"
          },
          "prong": "OWNERSHIP",
          "ownership_percentage": 25
        }
      ],
      "alternate_address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "string",
        "country": "string",
        "postal_code": "string",
        "phone_number": "string"
      }
    },
    "contact_preference": "NO_OUTBOUND"
  }'

Responses

createReferralRequest 200 response

Bodyapplication/json
idstringrequired

Unique identifier for the referral.

referral_signup_urlstringrequired

Signup URL to redirect prospects to complete their onboarding flow.

Note: Necessary disclosures must be shown when the prospect clicks on this link.

expires_atstring(date-time)required

The time at which this referral link expires.

customer_emailstring or null(email)

Customer's email address registered for the Brex application. This field is available only if there's a signup completed.

statusstring(ReferralStatus)required

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"
productsArray of objects(Product)required
products[].​cashobject(Cash)required

Available if customer applied for Brex Cash.

products[].​cash.​accountsArray of objects or null(Account)
products[].​cash.​applicationobject(Application)required
products[].​cash.​application.​statusstring(ApplicationStatus)required

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"
Response
application/json
{
  "id": "string",
  "referral_signup_url": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "customer_email": "user@example.com",
  "status": "UNCLAIMED",
  "products": [
    { … }
  ]
}

Gets a referral by ID

Request

Returns a referral object by ID if it exists.

Security
oAuth2ClientCredentials
Path
idstringrequired
curl -i -X GET \
  'https://api.brex.com/v1/referrals/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

getReferral 200 response

Bodyapplication/json
idstringrequired

Unique identifier for the referral.

referral_signup_urlstringrequired

Signup URL to redirect prospects to complete their onboarding flow.

Note: Necessary disclosures must be shown when the prospect clicks on this link.

expires_atstring(date-time)required

The time at which this referral link expires.

customer_emailstring or null(email)

Customer's email address registered for the Brex application. This field is available only if there's a signup completed.

statusstring(ReferralStatus)required

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"
productsArray of objects(Product)required
products[].​cashobject(Cash)required

Available if customer applied for Brex Cash.

products[].​cash.​accountsArray of objects or null(Account)
products[].​cash.​applicationobject(Application)required
products[].​cash.​application.​statusstring(ApplicationStatus)required

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"
Response
application/json
{
  "id": "string",
  "referral_signup_url": "string",
  "expires_at": "2019-08-24T14:15:22Z",
  "customer_email": "user@example.com",
  "status": "UNCLAIMED",
  "products": [
    { … }
  ]
}

Create a new document upload

Request

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 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.

Security
oAuth2ClientCredentials
Path
idstringrequired
Bodyapplication/jsonrequired
typestring(DocumentType)required

Type of document being submitted. Allowable types:

  • ARTICLES_OF_INCORPORATION
  • IRS_EIN_CONFIRMATION (IRS CP 575 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"
curl -i -X POST \
  'https://api.brex.com/v1/referrals/{id}/document_upload' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "ARTICLES_OF_INCORPORATION"
  }'

Responses

createDocument 200 response

Bodyapplication/json
uristringrequired

This is a presigned S3 link that should be used to attach the document. The maximum size accepted for this document is 50 MB.

idstringrequired

Unique identifier for the document.

Response
application/json
{
  "uri": "string",
  "id": "string"
}
Copyright © Brex 2019–2026. All rights reserved.