## Onboarding API examples

See the [Referrals guide](/onboarding/referrals) for a full end-to-end walkthrough. This page keeps a few short examples handy for quick testing.

**Create a referral**


```json
POST https://api.brex.com/v1/referrals

REQUEST
{
  "referral_code": "partner_refcode",
  "applicant": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@doeinc.com"
  },
  "business": {
    "legal_name": "Doe Inc",
    "incorporation_type": "C_CORP",
    "website_url": "https://doeinc.com"
  }
}

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

The returned `referral_signup_url` is the link you share with the prospect.

**Get an update about a referral**


```json
GET https://api.brex.com/v1/referrals/referral_123

RESPONSE
{
  "id": "referral_123",
  "referral_signup_url": "https://brex.com/signup?pref_token=referral_123",
  "expires_at": "2026-04-14T10:30:00",
  "status": "ACTIVE",
  "products": [
    {
      "cash": {
        "application": {
          "status": "PROCESSING"
        }
      }
    }
  ]
}
```

`status: ACTIVE` means the referral has been attributed to a Brex customer account.

**Create a document upload**


```json
POST https://api.brex.com/v1/referrals/referral_123/document_upload

REQUEST
{
  "type": "ARTICLES_OF_INCORPORATION"
}

RESPONSE
{
  "uri": "https://s3.amazonaws.com/destination-link",
  "id": "document_123"
}
```

Upload the file to the returned presigned URL:


```json
PUT https://s3.amazonaws.com/destination-link

REQUEST
* binary file content
```

**Process a delayed EIN document**

Use this after the referral is `ACTIVE`, the document type is `IRS_EIN_CONFIRMATION`, and the file has already been uploaded to S3.


```json
POST https://api.brex.com/v1/referrals/referral_123/process_ein_document

REQUEST
{
  "document_id": "document_123"
}

RESPONSE
200 OK
```