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

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

> PATCH /v1/contacts/{contactId} updates a contact's display name, emails, phone, address, or net terms. Only payee contacts support most fields.

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.

```http theme={null}
Authorization: Bearer <token>
```

## Path Parameters

<ParamField path="contactId" type="string" required>
  The unique identifier of the contact to update.
</ParamField>

## Request Body

<ParamField body="displayName" type="string">
  Updated display name for the contact. Applies to both `payee` and `business`-type contacts.
</ParamField>

<ParamField body="emails" type="string[]">
  Updated list of email addresses. Maximum 5 addresses. **Payee contacts only.**

  <Warning>
    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.
  </Warning>
</ParamField>

<ParamField body="phone" type="string">
  Updated phone number. **Payee contacts only.**
</ParamField>

<ParamField body="address" type="object">
  Updated mailing address. **Payee contacts only.**

  <Expandable title="address fields">
    <ParamField body="streetOne" type="string" required>
      Primary street address line.
    </ParamField>

    <ParamField body="streetTwo" type="string">
      Secondary street address line (e.g., suite or unit number). Optional.
    </ParamField>

    <ParamField body="city" type="string" required>
      City name.
    </ParamField>

    <ParamField body="stateCode" type="string" required>
      Two-letter US state code (e.g., `CA`, `NY`).
    </ParamField>

    <ParamField body="zipCode" type="string" required>
      US ZIP code.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="netTerms" type="number">
  Net payment terms in days. Must be `0` or greater. **Payee contacts only.**
</ParamField>

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

## Response

Returns the updated `Contact` object with HTTP status `200 OK`.

<ResponseField name="id" type="string">
  Unique identifier for the contact.
</ResponseField>

<ResponseField name="type" type="string">
  The contact type: `payee` or `business`.
</ResponseField>

<ResponseField name="status" type="string">
  The contact's current status: `active`, `archived`, or `revoked`.
</ResponseField>

<ResponseField name="displayName" type="string | null">
  The updated display name.
</ResponseField>

<ResponseField name="emails" type="string[]">
  The full, updated list of email addresses. Empty for `business`-type contacts.
</ResponseField>

<ResponseField name="phone" type="string | null">
  The updated phone number.
</ResponseField>

<ResponseField name="paymentDirection" type="string">
  Allowed payment direction: `bidirectional`, `can_pay`, `can_be_paid`, or `none`.
</ResponseField>

<ResponseField name="netTerms" type="number | null">
  Updated net payment terms in days, if set.
</ResponseField>

<ResponseField name="bankAccount" type="object | null">
  Summary of the contact's linked bank account.

  <Expandable title="bankAccount fields">
    <ResponseField name="last4" type="string">
      Last four digits of the bank account number.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="taxInfo" type="object | null">
  Tax information for the contact.

  <Expandable title="taxInfo fields">
    <ResponseField name="legalName" type="string | null">
      Legal name associated with the tax ID.
    </ResponseField>

    <ResponseField name="taxIdType" type="string | null">
      Type of tax ID: `ein` or `ssn`.
    </ResponseField>

    <ResponseField name="taxIdMask" type="string | null">
      Last four digits of the tax ID.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="paymentReady" type="boolean">
  Whether this contact can currently receive payments.
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  ISO 8601 timestamp of when the contact was created.
</ResponseField>

<ResponseField name="updatedAt" type="datetime | null">
  ISO 8601 timestamp of this update.
</ResponseField>

<ResponseField name="archivedAt" type="datetime | null">
  ISO 8601 timestamp of archival, if applicable.
</ResponseField>

## Example Request

```bash curl theme={null}
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

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

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