---
title: "Update contact by email"
method: PATCH
path: "/contacts"
tags: ["Contacts"]
---

# Update contact by email

`PATCH /contacts`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/contacts`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token` scopes: `contacts.write`
  - API key in header `Authorization`

Updates the contact matching the provided email address.

**Scopes:**
`contacts.write`

**Rate Limiting:**
This endpoint is rate limited to 400 requests per minute.

## Query parameters

- `email` string, required

## Headers

- `Omnisend-Version` string, required

## Request body

- ContactRequest: Payload for creating or updating a contact.
  - `address` string: Street, house number, apartment number.
  - `birthdate` string: Contact birthdate in YYYY-MM-DD format
  - `city` string: City
  - `country` string: Country name. Used to derive ISO country code when countryCode is not provided
  - `countryCode` string: ISO 3166-1 alpha-2 country code. Takes priority over country when both are provided
  - `createdAt` string: Contact creation timestamp. If provided, stored as "externalCreated" custom property
  - `customProperties` object: You can add your own custom properties. Read more in https://api-docs.omnisend.com/reference/contacts#custom-properties
  - `firstName` string: Contact first name
  - `gender` 'm' | 'f': Contact gender. m - male, f - female
  - `identifiers` ContactIdentifierRequest[]: Contact identifiers (email and/or phone)
    - `channels` object: Communication channels for this identifier
    - `consent` ContactConsentRequest: Consent record.
      - `createdAt` string: Consent collection timestamp in RFC3339 format. Defaults to current time if not provided
      - `ip` string: IP address at time of consent
      - `source` string: Source of consent
      - `userAgent` string: User agent at time of consent
    - `id` string, required: Identifier value. For email: a valid email address. For phone: full phone number in E.164 format with country code prefix (e.g. +1234567890)
    - `sendWelcomeMessage` boolean: Whether to send a welcome message for this identifier. Defaults to true. Takes effect only if the welcome workflow is enabled.
    - `source` string: Source of the identifier
    - `type` 'email' | 'phone', required: Identifier type
  - `lastName` string: Contact last name
  - `postalCode` string: Postal or zip code
  - `state` string: State or region
  - `tags` string[]: Labels assigned to the contact. When creating a contact, it is strongly advised to include a source tag, e.g. "source: shopify".
  - `trackingConsents` ContactTrackingConsentsRequest: Contact-level tracking consents.
    - `emailOpen` EmailOpenTrackingConsentRequest: Email open tracking consent record.
      - `status` 'given' | 'declined', required: Consent status
      - `statusDate` string: Timestamp when the consent status was collected. Defaults to current time if not provided

## Response `200`

OK

- ContactResponse: Contact resource representation.
  - `address` string: Contact Street, house number, apartment number
  - `birthdate` string: Contact birthdate in YYYY-MM-DD format
  - `city` string: Contact city
  - `consents` Consent[]: Consent records per channel, sorted by collection date (read-only)
    - `channel` 'email' | 'sms': Channel type this consent applies to
    - `createdAt` string: Consent collection timestamp
    - `ip` string: IP address from which consent was collected
    - `source` string: Source through which consent was obtained (e.g. omnisend-form, api)
    - `userAgent` string: User agent string from the consent collection request
  - `country` string: Contact country name
  - `countryCode` string: ISO 3166-1 alpha-2 country code
  - `createdAt` string: Contact creation timestamp (read-only)
  - `customProperties` object: Custom contact properties defined for the brand
  - `email` string: Primary email address derived from the email identifier (read-only)
  - `firstName` string: Contact first name
  - `gender` 'm' | 'f': Contact gender
  - `id` string: Contact unique identifier (read-only)
  - `identifiers` Identifier[]: Contact identifiers with channel subscription details
    - `channels` object: Subscription status per channel, keyed by channel name
    - `id` string: Identifier value (email address or phone number)
    - `type` 'email' | 'phone': Identifier type
  - `lastName` string: Contact last name
  - `optIns` OptIn[]: Opt-in history per channel, sorted by date (read-only)
    - `channel` 'email' | 'sms': Channel type
    - `optInAt` string: Timestamp when the opt-in was recorded
  - `phone` string[]: Phone numbers derived from phone identifiers (read-only)
  - `postalCode` string: Contact postal or ZIP code
  - `segments` string[]: IDs of segments the contact belongs to (read-only)
  - `state` string: State or province name
  - `status` 'subscribed' | 'unsubscribed' | 'nonSubscribed': Email channel subscription status derived from the primary email identifier (read-only)
  - `statuses` ContactStatus[]: Most recent subscription status per channel, sorted by date (read-only)
    - `channel` 'email' | 'sms': Channel type
    - `status` 'subscribed' | 'unsubscribed' | 'nonSubscribed': Channel subscription status
    - `statusChangedAt` string: Timestamp when the status last changed
  - `tags` string[]: Labels assigned to the contact
  - `trackingConsents` ContactTrackingConsents: Contact-level tracking consents.
    - `emailOpen` EmailOpenTrackingConsent: Email open tracking consent record.
      - `status` 'given' | 'declined': Consent status
      - `statusDate` string: Timestamp when the consent status was collected
  - `updatedAt` string: Contact last updated timestamp (read-only)

## Other responses

- `400`: Request contains invalid or missing fields
- `401`: Authentication is missing or invalid
- `403`: Insufficient permissions for this operation
- `404`: Contact not found
- `409`: Contact identifier already exists
- `410`: API version has been retired
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred

---

[API](https://skmtc.dev/omnisend/apis/contacts-api.md) - [All operations](https://skmtc.dev/omnisend/apis/contacts-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/contacts-api/revisions/e5a9a2dd0050?raw)