The Contacts API creates and retrieves payees and vendors associated with your Veem account. Create a single contact, list contacts with optional filters, retrieve a contact by ID, or create multiple contacts in a batch.

Authorization

OAuth2 token is required in the Authorization header.

📘
Headers
Three headers are required to use this endpoint.

Name Type Required Description
Authorization string Yes Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: Bearer c047594b-082c-4da1-be89-08fe3770f4b3.
See Get Access Token section to generate your Bearer token.
X-Request-Id string Yes This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows: 48855846-628d-4177-b071-80332a116f0a
Content-Type string Yes The content type of the request. Must be application/json

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: `Bearer c047594b-082c-4da1-be89-08fe3770f4b3`. See Get Access Token section to generate your Bearer token.
`X-Request-Id`	string	Yes	This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows: `48855846-628d-4177-b071-80332a116f0a`
`Content-Type`	string	Yes	The content type of the request. Must be `application/json`

Contact Endpoints

Veem's API provides a number of endpoints that you use to create and retrieve contacts.

Use the following base URL to access the endpoints in the sandbox environment.

POST https://sandbox-api.veem.com/veem/

Create Contact

Create a contact for your account. Send a POST request with the contact's identity details. When type is Business, include businessName. Optionally include businessAddress and bankAccount when you already have that information.

POST /v1.2/contacts

Create Contact (Business)

{
  "email": "[email protected]",
  "firstName": "Thomas",
  "lastName": "Scott",
  "isoCountryCode": "US",
  "phoneDialCode": "+1",
  "phoneNumber": "4152306359",
  "type": "Business",
  "businessName": "API Testing",
  "externalBusinessId": 1001,
  "businessAddress": {
    "line1": "166 Battery St",
    "line2": "Suite 101",
    "city": "San Francisco",
    "postalCode": "94111",
    "stateProvince": "CA"
  },
  "bankAccount": {
    "isoCountryCode": "US",
    "bankName": "Bank of America",
    "currencyCode": "USD",
    "bankAccountNumber": "12345678",
    "routingNumber": "026009593"
  }
}

{
  "id": 88421,
  "contactAccountId": 375012,
  "email": "[email protected]",
  "firstName": "Thomas",
  "lastName": "Scott",
  "businessName": "API Testing",
  "isoCountryCode": "US",
  "dialCode": "+1",
  "phoneNumber": "4152306359",
  "bank": {
    "isoCountryCode": "US",
    "bankName": "Bank of America",
    "currencyCode": "USD",
    "bankAccountNumber": "12345678",
    "routingNumber": "026009593"
  }
}

Create Contact (Personal)

{
  "email": "[email protected]",
  "firstName": "Emma",
  "lastName": "Johnson",
  "isoCountryCode": "US",
  "phoneDialCode": "+1",
  "phoneNumber": "2102102101",
  "type": "Personal"
}

{
  "id": 88422,
  "contactAccountId": 375013,
  "email": "[email protected]",
  "firstName": "Emma",
  "lastName": "Johnson",
  "businessName": "",
  "isoCountryCode": "US",
  "dialCode": "+1",
  "phoneNumber": "2102102101"
}

The API returns the created contact, including the contact id. Use this ID to retrieve the contact later. contactAccountId is the Veem account ID associated with the contact.

Veem uses the E.164 standard for phone numbers.

Parameter	Mandatory	Format/Values	Size/Type
email	Yes	Contact email address	string
firstName	Yes	Contact first name	string
lastName	Yes	Contact last name	string
isoCountryCode	Yes	Contact 2-letter country code. ISO 3166-1 alpha-2, e.g. `US`	2 characters
phoneNumber	Yes	Contact phone number	string
type	Yes	Contact type. One of `Incomplete`, `Business`, `Personal`	string
phoneDialCode	No	Contact phone dial code, e.g. `+1`	string
businessName	Conditional	Contact business name. Required when `type` is `Business`	string
externalBusinessId	No	Custom identifier for this contact	integer
businessAddress	No	Contact business address	object
businessAddress.line1	Conditional	Address line 1. Required when `businessAddress` is included	string
businessAddress.line2	Conditional	Address line 2. Required when `businessAddress` is included	string
businessAddress.city	Conditional	City. Required when `businessAddress` is included	string
businessAddress.postalCode	Conditional	Postal code. Required when `businessAddress` is included	string
businessAddress.stateProvince	Conditional	State or province. Required when `businessAddress` is included	string
bankAccount	No	Contact bank account. Bank fields required for the contact's country match the Bank Account endpoint.	object
bankAccount.isoCountryCode	No	Bank country code. ISO 3166-1 alpha-2, e.g. `US`	2 characters
bankAccount.bankName	No	Bank name	string
bankAccount.currencyCode	No	Bank account currency. ISO 4217, e.g. `USD`	3 characters
bankAccount.bankAccountNumber	No	Bank account number	string
bankAccount.routingNumber	No	Routing number. Required for banks in certain countries, e.g. United States	string
bankAccount.swiftBic	No	SWIFT/BIC code. Required for banks in certain countries	string
bankAccount.iban	No	IBAN. Required for banks in certain countries	string

Response fields

Field	Description
id	Contact ID. Use this value in Get Contact by ID
contactAccountId	Veem account ID associated with the contact
email	Contact email
firstName	Contact first name
lastName	Contact last name
businessName	Contact business name
isoCountryCode	Contact 2-letter country code
dialCode	Contact phone dial code
phoneNumber	Contact phone number
batchItemId	Batch item ID, when the contact was created in a contacts batch
bank	Contact bank account details, when a bank account was provided
extraInfo	Additional contact information

Get Contacts

List contacts for your account. Send a GET request. Filter by email, first name, last name, business name, batch ID, or batch item IDs. The API returns a page of matching contacts.

