{ "openapi": "3.0.1", "info": { "title": "Onboarding API", "description": "\nThe onboarding API allows you to refer your customers and personal contacts to Brex.\n", "contact": { "name": "Admin", "url": "https://brex.com", "email": "developer-support@brex.com" }, "version": "1.0", "x-logo": { "altText": "Brex Logo", "url": "https://www.brex.com/logo.png" } }, "servers": [ { "url": "https://api.brex.com", "description": "Production" }, { "url": "https://api-staging.brex.com", "description": "Staging (Note: This is not a sandbox. It will not work with customer tokens.)" } ], "security": [ { "oAuth2ClientCredentials": [] } ], "tags": [ { "name": "Referrals", "description": "\nThe onboarding API allows you to submit customer referrals to Brex and receive a customized Brex application URL. You can\noptionally submit additional information to help prefill their application with data you may have about the customer.\nYou also can get visibility into the application approval status.\n" } ], "paths": { "/v1/referrals": { "get": { "tags": [ "Referrals" ], "summary": "List referrals", "description": "Returns referrals created.\n*Note*: This doesn't include referrals that have expired.\n", "operationId": "listReferrals", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "listReferrals 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralPage" } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "Referrals" ], "summary": "Creates a referral", "description": "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.", "operationId": "createReferralRequest", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReferralRequest" } } }, "required": true }, "responses": { "200": { "description": "createReferralRequest 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Referral" } } } }, "401": { "description": "Unauthorized" } } } }, "/v1/referrals/{id}": { "get": { "tags": [ "Referrals" ], "summary": "Gets a referral by ID", "description": "Returns a referral object by ID if it exists.", "operationId": "getReferral", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "getReferral 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Referral" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Referral not found" } } } }, "/v1/referrals/{id}/document_upload": { "post": { "tags": [ "Referrals" ], "summary": "Create a new document upload", "description": "\nThe `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.\n\nRefer to these [docs](https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html) 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.\n", "operationId": "createDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "createDocument 200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Referral not found" } } } } }, "components": { "schemas": { "Account": { "required": [ "created_at", "id" ], "type": "object", "properties": { "id": { "required": [ "true" ], "type": "string", "description": "Brex Cash management account ID." }, "instructions": { "allOf": [ { "$ref": "#/components/schemas/Instruction" }, { "nullable": true } ] }, "created_at": { "type": "string", "format": "date-time" } }, "description": "If the application status is APPROVED, array of bank cash management accounts (note there is currently only one account per customer)." }, "Address": { "type": "object", "properties": { "line1": { "type": "string", "description": "Address line 1, no PO Box.", "nullable": true }, "line2": { "type": "string", "description": "Address line 2 (e.g., apartment, suite, unit, or building).", "nullable": true }, "city": { "type": "string", "description": "City, district, suburb, town, or village.", "nullable": true }, "state": { "type": "string", "description": "For US-addressed the 2-letter State abbreviation. For international-addresses the county, providence, or region.", "nullable": true }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2).", "nullable": true }, "postal_code": { "type": "string", "description": "ZIP or postal code.", "nullable": true }, "phone_number": { "type": "string", "description": "Phone number.", "nullable": true } }, "description": "Company business address (must be in the US; no PO box or virtual/forwarding addresses allowed)." }, "Applicant": { "required": [ "email", "first_name", "last_name" ], "type": "object", "properties": { "last_name": { "required": [ "true" ], "type": "string", "description": "Last name of the applying customer." }, "first_name": { "required": [ "true" ], "type": "string", "description": "First name of the applying customer." }, "email": { "required": [ "true" ], "type": "string", "description": "Business email of the applying customer.", "format": "email" } }, "description": "Required information about the referred prospect." }, "Application": { "required": [ "status" ], "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ApplicationStatus" } } }, "ApplicationStatus": { "type": "string", "description": "Application status of a product.\n\n`NO_ACCOUNT` - There is no active application, and the product account is not provisioned.\n\n`ACTIVE` - The application is approved, and the product account is provisioned.\n\n`NOT_SUBMITTED` - The application is started but not yet submitted.\n\n`INFORMATION_PENDING` - The application is submitted and additional information is requested.\n\n`MANUAL_REVIEW` - The application is under manual review.\n\n`PROCESSING` - The application is submitted and is under review.\n\n`REJECTED` - The application is rejected.\n\n`CLOSED` - The product account is closed.\n", "enum": [ "NO_ACCOUNT", "ACTIVE", "NOT_SUBMITTED", "INFORMATION_PENDING", "MANUAL_REVIEW", "PROCESSING", "REJECTED", "CLOSED" ] }, "BeneficialOwner": { "required": [ "legal_name", "prong" ], "type": "object", "properties": { "legal_name": { "required": [ "true" ], "type": "string", "description": "Legal full name." }, "company_relationship": { "allOf": [ { "$ref": "#/components/schemas/CompanyRelationship" }, { "nullable": true } ] }, "date_of_birth": { "type": "string", "description": "Date of birth.", "format": "date", "nullable": true }, "identity_document": { "allOf": [ { "$ref": "#/components/schemas/IdentityDocument" }, { "nullable": true } ] }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "nullable": true } ] }, "prong": { "$ref": "#/components/schemas/Prong" }, "ownership_percentage": { "type": "integer", "description": "Ownership percentage (25-100). Only populated for individuals with ownership stakes (25% or more).", "nullable": true, "minimum": 25, "maximum": 100, "example": 25 } }, "description": "Federal law requires us to collect information for anyone who owns 25% or more of the company." }, "Business": { "type": "object", "properties": { "legal_name": { "type": "string", "description": "Company legal name.", "nullable": true }, "incorporation_type": { "allOf": [ { "$ref": "#/components/schemas/IncorporationType" }, { "nullable": true } ] }, "employer_identification_number": { "maxLength": 9, "minLength": 9, "type": "string", "description": "Company Employer Identification Number(EIN).", "nullable": true }, "website_url": { "type": "string", "description": "Business website (or link to ecommerce store for sellers).", "nullable": true }, "activity_description": { "type": "string", "description": "Brief description of the business activity.", "nullable": true }, "incorporation_year": { "type": "integer", "description": "Year of incorporation (YYYY format).", "nullable": true, "example": 2023 }, "incorporation_state": { "type": "string", "description": "State of incorporation (US state abbreviation).", "nullable": true, "example": "CA" }, "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "nullable": true } ] }, "beneficial_owners": { "type": "array", "description": "List of beneficial owners of the company", "nullable": true, "items": { "$ref": "#/components/schemas/BeneficialOwner" } }, "alternate_address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "nullable": true } ] } }, "description": "Information about the business the application is for.\n\nYou can optionally set the `alternate_address`, if the business has an additional address which is different from the \nregistration address. For instance, for international companies where their operational address may be different \nthan where the company was incorporated.\n" }, "Cash": { "required": [ "application" ], "type": "object", "properties": { "accounts": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Account" } }, "application": { "$ref": "#/components/schemas/Application" } }, "description": "Available if customer applied for Brex Cash." }, "CompanyRelationship": { "type": "string", "description": "Relationship of this beneficial owner for this company.", "enum": [ "FOUNDER", "EXECUTIVE", "SENIOR_LEADERSHIP", "OTHER" ] }, "ContactPreference": { "type": "string", "description": "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" ] }, "CreateDocumentRequest": { "required": [ "type" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/DocumentType" } }, "description": "Request for creating new document upload URL." }, "CreateReferralRequest": { "required": [ "applicant", "referral_code" ], "type": "object", "properties": { "referral_code": { "required": [ "true" ], "type": "string", "description": "Referral code that attributes credit to you if the prospect signs up for a Brex account." }, "applicant": { "$ref": "#/components/schemas/Applicant" }, "business": { "allOf": [ { "$ref": "#/components/schemas/Business" }, { "nullable": true } ] }, "contact_preference": { "allOf": [ { "$ref": "#/components/schemas/ContactPreference" }, { "nullable": true } ] } }, "description": "Submit a new referral to Brex for onboarding." }, "Document": { "required": [ "id", "uri" ], "type": "object", "properties": { "uri": { "required": [ "true" ], "type": "string", "description": "This is a presigned S3 link that should be used to attach the document.\nThe maximum size accepted for this document is 50 MB." }, "id": { "required": [ "true" ], "type": "string", "description": "Unique identifier for the document." } } }, "DocumentType": { "type": "string", "description": "Type of document being submitted. Allowable types:\n- ARTICLES_OF_INCORPORATION\n- IRS_EIN_CONFIRMATION (IRS CP 575 or 147C form)\n- IRS_EIN_APPLICATION (IRS SS4 form)\n- CERTIFICATE_GOOD_STANDING\n", "enum": [ "ARTICLES_OF_INCORPORATION", "IRS_EIN_CONFIRMATION", "IRS_EIN_APPLICATION", "CERTIFICATE_GOOD_STANDING" ] }, "DomesticInstruction": { "required": [ "account_type", "bank_account_number", "bank_address", "bank_name", "bank_routing_number", "beneficiary_address", "beneficiary_name" ], "type": "object", "properties": { "account_type": { "type": "string" }, "bank_account_number": { "type": "string" }, "bank_routing_number": { "type": "string" }, "beneficiary_name": { "type": "string" }, "beneficiary_address": { "type": "string" }, "bank_name": { "type": "string" }, "bank_address": { "type": "string" } }, "description": "Domestic ACH/wire instructions." }, "IdentityDocument": { "required": [ "country", "number", "type" ], "type": "object", "properties": { "country": { "required": [ "true" ], "type": "string", "description": "Country where the identity document was issued." }, "type": { "$ref": "#/components/schemas/IdentityDocumentType" }, "number": { "required": [ "true" ], "type": "string", "description": "US SSN or passport number." } }, "description": "Document identifying the owner." }, "IdentityDocumentType": { "type": "string", "description": "Either a US SSN or US/international passport.", "enum": [ "SSN", "PASSPORT" ] }, "IncorporationType": { "type": "string", "description": "Incorporation type of the company referred.", "enum": [ "C_CORP", "S_CORP", "B_CORP", "LLC", "LLP", "SOLE_PROP", "ORG_501C3", "LP" ] }, "Instruction": { "required": [ "domestic", "international" ], "type": "object", "properties": { "domestic": { "$ref": "#/components/schemas/DomesticInstruction" }, "international": { "$ref": "#/components/schemas/InternationalInstruction" } }, "description": "Domestic and international ACH/wire instructions." }, "InternationalInstruction": { "required": [ "account_type", "bank_address", "bank_name", "beneficiary_address", "beneficiary_name", "special_instructions", "swift_account_number", "swift_bank_number" ], "type": "object", "properties": { "account_type": { "type": "string" }, "swift_account_number": { "type": "string" }, "swift_bank_number": { "type": "string" }, "beneficiary_name": { "type": "string" }, "beneficiary_address": { "type": "string" }, "bank_name": { "type": "string" }, "bank_address": { "type": "string" }, "special_instructions": { "type": "string" } }, "description": "International wire instructions." }, "Product": { "required": [ "cash" ], "type": "object", "properties": { "cash": { "$ref": "#/components/schemas/Cash" } }, "description": "Array of Brex products that the customer has applied for. This is a gated feature available to select clients only." }, "Prong": { "type": "string", "description": "When using `CONTROL` prong, the beneficial owner is a single individual with \nsignificant responsibility to control, manage, or direct a legal entity customer. This includes, an\nexecutive officer or senior manager (Chief Executive Officer, Chief Financial Officer, Chief\nOperating Officer, President), or any other individual who regularly performs similar\nfunctions. \n\nUnder the `OWNERSHIP` prong, a beneficial owner is each individual, if any, who, directly or\nindirectly, through any contract, arrangement, understanding, relationship or otherwise, owns\n25 percent or more of the equity interests of a legal entity customer. If a trust owns directly\nor indirectly, through any contract, arrangement, understanding, relationship or otherwise, 25\npercent or more of the equity interests of a legal entity customer, the beneficial owner is the\ntrustee.\n\nUnder the `BOTH` prong, the beneficial owner represents both.\n", "enum": [ "OWNERSHIP", "CONTROL", "BOTH" ] }, "Referral": { "required": [ "expires_at", "id", "products", "referral_signup_url", "status" ], "type": "object", "properties": { "id": { "required": [ "true" ], "type": "string", "description": "Unique identifier for the referral." }, "referral_signup_url": { "required": [ "true" ], "type": "string", "description": "Signup URL to redirect prospects to complete their onboarding flow.\n\n*Note*: Necessary disclosures must be shown when the prospect clicks on this link.\n" }, "expires_at": { "required": [ "true" ], "type": "string", "description": "The time at which this referral link expires.", "format": "date-time" }, "customer_email": { "type": "string", "description": "Customer's email address registered for the Brex application. This field is available only if there's a signup completed.\n", "format": "email", "nullable": true }, "status": { "$ref": "#/components/schemas/ReferralStatus" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "ReferralPage": { "required": [ "items" ], "type": "object", "properties": { "next_cursor": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Referral" } } } }, "ReferralStatus": { "type": "string", "description": "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" ] } }, "securitySchemes": { "oAuth2ClientCredentials": { "type": "oauth2", "description": "\nRefer to [these](https://developer.brex.com/docs/onboarding_examples/) docs on how to use client credentials \n", "flows": { "clientCredentials": { "tokenUrl": "https://accounts-api.brex.com/oauth2/default/v1/token", "scopes": { "openid": "openid", "offline_access": "offline access", "https://onboarding.brexapis.com/referrals": "View and manage referral data." } } } } } }, "x-explorer-enabled": false }