Update Contact — PATCH /v1/contacts/{contactId} Reference

Use this endpoint to update an existing contact. You can modify the display name on any contact type. Emails, phone, address, and net terms are only supported for payee-type contacts. All fields are optional — include only the fields you want to change.

Base URL

PATCH https://api.cleo-pay.com/v1/contacts/{contactId}

Authentication

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

Authorization: Bearer <token>

Path Parameters

string

required

The unique identifier of the contact to update.

Request Body

string

Updated display name for the contact. Applies to both payee and business-type contacts.

string[]

Updated list of email addresses. Maximum 5 addresses. Payee contacts only.

This field replaces all existing email addresses on the contact. If you want to keep existing emails, include them in the array alongside any new addresses.

string

Updated phone number. Payee contacts only.

object

Updated mailing address. Payee contacts only.

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.

number

Net payment terms in days. Must be 0 or greater. Payee contacts only.

The emails, phone, address, and netTerms fields are only applicable to payee-type contacts. Sending these fields for a business-type contact will result in an error.

Response

Returns the updated Contact object with HTTP status 200 OK.

string

Unique identifier for the contact.

string

The contact type: payee or business.

string

The contact’s current status: active, archived, or revoked.

string | null

The updated display name.

string[]

The full, updated list of email addresses. Empty for business-type contacts.

string | null

The updated phone number.

string

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

number | null

Updated net payment terms in days, if set.

object | null

Summary of the contact’s linked bank account.

Show bankAccount fields

string

Last four digits of the bank account number.

object | null

Tax information for the contact.

Show taxInfo fields

string | null

Legal name associated with the tax ID.

string | null

Type of tax ID: ein or ssn.

string | null

Last four digits of the tax ID.

boolean

Whether this contact can currently receive payments.

datetime

ISO 8601 timestamp of when the contact was created.

datetime | null

ISO 8601 timestamp of this update.

datetime | null

ISO 8601 timestamp of archival, if applicable.

Example Request

curl

curl --request PATCH \
  --url "https://api.cleo-pay.com/v1/contacts/cnt_01hq1z2k3m4n5p6q7r8s9t0u" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "displayName": "Acme Supplies LLC (Updated)",
    "emails": ["billing@acmesupplies.com", "ap@acmesupplies.com"],
    "netTerms": 45
  }'

Example Response

200

{
  "id": "cnt_01hq1z2k3m4n5p6q7r8s9t0u",
  "type": "payee",
  "status": "active",
  "displayName": "Acme Supplies LLC (Updated)",
  "emails": ["billing@acmesupplies.com", "ap@acmesupplies.com"],
  "phone": "+15550001234",
  "paymentDirection": "can_be_paid",
  "netTerms": 45,
  "bankAccount": {
    "last4": "7890"
  },
  "taxInfo": {
    "legalName": "Acme Supplies LLC",
    "taxIdType": "ein",
    "taxIdMask": "6789"
  },
  "paymentReady": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-04-10T09:15:00Z",
  "archivedAt": null
}

When updating emails, always include the complete desired list. For example, if the contact currently has one email and you want to add a second, pass both addresses in the emails array — omitting the original will remove it.

Payables

Bank Accounts

Contacts

Payments

Update Contact — PATCH /v1/contacts/{contactId} Reference

Base URL

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response

​Base URL

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

Base URL

Authentication

Path Parameters

Request Body

Response

Example Request

Example Response