# Create or update a customer contact by email or phone

```http
POST https://secure.yoprint.com/v1/api/store/{team_slug}/customer/{hash_id}/contact/upsert
```

- API version: v1
- Operation ID: `v1_public_customer_contact_upsert`
- Section: Customers › [Customer contacts](https://developer.yoprint.com/reference/customer-contacts.md)
- Web page: https://developer.yoprint.com/reference/customer-contacts/v1-customer-contact-upsert/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Updates the customer's contact that has this `email` or `phone`, or adds a new contact.

With `perform_upsert: true` YoPrint looks among the customer's live contacts for one whose `email` equals yours or whose `phone` equals yours, and updates the first it finds with the fields you send. Otherwise, or with `perform_upsert: false`, it adds a new contact (primary only when the customer has no other live contact). Returns the contact.

## Permission

Any member of the team.

## Business rules

- `is_external` and `external_type` are ignored: sending them (for example a value you read back) is not refused and changes nothing. Only the Shopify sync sets them.
- With `perform_upsert: true`, send `email` or `phone`. With neither, the customer's first contact is updated.
- A matched contact synced from Shopify is refused (422 "Shopify-managed customer contacts are read-only. Manage changes from Shopify.").
- Customers synced from Shopify are read-only here: changes are refused with 422 `validation_error` "External customers are read-only. Manage changes from Shopify." System customers (`is_system: true`) are refused the same way ("System customer cannot be modified or deleted.").
- On a live customer (not a system or Shopify customer) a contact's email is saved trimmed and in lower case, and two live contacts of the customer can't have the same email (compared the same way). Other customers may use the same email.
- This operation can't send `portal_email_scope` or `portal_reconnect_confirmed`. When it changes the email of a matched contact that gives someone Customer Portal access, and the change needs either, it answers 409: make the change with Update a customer contact.

## Side effects

- Sends `customer_contact.updated` for a match, or `customer_contact.created` for a new contact.
- When the contact's email already belongs to a Customer Portal account on your team that can't open this customer yet, saving the contact gives that account access to this customer (active when the account is set up with a verified email or a password, invited otherwise). No email is sent.
- A matched contact whose email changes moves its Customer Portal access as Update a customer contact describes, with `portal_email_scope` `all_customers`.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `hash_id` (string, required): The customer's id (`id` from List customers or Create a customer). A hash id from an earlier answer; unique keys and document numbers (such as `PO0042`) don't work here. Example `EDhVUaC6jbLbed`.

## Request body

Content type `application/json`, required.

Fields:

- `perform_upsert` (boolean, required): True to match by `email` or `phone` first. False always adds.
- `default_receive_sms` (boolean, optional)
- `email` (string (email), optional): Matched exactly.
- `fax` (string, optional): Checked as a real number for `fax_country`.
- `fax_country` (string, optional)
- `first_name` (string, optional): Not required here, but send it when the contact may be new.
- `is_primary` (boolean, optional): Not used. Use Set the primary contact.
- `last_name` (string, optional): The contact's last name.
- `phone` (string, optional): Matched exactly as stored. Send `phone_country` with it.
- `phone_country` (string, optional): Two-letter country code of `phone`, such as `US`. Required with `phone`.
- `send_invoice` (boolean, optional): Stored with the contact and returned as `send_invoice`.

### Example request

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed/contact/upsert' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alex@example.com",
    "first_name": "Alex",
    "last_name": "Rivera",
    "perform_upsert": true,
    "send_invoice": true
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required)
  - `created_at` (string (date-time), required)
  - `first_name` (string | null, required)
  - `id` (string, required)
  - `is_primary` (boolean, required)
  - `trashed` (boolean, required): True when the contact is deleted.
  - `updated_at` (string (date-time), required)
  - `customer_id` (string, optional): Customer contacts only.
  - `default_receive_sms` (boolean, optional)
  - `email` (string | null, optional)
  - `external_type` (string | null, optional)
  - `fax` (string | null, optional)
  - `fax_country` (string | null, optional)
  - `is_external` (boolean, optional): True for a contact synced from Shopify; such contacts are read-only.
  - `last_name` (string | null, optional)
  - `phone` (string | null, optional)
  - `phone_country` (string | null, optional)
  - `send_invoice` (boolean, optional): Customer contacts only.
  - `vendor_id` (string, optional): Vendor contacts only.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "created_at": "2026-11-01T09:00:00+00:00",
    "customer_id": "V4keXwwxMQyXw7",
    "default_receive_sms": false,
    "email": "alex@example.com",
    "external_type": null,
    "fax": null,
    "fax_country": null,
    "first_name": "Alex",
    "id": "cBoKHftCid2dDD",
    "is_external": false,
    "is_primary": true,
    "last_name": "Rivera",
    "phone": "+1 201 555 0123",
    "phone_country": "US",
    "send_invoice": true,
    "trashed": false,
    "updated_at": "2026-11-01T09:00:00+00:00"
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: The change moves portal access on a customer your role can't update: you need Manage Customers "Manage All", or "Manage Assigned to User" and to be assigned to every customer the change covers. This 403 has a short body, `{"message": "You need permission to update every linked customer."}`. Fix: Ask a member who can update those customers, or send `portal_email_scope: this_customer`.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
  - When: No customer with this id in the team. Deleted customers are found here, so this also works on a deleted customer. `error.code` is null and `error.message` names the record type. Fix: Check the id.
- `409`
  - When: Another live contact of this customer already has this email, ignoring case and surrounding spaces (`error.code` `customer_portal_duplicate_contact_email`, "This customer already has a contact with that email. Edit the existing contact or use a different email."). Fix: Update the existing contact instead, or use another email.
  - When: The matched contact's new email needs a choice this operation can't send (`error.code` `customer_portal_email_scope_required` or `customer_portal_email_reconnect_required`), or the account on the new email is unavailable (`customer_portal_account_unavailable`). Fix: Change the email with Update a customer contact, sending `portal_email_scope` or `portal_reconnect_confirmed`.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: `perform_upsert` is missing, or a phone is not valid for its country. `error.code` is `validation_failed`. Fix: Send `perform_upsert`, and `phone_country` with `phone`.
  - When: On a live customer, the email is longer than 191 characters or is not a valid address (`error.code` `customer_portal_email_invalid`, "Enter a valid email address using supported characters."). Fix: Send a valid email of at most 191 characters.
  - When: The customer comes from Shopify, or is a system customer (`error.code` `validation_error`, with the reason in `error.message`). Fix: Change Shopify customers in Shopify. System customers cannot be changed.

## Related

- [Add a contact to a customer](https://developer.yoprint.com/reference/customer-contacts/v1-customer-contact-store.md): `POST /v1/api/store/{team_slug}/customer/{hash_id}/contact`
- [Create or update a customer by contact](https://developer.yoprint.com/reference/customers/v1-customer-upsert.md): `POST /v1/api/store/{team_slug}/customer/upsert`