GET /v1.2/contacts

Example with filters:

GET /v1.2/[email protected]&pageNumber=0&pageSize=20

[
  {
    "id": 88421,
    "contactAccountId": 375012,
    "email": "[email protected]",
    "firstName": "Thomas",
    "lastName": "Scott",
    "businessName": "API Testing",
    "isoCountryCode": "US",
    "dialCode": "+1",
    "phoneNumber": "4152306359"
  }
]

Query parameters

Parameter	Mandatory	Format/Values	Size/Type
email	No	Filter by contact email address	string
firstName	No	Filter by contact first name	string
lastName	No	Filter by contact last name	string
businessName	No	Filter by contact business name	string
batchId	No	Filter by the batch ID returned from Create Contacts	integer
batchItemIds	No	Filter by batch item IDs from Create Contacts. Repeat the parameter for each ID	array of integer
pageNumber	No	Page number. Default: `0`	integer
pageSize	No	Number of contacts per page. Default: `20`	integer

The API returns an array of contact objects. Response fields match Create Contact.

After you create contacts in a batch, filter by batchId to retrieve the contacts produced by that batch.

Get Contact by ID

Retrieve a contact by ID. Send a GET request with the contact ID returned from Create Contact or Get Contacts.

GET /v1.2/contacts/{contactId}

{
  "id": 88421,
  "contactAccountId": 375012,
  "email": "[email protected]",
  "firstName": "Thomas",
  "lastName": "Scott",
  "businessName": "API Testing",
  "isoCountryCode": "US",
  "dialCode": "+1",
  "phoneNumber": "4152306359",
  "bank": {
    "isoCountryCode": "US",
    "bankName": "Bank of America",
    "currencyCode": "USD",
    "bankAccountNumber": "12345678",
    "routingNumber": "026009593"
  }
}

Path parameters

Parameter	Mandatory	Format/Values	Size/Type
contactId	Yes	Contact ID returned when the contact was created	integer

Response fields match Create Contact.

Create Contacts

Create multiple contacts in a batch. Send a POST request with an array of contact objects. Each item requires a unique batchItemId within the batch. The API validates the request and starts processing.

POST /v1.2/contacts/batch

Set includeItems=true to include batch items in the response. The default is false.

POST /v1.2/contacts/batch?includeItems=true

[
  {
    "batchItemId": 1,
    "email": "[email protected]",
    "firstName": "Thomas",
    "lastName": "Scott",
    "isoCountryCode": "US",
    "phoneDialCode": "+1",
    "phoneNumber": "4152306359",
    "type": "Business",
    "businessName": "API Testing",
    "businessAddress": {
      "line1": "166 Battery St",
      "line2": "Suite 101",
      "city": "San Francisco",
      "postalCode": "94111",
      "stateProvince": "CA"
    },
    "bankAccount": {
      "isoCountryCode": "US",
      "bankName": "Bank of America",
      "currencyCode": "USD",
      "bankAccountNumber": "12345678",
      "routingNumber": "026009593"
    }
  },
  {
    "batchItemId": 2,
    "email": "[email protected]",
    "firstName": "Emma",
    "lastName": "Johnson",
    "isoCountryCode": "US",
    "phoneDialCode": "+1",
    "phoneNumber": "2102102101",
    "type": "Personal"
  }
]

{
  "batchId": 18452,
  "hasErrors": false,
  "processedItems": 0,
  "status": "InProgress",
  "totalItems": 2
}

The API returns a batchId. Use Get Contact Batch to check processing status. When processing completes, use Get Contacts with batchId to retrieve the created contacts.

Each batch item uses the same fields as Create Contact, plus batchItemId.

Parameter	Mandatory	Format/Values	Size/Type
batchItemId	Yes	Unique identifier for this item within the batch	integer
includeItems	No	Query parameter. When `true`, the API includes `batchItems` in the response. Default: `false`	boolean

Response fields

Field	Description
batchId	Batch ID. Use this value in Get Contact Batch
status	Current batch status
totalItems	Number of contacts in the request
processedItems	Number of contacts processed so far
hasErrors	`true` when one or more batch items failed
batchItems	Per-item results, when `includeItems` is `true`

Get Contact Batch

Retrieve the status of a contact creation batch. Send a GET request with the batchId returned from Create Contacts. Poll this endpoint until the batch finishes processing.

GET /v1.2/contacts/batch/{batchId}

includeItems defaults to true. Set includeItems=false to return batch summary fields only.

GET /v1.2/contacts/batch/{batchId}?includeItems=true

{
  "batchId": 18452,
  "batchItems": [
    {
      "batchItemId": 1,
      "accountId": 375012,
      "status": "Completed"
    },
    {
      "batchItemId": 2,
      "accountId": 375013,
      "status": "Completed"
    }
  ],
  "hasErrors": false,
  "processedItems": 2,
  "status": "Completed",
  "totalItems": 2
}

Path and query parameters

Parameter	Mandatory	Format/Values	Size/Type
batchId	Yes	Batch ID returned from Create Contacts	integer
includeItems	No	When `true`, the API includes `batchItems` in the response. Default: `true`	boolean

Response fields

Field	Description
batchId	Batch ID
status	Current batch status
totalItems	Number of contacts in the batch
processedItems	Number of contacts processed so far
hasErrors	`true` when one or more batch items failed
batchItems	Per-item results, when `includeItems` is `true`
batchItems.batchItemId	Batch item ID from the create request
batchItems.accountId	Veem account ID created for the contact
batchItems.status	Status of this batch item
batchItems.errorInfo	Error details when this batch item failed. Includes `code`, `error`, `message`, and `timestamp`

When a batch item fails, hasErrors is true and that item includes errorInfo.