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

contactId

string

required

The unique identifier of the contact to update.

Request Body

displayName

string

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

emails

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.

phone

string

Updated phone number. Payee contacts only.

address

object

Updated mailing address. Payee contacts only.

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.

netTerms

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.

type

string

The contact type: payee or business.

status

string

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

displayName

string | null

The updated display name.

emails

string[]

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

phone

string | null

The updated phone number.

paymentDirection

string

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

netTerms

number | null

Updated net payment terms in days, if set.

bankAccount

object | null

Summary of the contact’s linked bank account.

Show bankAccount fields

last4

string

Last four digits of the bank account number.

taxInfo

object | null

Tax information for the contact.

Show taxInfo fields

legalName

string | null

Legal name associated with the tax ID.

taxIdType

string | null

Type of tax ID: ein or ssn.

taxIdMask

string | null

Last four digits of the tax ID.

paymentReady

boolean

Whether this contact can currently receive payments.

createdAt

datetime

ISO 8601 timestamp of when the contact was created.

updatedAt

datetime | null

ISO 8601 timestamp of this update.

archivedAt

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