Account Creation

This endpoint is used to create a new Veem account. You will need your Oauth2 token to be able to hit this endpoint.

POST https://sandbox-api.veem.com/veem/v1.2/account

Headers

There are 2 headers necessary for the use of this endpoint:

• X-request-id: This is a number unique to the current API request, and follows the UUID format. Reusing this header without changing the value will result in a 500 (Internal Server Error) status. An example X-request-id is as follows:

48855846-628d-4177-b071-80332a116f0a

• Authorization: This header holds the bearer token required to use Veem's public API. Failure to use a valid bearer token will result in a 404 (Not Found) status. An example of a valid token is as follows:

Bearer c047594b-082c-4da1-be89-08fe3770f4b3

Request Payload

When creating an account using Veem's Account Creation API, one must follow the format as shown in the following example:

 {  
     "email": "[email protected]",  
     "firstName": "Thomas",  
     "middleName": "Robert",  
     "lastName": "Scott",  
     "extraName": "Hernandez",  
     "isoCountryCode": "US",  
     "dialCode": "+1",  
     "phoneNumber": "2046611473",  
     "businessName": "API Testing",  
     "businessEntity": "Corporation",  
     "taxIdNumber": "33-1867307",  
     "industry": "Software, IT and Telecommunications",  
     "subIndustry": "Software", 
     "type": "Business",
     "address": {  
         "countryCode": "US",  
         "street": "166 Battery St",  
         "streetSecondary": "166 Battery St",  
         "city": "San Francisco",  
         "postalCode": "94111",  
         "province": "CA"  
     },  
     "bankInfo": {  
         "isoCountryCode": "US",  
         "bankName": "Bank of America",  
         "currencyCode": "USD",  
         "bankAccountNumber": "12345678",  
         "routingNumber": "026009593"  
     },  
     "extraInfo": {  
         "purposeOfPayment": "Services",  
         "purposeOfPaymentDescription": "Thanks for your services"  
     }  
 }

Note: Not all of these parameters are required for the creation of a Veem account, and can be omitted from the request body altogether. Furthermore, the parameters are different when creating a business account as opposed to a personal account.

Request Parameters

The following table contains detailed information on the payload's parameters, such as the parameter name, whether it is mandatory or not, formatting (if applicable), and size of the parameter

For extra information, you can find some resources here:
ISO 3166-1 alpha-2 standard: https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes
Dial codes: https://en.wikipedia.org/wiki/List_of_country_calling_codes

Industry and subindustry list:

Response Payload

Once a valid request has been sent, a response payload of this format should be expected:

{
    "id": 374999,
    "email": "[email protected]",
    "clientId": "APITesting-98c22708",
    "clientSecret": "d7f4f648-2102-4e0a-9108-7a5e94d7dfa7",
    "token": "d51948db-6da6-499e-9af5-bb48767145f5",
    "expiresIn": 31557599,
    "userId": 393473,
    "accountSetUpStatus": "READY",
    "verificationStatus": "Unverified",
    "bankId": 180529,
    "verificationProfile": {
        "reasons": [
            {
                "code": "account_under_review",
                "description": "Payments may be submitted but Veem will not process the payment, until risk reviews are completed"
            }
        ]
    }
}

Please make sure to save id, token and bankId info in your database for future endpoint.

The following table will provide extra information on some of these parameters:

Possible response errors

When opening a Veem account, one might encounter some errors depending on the information provided. Here are some examples of the possible status codes one might encounter when using Veem's Account Creation API:

Account creation is successful, but missing certain info:

Status Code: 201 (Created)

Example response:

{
    "id": 374999,
    "email": "[email protected]",
    "clientId": "APITesting-98c22708",
    "clientSecret": "d7f4f648-2102-4e0a-9108-7a5e94d7dfa7",
    "token": "d51948db-6da6-499e-9af5-bb48767145f5",
    "expiresIn": 31557599,
    "userId": 393473,
    "accountSetUpStatus": "MISSING_INFORMATION",
    "verificationStatus": "Unverified",
    "missingInformation": [
        "Bank account info is missing"
    ]
}

Bad Request

Status Code: 400 (Bad Request)

Example Response:

{
    "fieldErrors": [
        {
            "field": "businessEntity",
            "message": "must not be blank"
        },
        {
            "field": "industry",
            "message": "must not be blank"
        },
        {
            "field": "phoneNumber",
            "message": "must not be blank"
        },
        {
            "field": "taxIdNumber",
            "message": "must not be blank"
        },
        {
            "field": "businessName",
            "message": "must not be blank"
        },
        {
            "field": "address",
            "message": "must not be null"
        }
    ]
}

Note: When partially omitting information for bankAccount fields (e.g. bankNumber and routingNumber), but providing the rest, one can expect a response similar to the following:

