# 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.

Endpoint: POST /v1/referrals
Version: 1.0
Security: oAuth2ClientCredentials

## Request fields (application/json):

  - `referral_code` (string, required)
    Referral code that attributes credit to you if the prospect signs up for a Brex account.

  - `applicant` (object, required)
    Required information about the referred prospect.

  - `applicant.last_name` (string, required)
    Last name of the applying customer.

  - `applicant.first_name` (string, required)
    First name of the applying customer.

  - `applicant.email` (string, required)
    Business email of the applying customer.

  - `business` (object,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.

  - `business.legal_name` (string,null)
    Company legal name.

  - `business.incorporation_type` (string,null)
    Incorporation type of the company referred.
    Enum: "C_CORP", "S_CORP", "B_CORP", "LLC", "LLP", "SOLE_PROP", "ORG_501C3", "LP"

  - `business.employer_identification_number` (string,null)
    Company Employer Identification Number(EIN).

  - `business.website_url` (string,null)
    Business website (or link to ecommerce store for sellers).

  - `business.activity_description` (string,null)
    Brief description of the business activity.

  - `business.incorporation_year` (integer,null)
    Year of incorporation (YYYY format).
    Example: 2023

  - `business.incorporation_state` (string,null)
    State of incorporation (US state abbreviation).
    Example: "CA"

  - `business.address` (object,null)
    Company business address (must be in the US; no PO box or virtual/forwarding addresses allowed).

  - `business.address.line1` (string,null)
    Address line 1, no PO Box.

  - `business.address.line2` (string,null)
    Address line 2 (e.g., apartment, suite, unit, or building).

  - `business.address.city` (string,null)
    City, district, suburb, town, or village.

  - `business.address.state` (string,null)
    For US-addressed the 2-letter State abbreviation. For international-addresses the county, providence, or region.

  - `business.address.country` (string,null)
    Two-letter country code (ISO 3166-1 alpha-2).

  - `business.address.postal_code` (string,null)
    ZIP or postal code.

  - `business.address.phone_number` (string,null)
    Phone number.

  - `business.beneficial_owners` (array,null)
    List of beneficial owners of the company

  - `business.beneficial_owners.legal_name` (string, required)
    Legal full name.

  - `business.beneficial_owners.company_relationship` (string,null)
    Relationship of this beneficial owner for this company.
    Enum: "FOUNDER", "EXECUTIVE", "SENIOR_LEADERSHIP", "OTHER"

  - `business.beneficial_owners.date_of_birth` (string,null)
    Date of birth.

  - `business.beneficial_owners.identity_document` (object,null)
    Document identifying the owner.

  - `business.beneficial_owners.identity_document.country` (string, required)
    Country where the identity document was issued.

  - `business.beneficial_owners.identity_document.type` (string, required)
    Either a US SSN or US/international passport.
    Enum: "SSN", "PASSPORT"

  - `business.beneficial_owners.identity_document.number` (string, required)
    US SSN or passport number.

  - `business.beneficial_owners.prong` (string, required)
    When using CONTROL prong, the beneficial owner is a single individual with 
significant responsibility to control, manage, or direct a legal entity customer. This includes, an
executive officer or senior manager (Chief Executive Officer, Chief Financial Officer, Chief
Operating Officer, President), or any other individual who regularly performs similar
functions. 

Under the OWNERSHIP prong, a beneficial owner is each individual, if any, who, directly or
indirectly, through any contract, arrangement, understanding, relationship or otherwise, owns
25 percent or more of the equity interests of a legal entity customer. If a trust owns directly
or indirectly, through any contract, arrangement, understanding, relationship or otherwise, 25
percent or more of the equity interests of a legal entity customer, the beneficial owner is the
trustee.

Under the BOTH prong, the beneficial owner represents both.
    Enum: "OWNERSHIP", "CONTROL", "BOTH"

  - `business.beneficial_owners.ownership_percentage` (integer,null)
    Ownership percentage (25-100). Only populated for individuals with ownership stakes (25% or more).
    Example: 25

  - `business.alternate_address` (object,null)
    Company business address (must be in the US; no PO box or virtual/forwarding addresses allowed).

  - `contact_preference` (string,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"

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the referral.

  - `referral_signup_url` (string, required)
    Signup URL to redirect prospects to complete their onboarding flow.

Note: Necessary disclosures must be shown when the prospect clicks on this link.

  - `expires_at` (string, required)
    The time at which this referral link expires.

  - `customer_email` (string,null)
    Customer's email address registered for the Brex application. This field is available only if there's a signup completed.

  - `status` (string, required)
    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"

  - `products` (array, required)

  - `products.cash` (object, required)
    Available if customer applied for Brex Cash.

  - `products.cash.accounts` (array,null)

  - `products.cash.accounts.id` (string, required)
    Brex Cash management account ID.

  - `products.cash.accounts.instructions` (object,null)
    Domestic and international ACH/wire instructions.

  - `products.cash.accounts.instructions.domestic` (object, required)
    Domestic ACH/wire instructions.

  - `products.cash.accounts.instructions.domestic.account_type` (string, required)

  - `products.cash.accounts.instructions.domestic.bank_account_number` (string, required)

  - `products.cash.accounts.instructions.domestic.bank_routing_number` (string, required)

  - `products.cash.accounts.instructions.domestic.beneficiary_name` (string, required)

  - `products.cash.accounts.instructions.domestic.beneficiary_address` (string, required)

  - `products.cash.accounts.instructions.domestic.bank_name` (string, required)

  - `products.cash.accounts.instructions.domestic.bank_address` (string, required)

  - `products.cash.accounts.instructions.international` (object, required)
    International wire instructions.

  - `products.cash.accounts.instructions.international.swift_account_number` (string, required)

  - `products.cash.accounts.instructions.international.swift_bank_number` (string, required)

  - `products.cash.accounts.instructions.international.special_instructions` (string, required)

  - `products.cash.accounts.created_at` (string, required)

  - `products.cash.application` (object, required)

  - `products.cash.application.status` (string, required)
    Application status of a product.

NO_ACCOUNT - There is no active application, and the product account is not provisioned.

ACTIVE - The application is approved, and the product account is provisioned.

NOT_SUBMITTED - The application is started but not yet submitted.

INFORMATION_PENDING - The application is submitted and additional information is requested.

MANUAL_REVIEW - The application is under manual review.

PROCESSING - The application is submitted and is under review.

REJECTED - The application is rejected.

CLOSED - The product account is closed.
    Enum: "NO_ACCOUNT", "ACTIVE", "NOT_SUBMITTED", "INFORMATION_PENDING", "MANUAL_REVIEW", "PROCESSING", "REJECTED", "CLOSED"


## Response 401 fields