> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts: Manage Your Vendors and Payees in Cleo Pay

> Contacts represent vendors and payees in Cleo Pay. Learn about contact types, statuses, payment direction, tax info, and the paymentReady flag.

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.                |

<Info>
  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.
</Info>

## 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.             |

<Tip>
  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.
</Tip>

## 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.

```json theme={null}
"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

```json theme={null}
{
  "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](/concepts/bank-accounts) — understand how your own bank accounts are linked and verified.
* [Payments](/concepts/payments) — send an ACH payment to a contact.
* [Payables](/concepts/payables) — create an invoice associated with a contact.