{
    "id": 375005,
    "email": "[email protected]",
    "clientId": "APITesting-6608e0f5",
    "clientSecret": "3ba6f018-792b-4308-9a17-f0ec27e3994d",
    "token": "f7f5c040-b249-4ea1-8185-e7e85b709c51",
    "expiresIn": 31557599,
    "userId": 393479,
    "accountSetUpStatus": "MISSING_INFORMATION",
    "verificationStatus": "Unverified",
    "missingInformation": [
        "Bank account info is missing: 400 BAD_REQUEST \"Missing bank account fields: [routingNumber, bankAccountNumber]\""
    ],
    "verificationProfile": {
        "reasons": [
            {
                "code": "account_under_review",
                "description": "Payments may be submitted but Veem will not process the payment, until risk reviews are completed"
            }
        ]
    }
}

Internal Server Error

Status Code: 500 (Internal Server Error)

Note: This is a generic error code that can occur for any number of reasons. If these errors occur, one must contact Veem support to have it ratified

Example Responses:

Maximum Characters exceeded:

{
    "timestamp": 1735673162023,
    "status": 500,
    "error": "Internal Server Error",
    "message": "Failed to call internal service",
    "path": "/veem/v1.2/account"
}

Reuse of the same X-REQUEST-ID:

{
    "timestamp": 1735673703326,
    "status": 500,
    "error": "Internal Server Error",
    "message": "X-REQUEST-ID already has been used: 48855846-628d-4177-b071-80332a116f0a. Use a new one",
    "path": "/veem/v1.2/account"
}

Entering incorrect business entity with account type:

{
    "timestamp": 1735674059130,
    "status": 500,
    "error": "Internal Server Error",
    "message": "Invalid business type",
    "path": "/veem/v1.2/account"
}

Generic:

{
    "timestamp": 1705605916361,
    "status": 500,
    "error": "Internal Server Error",
    "message": "Unexpected error has occurred. We apologize for the inconvenience",
    "path": "/veem/v1.2/account"
}

Edit account

This endpoint is used to edit specific parameters in an existing Veem account. The endpoint is as follows:

PATCH https://sandbox-api.veem.com/veem/v1.2/account/{accountId}

Headers

There are 2 headers necessary for the use of this endpoint:

• X-request-id: This is a number unique to the current API request, and follows the UUID format. Reusing this header without changing the value will result in a 500 (Internal Server Error) status. An example X-request-id is as follows:

48855846-628d-4177-b071-80332a116f0a

• Authorization: This header holds the bearer token required to use Veem's public API. Failure to use a valid bearer token will result in a 404 (Not Found) status. An example of a valid token is as follows:

Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

Request Payload

When editing an account, one must follow the format as shown in the following example:

{
    "subIndustry": "Software",
    "firstName": "New First Name",
    "lastName": "New Last Name",
    "dialCode": "+1",
    "phoneNumber": "6612861111",
    "taxIdNumber": "54-3216789",
    "businessName": "New Business Name",
    "industry": "Software, IT and Telecommunications",
    "address": {
        "street": "Address line 1",
        "streetSecondary": "Address line 1",
        "city": "San Francisco",
        "postalCode": "94116",
        "province": "CA"
    }
}

Request Parameters

The following table contains detailed information on the payload's parameters, such as the parameter name, formatting (if applicable), and size of the parameter

Note: None of these fields are mandatory. You are free to choose which fields you want to modify in an account

For extra information, you can find some resources here:
Dial codes: https://en.wikipedia.org/wiki/List_of_country_calling_codes
Subindustry list: placeholder

Response Payload

Once a valid request has been sent, a response payload of this format should be expected:

Get account

Once a Veem account has been opened, you can fetch the account's information using the account id that you received from the Open Account endpoint. The endpoint is as follows:

GET https://sandbox-api.veem.com/veem/v1.2/account/{accountId}

Note: If coming directly from the Open Account flow, use the value from the id field and not from the userId field

Headers

There are 2 headers necessary for the use of this endpoint:

• X-request-id: This is a number unique to the current API request, and follows the UUID format. Reusing this header without changing the value will result in a 500 (Internal Server Error) status. An example X-request-id is as follows:

48855846-628d-4177-b071-80332a116f0a

• Authorization: This header holds the bearer token required to use Veem's public API. Failure to use a valid bearer token will result in a 404 (Not Found) status. An example of a valid token is as follows:

Bearer d49e7fd4-2600-4dd4-a572-118668febbe7

Response Payload

When using the endpoint, one can expect to receive a response following the format below:

{
    "id": 374999,
    "email": "[email protected]",
    "clientId": "APITesting-98c22708",
    "clientSecret": "d7f4f648-2102-4e0a-9108-7a5e94d7dfa7",
    "token": "d51948db-6da6-499e-9af5-bb48767145f5"
    "accountSetUpStatus": "READY",
    "verificationStatus": "Unverified",
}

The following table will provide extra information on some of these parameters:

To get account status you can also use Webhook, check this page