# Referrals

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](/guides/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:


```bash
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:


```http
Authorization: Bearer <ACCESS_TOKEN>
```

When testing in staging, use the staging auth and API base URLs from the [Partner authentication](/guides/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:


```bash
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:


```json
{
  "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:


```bash
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:


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

Instead of polling, you can subscribe to [webhooks](/guides/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:


```bash
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:


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

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


```bash
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](/guides/webhooks). `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


```bash
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


```bash
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:


```bash
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

| Status | Meaning |
|  --- | --- |
| `400` | Invalid request body, invalid cursor, delayed EIN called before upload completed, delayed EIN called before attribution, or delayed EIN called with the wrong document type. |
| `401` | Missing or invalid bearer token, or the token does not include the referrals scope. |
| `404` | Referral not found for your client, or the supplied document does not belong to that referral. |


For the full schema reference, see the [Onboarding API reference](/openapi/onboarding_api).