# Add a contact to a customer

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

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

Adds a contact to the customer and returns it.

`is_primary` is required in the request body, but its value is ignored: the new contact becomes primary only if the customer has no other live contacts. If the customer already has live contacts, the new contact is saved with `is_primary: false`. To make this contact primary, call Set the primary contact afterwards.

## Permission

Needs the Manage Customers permission ("Manage All" or "Manage Assigned to User"). Whether the customer is assigned to you is not checked.

## 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.
- A phone needs `phone_country` and must be a valid number for it; the same goes for `fax` and `fax_country`.
- 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. Phones need not be unique.
- Works on a deleted customer too: the contact is added to it, and its email is neither changed nor checked against the other contacts.

## Side effects

- Sends the `customer_contact.created` webhook.
- 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.

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

- `first_name` (string, required): Required. The contact's first name.
- `is_primary` (boolean, required): Required, but its value is ignored: the contact becomes primary only if the customer has no other live contacts. To make it primary, use Set the primary contact.
- `send_invoice` (boolean, required): Required. Stored with the contact and returned as `send_invoice`.
- `default_receive_sms` (boolean, optional): When this contact is set on a sales order, it receives text messages about the order by default. Saved as sent; defaults to false.
- `email` (string (email), optional): The contact's email. Messages you send to this contact go here.
- `fax` (string, optional): Checked as a real number for `fax_country`.
- `fax_country` (string, optional): Two-letter country code of `fax`.
- `last_name` (string, optional): The contact's last name.
- `phone` (string, optional): Checked as a real number for `phone_country`. Send `phone_country` with it.
- `phone_country` (string, optional): Two-letter country code of `phone`, such as `US`. Required with `phone`.

### Example request

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

## 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-03T09:00:00+00:00",
    "customer_id": "V4keXwwxMQyXw7",
    "default_receive_sms": false,
    "email": "jordan@example.com",
    "external_type": null,
    "fax": null,
    "fax_country": null,
    "first_name": "Jordan",
    "id": "z00Q1u9fDyYcfw",
    "is_external": false,
    "is_primary": false,
    "last_name": "Lee",
    "phone": null,
    "phone_country": null,
    "send_invoice": false,
    "trashed": false,
    "updated_at": "2026-11-03T09: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: Your role has no Manage Customers permission. This 403 has a short body, `{"message": "Insufficient Permission"}`, with no `success` or `error`. Fix: Ask a team owner to give your role Manage Customers.
- `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.
- `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: `first_name`, `send_invoice` or `is_primary` is missing, or the phone is not valid for `phone_country`. `error.code` is `validation_failed`. Fix: Fix each field named in `error.fields`; its keys are field paths such as `contact.0.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

- [Create or update a customer contact by email or phone](https://developer.yoprint.com/reference/customer-contacts/v1-customer-contact-upsert.md): `POST /v1/api/store/{team_slug}/customer/{hash_id}/contact/upsert`
- [Set the primary contact](https://developer.yoprint.com/reference/customer-contacts/v1-customer-contact-primary.md): `PATCH /v1/api/store/{team_slug}/customer/{hash_id}/contact/{id}/primary`