Referrals

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

The Onboarding API lets you create Brex referral links for prospects, prefill parts of their application, track referral status, and upload supporting documents. This guide covers the full referral flow, including delayed EIN document processing after a prospect has already signed up.

End-to-end flow

1. Generate an OAuth2 client credentials token with the https://onboarding.brexapis.com/referrals scope.
2. Create a referral and store the returned id, referral_signup_url, and expires_at.
3. Share the signup URL with the prospect, or set contact_preference to EMAIL_OUTBOUND if Brex should email them directly.
4. Use GET /v1/referrals/{id} or GET /v1/referrals to track status changes.
5. Upload supporting documents when needed with POST /v1/referrals/{id}/document_upload.
6. If the prospect signs up before providing an IRS EIN confirmation letter, use the delayed EIN flow after the referral becomes active.

Before you start

• A Brex-issued partner client ID and client secret
• A referral code assigned to your integration
• An OAuth2 token with the https://onboarding.brexapis.com/referrals scope
• Production API base URL: https://api.brex.com
• Staging API base URL: https://api-staging.brex.com

See Partner authentication for environment-specific auth endpoints and setup details.

1. Get an access token

Use the OAuth2 client credentials flow to request a bearer token:

curl https://accounts-api.brex.com/oauth2/default/v1/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'client_secret=<CLIENT_SECRET>' \
  --data-urlencode 'scope=https://onboarding.brexapis.com/referrals'

Use the access token in the Authorization header for every onboarding API request:

Authorization: Bearer <ACCESS_TOKEN>

When testing in staging, use the staging auth and API base URLs from the Partner authentication guide.

2. Create a referral

Call POST /v1/referrals with the prospect's applicant details and any business data you want Brex to prefill:

curl https://api.brex.com/v1/referrals \
  --request POST \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "referral_code": "partner_abc123",
    "applicant": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    },
    "business": {
      "legal_name": "Acme Inc.",
      "incorporation_type": "C_CORP",
      "employer_identification_number": "123456789",
      "website_url": "https://acme.com",
      "activity_description": "Software development",
      "incorporation_year": 2023,
      "incorporation_state": "CA",
      "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
    },
    "contact_preference": "EMAIL_OUTBOUND"
  }'

Example response:

{
  "id": "pref_abc123",
  "referral_signup_url": "https://brex.com/signup?pref_token=pref_abc123",
  "expires_at": "2026-04-14T10:30:00Z",
  "status": "UNCLAIMED",
  "products": [
    {
      "cash": {
        "application": {
          "status": "NO_ACCOUNT"
        }
      }
    }
  ]
}

Required fields:

• referral_code
• applicant.first_name
• applicant.last_name
• applicant.email

Implementation notes:

• business is optional, but it is the main way to prefill application data.
• business.address.country must be a two-letter ISO 3166-1 alpha-2 country code such as US.
• business.employer_identification_number, if provided, must be 9 digits.
• contact_preference defaults to NO_OUTBOUND. Set it to EMAIL_OUTBOUND if Brex should email the prospect directly.
• If you know the business EIN but do not yet have the IRS letter, you can still create the referral and use the delayed EIN flow later.
• Store the returned id and referral_signup_url securely. The signup URL contains sensitive referral data and expires at expires_at.

3. Track referral and application status

Use GET /v1/referrals/{id} when you already know the referral ID:

curl https://api.brex.com/v1/referrals/<REFERRAL_ID> \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Use GET /v1/referrals to sync the referrals your client created:

curl 'https://api.brex.com/v1/referrals?cursor=<NEXT_CURSOR>' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Instead of polling, you can subscribe to webhooks for real-time notifications. The onboarding API publishes REFERRAL_CREATED, REFERRAL_ACTIVATED, and REFERRAL_APPLICATION_STATUS_CHANGED events.

Tracking notes:

• GET /v1/referrals returns non-expired referrals only.
• Paginate with the cursor query parameter and the next_cursor field in the response.
• status shows the referral lifecycle:
  • UNCLAIMED: the signup link has not been used yet
  • EXPIRED: the signup link expired before signup
  • ACTIVE: the prospect completed signup and is attributed to a Brex customer account
  • CLOSED: the attributed account was later closed

4. Upload supporting documents

Call POST /v1/referrals/{id}/document_upload to create a presigned S3 upload URL for a referral document:

curl https://api.brex.com/v1/referrals/<REFERRAL_ID>/document_upload \
  --request POST \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "ARTICLES_OF_INCORPORATION"
  }'

Example response:

{
  "id": "prefdoc_a1b2c3d4e5",
  "uri": "https://s3.amazonaws.com/..."
}

Upload the file bytes to the returned uri with a PUT request:

curl '<PRESIGNED_URI>' \
  --request PUT \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@document.pdf'

Supported document types:

• ARTICLES_OF_INCORPORATION
• IRS_EIN_CONFIRMATION
• IRS_EIN_APPLICATION
• CERTIFICATE_GOOD_STANDING

Upload notes:

• The presigned S3 URL expires 30 minutes after it is created.
• The maximum file size is 50 MB.
• If the URL expires, call POST /v1/referrals/{id}/document_upload again to get a fresh uri.
• Repeating document_upload for the same referral and document type returns the same document id with a fresh upload URL.

5. Process a delayed EIN document

Use the delayed EIN flow when the prospect did not provide their IRS EIN confirmation document during initial referral creation, but later signs up and then supplies a CP-575 or 147C letter.

5a. Wait until the referral is attributed

Poll GET /v1/referrals/{id} until the referral status becomes ACTIVE, or listen for the REFERRAL_ACTIVATED webhook. ACTIVE means the referral is attached to a Brex customer account and delayed EIN processing can begin.

5b. Create an upload URL for the EIN confirmation document

curl https://api.brex.com/v1/referrals/<REFERRAL_ID>/document_upload \
  --request POST \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "IRS_EIN_CONFIRMATION"
  }'

5c. Upload the CP-575 or 147C file to the presigned S3 URL

curl '<PRESIGNED_URI>' \
  --request PUT \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@ein-confirmation.pdf'

5d. Trigger delayed EIN processing

Use the document ID returned in step 5b:

curl https://api.brex.com/v1/referrals/<REFERRAL_ID>/process_ein_document \
  --request POST \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_id": "prefdoc_a1b2c3d4e5"
  }'

A successful call returns 200 OK with an empty response body. Brex will process the uploaded document to complete EIN verification for the customer.

Delayed EIN rules:

• document_id must be the document id returned by POST /v1/referrals/{id}/document_upload.
• The document must belong to the same referral you are processing.
• The document must be of type IRS_EIN_CONFIRMATION.
• Call the processing endpoint only after the file upload has completed. If the upload is missing or incomplete, the endpoint returns 400.
• Call the processing endpoint only after the referral is attributed to a customer account. If the referral is not yet ACTIVE, the endpoint returns 400.

Common error cases

For the full schema reference, see the Onboarding API reference.