Contacts: Manage Your Vendors and Payees in Cleo Pay

A contact in Cleo Pay represents an entity you can pay or do business with — typically a vendor, supplier, or contractor. Every payment you send is associated with a contact, either directly or through a payable. Contacts store bank account details, tax information, and payment configuration so you can send funds reliably without re-entering details on every transaction.

Contact types

Cleo Pay has two contact types that determine how the contact record is managed:

Type	Description
`payee`	A vendor or payee that your business manages. You supply and control their bank account details and contact information. Most vendor and contractor contacts are `payee` type.
`business`	An independent Cleo Pay business with its own account. Their details are managed on their side. Your organization has a relationship with them on the platform.

When creating a contact via the API, you will typically create payee contacts. The business type is established through the Cleo Pay platform when two businesses connect with each other.

Contact status

Status	Description
`active`	The contact is in good standing and available for payments.
`archived`	The contact has been archived. Archived contacts are no longer available for new payments. The `archivedAt` timestamp records when this happened.
`revoked`	The contact’s access or relationship has been revoked.

Payment direction

The paymentDirection field controls which direction funds can flow between your business and this contact.

Value	Meaning
`bidirectional`	Payments can flow both to and from this contact.
`can_pay`	Your business can send payments to this contact.
`can_be_paid`	This contact can send payments to your business.
`none`	No payment flow is currently configured.

For outbound vendor payments, you need a contact with paymentDirection of can_pay or bidirectional. If the direction is none or can_be_paid, you cannot send payments to that contact.

paymentReady

The paymentReady boolean is a convenience flag that tells you at a glance whether a contact can currently receive a payment. It is true only when all required conditions are met — the contact is active, has a valid bank account on file, and payment direction allows outbound transfers. Always check paymentReady: true before initiating a payment to a contact. If it is false, the payment will enter held status and wait until the contact’s details are complete.

Bank account details

When a contact has a bank account on file, the bankAccount object exposes the last 4 digits for identification purposes. Full account numbers are never returned in any API response.

"bankAccount": {
  "last4": "1234"
}

If no bank account is associated with the contact, bankAccount is null.

Tax information

The taxInfo object stores the contact’s tax identity for 1099 and compliance purposes.

Field	Description
`legalName`	The contact’s legal business or individual name as it appears on tax filings. Nullable.
`taxIdType`	`"ein"` (Employer Identification Number), `"ssn"` (Social Security Number), or `null` if not yet provided.
`taxIdMask`	The last 4 digits of the tax ID only — the full number is never returned. Nullable.

Emails

The emails field is an array of email addresses associated with the contact. This field is populated for payee contacts; for business-type contacts the array is always empty, as their contact details are managed on their own account. Emails are used for notifications and remittance communications.

Phone

The phone field is a string containing the contact’s phone number. For business-type contacts this field is always null, as their details are self-managed.

Net terms

The netTerms field is an integer representing the number of days after invoice issuance that payment is due. For example, netTerms: 30 corresponds to Net 30 payment terms. This value is informational and used when generating payables for this contact.

Duplicate guard

When creating a contact, Cleo Pay checks for existing contacts with the same name or details. If a potential duplicate is detected, the request will fail with an error. To proceed with creating the contact anyway, include "allowDuplicates": true in your request body.

Example contact object

{
  "id": "con_01hq9r2m7tuvwxyz",
  "type": "payee",
  "status": "active",
  "displayName": "Globex Supplies LLC",
  "emails": [
    "billing@globex-supplies.com",
    "ap@globex-supplies.com"
  ],
  "phone": "+1-555-867-5309",
  "paymentDirection": "can_pay",
  "paymentReady": true,
  "netTerms": 30,
  "bankAccount": {
    "last4": "1234"
  },
  "taxInfo": {
    "legalName": "Globex Supplies LLC",
    "taxIdType": "ein",
    "taxIdMask": "7890"
  },
  "createdAt": "2025-01-10T09:00:00Z",
  "updatedAt": "2025-03-01T14:30:00Z",
  "archivedAt": null
}

Next steps

Bank Accounts — understand how your own bank accounts are linked and verified.
Payments — send an ACH payment to a contact.
Payables — create an invoice associated with a contact.

Get Started

Core Concepts

How-To Guides

Reference

Contacts: Manage Your Vendors and Payees in Cleo Pay

Contact types

Contact status

Payment direction

paymentReady

Bank account details

Tax information

Emails

Phone

Net terms

Duplicate guard

Example contact object

Next steps

​Contact types

​Contact status

​Payment direction

​paymentReady

​Bank account details

​Tax information

​Emails

​Phone

​Net terms

​Duplicate guard

​Example contact object

​Next steps

Contact types

Contact status

Payment direction

paymentReady

Bank account details

Tax information

Emails

Phone

Net terms

Duplicate guard

Example contact object

Next steps