Onboarding API (1.0)

Download OpenAPI specification:Download

Admin: developer-access@brex.com URL: https://brex.com

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

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.

List referrals

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

SecurityoAuth2ClientCredentials

Request

query Parameters

cursor

string or null

Responses

200

listReferrals 200 response

400

Invalid cursor

401

Unauthorized

get/v1/referrals

Request samples

curl
JavaScript
Node.js
Python

Response samples

application/json

{"next_cursor": "string",
"items": [{"id": "string",
"referral_signup_url": "string",
"expires_at": "2019-08-24T14:15:22Z",
"customer_email": "user@example.com",
"status": "UNCLAIMED",
"products": [{"cash": {"accounts": [{"id": null,
"instructions": null,
"created_at": null
}
],
"application": {"status": "NO_ACCOUNT"
}
}
}
]
}
]
}

Creates a referral

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.

SecurityoAuth2ClientCredentials

Request

Request Body schema: application/json

referral_code required	string Referral code that attributes credit to you if the prospect signs up for a Brex account.
required	object (Applicant) Required information about the referred prospect.
	object 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_preference	string 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"

Responses

200

createReferralRequest 200 response

401

Unauthorized

post/v1/referrals

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"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",
"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"
}
],
"alternate_address": {"line1": "string",
"line2": "string",
"city": "string",
"state": "string",
"country": "string",
"postal_code": "string",
"phone_number": "string"
}
},
"contact_preference": "NO_OUTBOUND"
}

Response samples

application/json

{"id": "string",
"referral_signup_url": "string",
"expires_at": "2019-08-24T14:15:22Z",
"customer_email": "user@example.com",
"status": "UNCLAIMED",
"products": [{"cash": {"accounts": [{"id": "string",
"instructions": {"domestic": {"account_type": null,
"bank_account_number": null,
"bank_routing_number": null,
"beneficiary_name": null,
"beneficiary_address": null,
"bank_name": null,
"bank_address": null
},
"international": {"account_type": null,
"swift_account_number": null,
"swift_bank_number": null,
"beneficiary_name": null,
"beneficiary_address": null,
"bank_name": null,
"bank_address": null,
"special_instructions": null
}
},
"created_at": "2019-08-24T14:15:22Z"
}
],
"application": {"status": "NO_ACCOUNT"
}
}
}
]
}

Gets a referral by ID

Returns a referral object by ID if it exists.

SecurityoAuth2ClientCredentials

Request

path Parameters

required

string

Responses

200

getReferral 200 response

401

Unauthorized

404

Referral not found

get/v1/referrals/{id}

Request samples

curl
JavaScript
Node.js
Python

Response samples

application/json

{"id": "string",
"referral_signup_url": "string",
"expires_at": "2019-08-24T14:15:22Z",
"customer_email": "user@example.com",
"status": "UNCLAIMED",
"products": [{"cash": {"accounts": [{"id": "string",
"instructions": {"domestic": {"account_type": null,
"bank_account_number": null,
"bank_routing_number": null,
"beneficiary_name": null,
"beneficiary_address": null,
"bank_name": null,
"bank_address": null
},
"international": {"account_type": null,
"swift_account_number": null,
"swift_bank_number": null,
"beneficiary_name": null,
"beneficiary_address": null,
"bank_name": null,
"bank_address": null,
"special_instructions": null
}
},
"created_at": "2019-08-24T14:15:22Z"
}
],
"application": {"status": "NO_ACCOUNT"
}
}
}
]
}

Create a new document upload

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.

SecurityoAuth2ClientCredentials

Request

path Parameters

required

string

Request Body schema: application/json

type

required

string (DocumentType)

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"

Responses

200

createDocument 200 response

401

Unauthorized

404

Referral not found

post/v1/referrals/{id}/document_upload

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"type": "ARTICLES_OF_INCORPORATION"
}

Response samples

application/json

{"uri": "string",
"id": "string"
}