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

displayName

string

required

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

emails

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.

phone

string

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

address

object

Mailing address for the contact. Optional.

Show address fields

streetOne

string

required

Primary street address line.

streetTwo

string

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

city

string

required

City name.

stateCode

string

required

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

zipCode

string

required

US ZIP code.

bankAccount

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

accountNumber

string

Full bank account number. Write-only.

routingNumber

string

Nine-digit ABA routing number. Write-only.

accountType

string

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

taxInfo

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

legalName

string

required

Legal name as it appears on tax filings.

taxIdType

string

required

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

taxId

string

required

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

allowDuplicates

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.

type

string

The contact type: payee or business.

status

string

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

displayName

string | null

The display name provided in the request.

emails

string[]

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

phone

string | null

Phone number, if provided.

paymentDirection

string

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

netTerms

number | null

Net payment terms in days, if configured.

bankAccount

object | null

Summary of the linked bank account.

Show bankAccount fields

last4

string

Last four digits of the bank account number.

taxInfo

object | null

Tax information summary.

Show taxInfo fields

legalName

string | null

Legal name provided at creation.

taxIdType

string | null

Type of tax ID: ein or ssn.

taxIdMask

string | null

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

paymentReady

boolean

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

createdAt

datetime

ISO 8601 timestamp of contact creation.

updatedAt

datetime | null

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

archivedAt

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