Start your case

To kick off a KYB check, you’ll need to create a case. Use the following endpoint to submit a business and its owners for verification. This endpoint expects a JSON data object with two root fields:

business (Required) - A JSON object with detailed information about the business
persons (Required) - An array of Person JSON objects with detailed information about the people associated to the business (at least one must be sent)

Note: Authentication is done through a Bearer token with your API key (see Introduction > Configure API Access)

Endpoint

POST /identity/cases

Request Format

curl --request POST  
  --url <https://api.dev.getbeam.cash/identity/cases>  
  --header 'Authorization: Bearer beam_sandbox_abc123'  
  --header 'Content-Type: application/json'  
  --data '{  
    "business": {  
        "name": "string (DBA name, optional)",  
        "legalName": "string (required)",  
        "description": "string (optional, required for full KYB)",  
        "ein": "string (optional, required for full KYB)",  
        "industry": "Industry (optional - See Supported Parameters)",  
        "phoneNumber": "string (E.164 format, optional, required for full KYB)",  
        "email": "string (required)",  
        "website": "string (optional)",  
        "legalEntityType": "LegalEntityType (required - See Supported Parameters)",  
        "incorporationDate": "string (ISO 8601 date, optional, required for full KYB)",  
        "stateOfFormation": "USStateCode (optional, required for full KYB - See Supported Parameters)",  
        "countryOfFormation": "CountryCode (optional, required for full KYB - See Supported Parameters)",  
        "regulatoryStatus": "BusinessRegulatoryStatus (optional)",  
        "regulatoryAuthority": "string (optional)",  
        "regulatorJurisdiction": "CountryCode (optional - See Supported Parameters)",  
        "regulatorRegisterNumber": "string (optional)",  
        "nicCode": "string (optional)",  
        "tradingType": "TradingType (optional - See Supported Parameters)",  
        "monthlyTransactionVolume": "string (optional)",  
        "registeredAddress": {  
            "street1": "string (required)",  
            "street2": "string (optional)",  
            "district": "string (optional)",  
            "city": "string (required)",  
            "state": "USStateCode (required - See Supported Parameters)",  
            "postalCode": "string (required)",  
            "country": "CountryCode (required - See Supported Parameters)"  
        },  
        "physicalAddress": {  
            "street1": "string (required)",  
            "street2": "string (optional)",  
            "district": "string (optional)",  
            "city": "string (required)",  
            "state": "USStateCode (required - See Supported Parameters)",  
            "postalCode": "string (required)",  
            "country": "CountryCode (required - See Supported Parameters)"  
        }  
    },  
    "persons": [  
        {  
            "firstName": "string (optional, required for full KYC)",  
            "firstName2": "string (optional)",  
            "middleName": "string (optional)",  
            "lastName": "string (optional, required for full KYC)",  
            "lastName2": "string (optional)",  
            "email": "string (required)",  
            "phoneNumber": "string (E.164 format, optional, required for full KYC)",  
            "ssn": "string (optional, required for full KYC)",  
            "birthdate": "string (ISO 8601 date, optional)",  
            "employmentStatus": "EmploymentStatus (optional, required for full KYC - See Supported Parameters)",  
            "industry": "Industry (optional, required for full KYC - See Supported Parameters)",  
            "occupation": "Occupation (optional, required for full KYC - See Supported Parameters)",  
            "annualIncome": "number (optional, required for full KYC)",  
            "incomeSource": "IncomeSource (optional, required for full KYC - See Supported Parameters)",  
            "incomeCountryCode": "CountryCode (ISO 3166-1 alpha-2, optional, required for for KYC - See Supported Parameters)",  
            "wealthSource": "WealthSource (optional, required for full KYC - See Supported Parameters)",  
            "address": {  
                "street1": "string (required)",  
                "street2": "string (optional)",  
                "district": "string (optional)",  
                "city": "string (required)",  
                "state": "USStateCode (required - See Supported Parameters)",  
                "postalCode": "string (required)",  
                "country": "CountryCode (required - See Supported Parameters)"  
            },  
            "role": "BusinessPersonRole (required - See Supported Parameters)"  
        }  
    ]  
}'

Once submitted, Beam will return a case_id that you can use to track status and take action (see next step).