Create Contact — POST /v1/contacts API Reference

Use this endpoint to create a new contact in your account. Contacts can represent either a payee (a vendor you manage) or a business (an independent Cleo business). To make a contact payment-ready at creation time, include bankAccount and taxInfo in the request body.

Base URL

POST https://api.cleo-pay.com/v1/contacts

Authentication

All requests must include a Bearer token in the Authorization header.

Authorization: Bearer <token>

Request Body

string

required

The display name for the contact. This is the primary identifier shown in the Cleo Pay dashboard.

string[]

List of email addresses for the contact. Maximum 5 addresses. Only applicable to payee-type contacts — this field is ignored for business-type contacts.

string

Phone number for the contact, in any standard format. Optional.

object

Mailing address for the contact. Optional.

Show address fields

string

required

Primary street address line.

string

Secondary street address line (e.g., suite or unit number). Optional.

string

required

City name.

string

required

Two-letter US state code (e.g., CA, NY).

string

required

US ZIP code.

object

Bank account details for the contact. Providing this field makes the contact eligible to receive ACH payments. All fields within this object are write-only — they are never returned in API responses. Only last4 is returned after creation.

Show bankAccount fields

string

Full bank account number. Write-only.

string

Nine-digit ABA routing number. Write-only.

string

Type of bank account. Accepted values: checking, savings.

object

Tax identification information for the contact. Providing this field is required for 1099 reporting. The full tax ID is write-only — only the last four digits are returned as taxIdMask after creation.

Show taxInfo fields

string

required

Legal name as it appears on tax filings.

string

required

Type of tax ID. Accepted values: ein (Employer Identification Number), ssn (Social Security Number).

string

required

Full tax identification number. Write-only — only the last four digits are returned as taxIdMask in all subsequent responses.

boolean

default:"false"

When false (the default), Cleo Pay checks for an existing contact with a matching name or email and returns an error if a potential duplicate is found. Set this to true to bypass the duplicate-contact guard and force creation.

The bankAccount.accountNumber, bankAccount.routingNumber, and taxInfo.taxId fields are strictly write-only. They are accepted on creation but never returned in any API response. Use bankAccount.last4 and taxInfo.taxIdMask to confirm the values that were saved.

Response

Returns the created Contact object with HTTP status 201 Created.

string

Unique identifier for the newly created contact.

string

The contact type: payee or business.

string

Initial status of the contact. Newly created contacts have a status of active.

string | null

The display name provided in the request.

string[]

Email addresses associated with the contact. Empty for business-type contacts.

string | null

Phone number, if provided.

string

Allowed payment direction: bidirectional, can_pay, can_be_paid, or none.

number | null

Net payment terms in days, if configured.

object | null

Summary of the linked bank account.

Show bankAccount fields

string

Last four digits of the bank account number.

object | null

Tax information summary.

Show taxInfo fields

string | null

Legal name provided at creation.

string | null

Type of tax ID: ein or ssn.

string | null

Last four digits of the tax ID. The full tax ID is never returned.

boolean

Whether the contact can currently receive payments. This is true when a valid bank account is linked.

datetime

ISO 8601 timestamp of contact creation.

datetime | null

ISO 8601 timestamp of the most recent update. null immediately after creation.

datetime | null

ISO 8601 timestamp of archival. null for newly created contacts.

Example Request

curl

curl --request POST \
  --url "https://api.cleo-pay.com/v1/contacts" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "displayName": "Acme Supplies LLC",
    "emails": ["billing@acmesupplies.com"],
    "phone": "+15550001234",
    "address": {
      "streetOne": "123 Commerce Drive",
      "city": "Austin",
      "stateCode": "TX",
      "zipCode": "78701"
    },
    "bankAccount": {
      "accountNumber": "123456789012",
      "routingNumber": "021000021",
      "accountType": "checking"
    },
    "taxInfo": {
      "legalName": "Acme Supplies LLC",
      "taxIdType": "ein",
      "taxId": "12-3456789"
    },
    "allowDuplicates": false
  }'

Example Response

201

{
  "id": "cnt_01hq1z2k3m4n5p6q7r8s9t0u",
  "type": "payee",
  "status": "active",
  "displayName": "Acme Supplies LLC",
  "emails": ["billing@acmesupplies.com"],
  "phone": "+15550001234",
  "paymentDirection": "can_be_paid",
  "netTerms": null,
  "bankAccount": {
    "last4": "2012"
  },
  "taxInfo": {
    "legalName": "Acme Supplies LLC",
    "taxIdType": "ein",
    "taxIdMask": "6789"
  },
  "paymentReady": true,
  "createdAt": "2024-04-10T12:00:00Z",
  "updatedAt": null,
  "archivedAt": null
}

To add a contact without bank or tax details now and complete them later, omit bankAccount and taxInfo from the request. You can update the contact’s display name, emails, phone, address, and net terms via a subsequent PATCH /v1/contacts/{contactId} call.

Payables

Bank Accounts

Contacts

Payments

Create Contact — POST /v1/contacts API Reference

Base URL

Authentication

Request Body

Response

Example Request

Example Response

​Base URL

​Authentication

​Request Body

​Response

​Example Request

​Example Response

Base URL

Authentication

Request Body

Response

Example Request

Example Response