---
updatedAt: 2026-09-09T10:07:17.000Z
agentTools:
  projectIndex: https://marketing.developer.dotdigital.com/llms.txt
---

# Replace a contact

Replaces a contact with the data passed in the request.<br><br>
  **Note:**
  * This call **replaces** the contact's **identifiers**, **dataFields**, **lists** and **preferences**. Identifiers and data fields you do not specify are removed, and the contact is removed from lists and preferences you do not specify. If you do not specify **mobileNumber**, the contact's mobile number is deleted, and **mobileNumber** then has the value **deleted**.
  * This call does **not** replace the email channel properties. If the contact already has an email channel, the **emailType**, **optInType**, **status** and **openTracking** properties you do not specify remain unaltered. Defaults are only applied when the contact does not have an email channel yet.
  * This call does **not** change consent records. The contact's existing consent records are kept. To add consent records, use **importContact** (PATCH) or **importContacts**.
  * To change only some fields, use the PATCH call.

<span class="callRateMedium"></span>

Replaces a contact entirely with the data passed in the request, including list membership. Because segments are recalculated dynamically from contact data, this can remove the contact from any segments it previously matched.

<Callout icon="🚧" theme="warn">
  ### This call r**eplaces the entire contact**

  This call will **replace the entire contact** when updating with the data passed allowing you to reset the entire contact to a known state; if you want to change only certain fields then use the [PATCH call.](https://marketing.developer.dotdigital.com/reference/importcontact)
</Callout>

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Contacts",
    "description": "Create, Get, update, and delete contacts. Use this API to look up contacts\nby identifier, perform full or partial updates on a single contact, bulk-import\ncollections of contacts asynchronously, and bulk-delete contacts. When listing\ncontacts you can filter by contact status, list subscription status, list\nmembership, segment, or creation and modification date. Each contact can carry\ndata fields, channel properties (email, SMS, WhatsApp), list memberships,\nmarketing preferences, and consent records.",
    "version": "3.5.0"
  },
  "externalDocs": {
    "description": "Learn more about Dotdigital APIs",
    "url": "https://developer.dotdigital.com"
  },
  "servers": [
    {
      "url": "https://{region}-api.dotdigital.com",
      "variables": {
        "region": {
          "description": "The Dotdigital region id your account belongs to",
          "enum": [
            "r1",
            "r2",
            "r3"
          ],
          "default": "r1"
        }
      }
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "paths": {
    "/contacts/v3/{identifier}/{value}": {
      "put": {
        "summary": "Replace a contact",
        "description": "Replaces a contact with the data passed in the request.<br><br>\n  **Note:**\n  * This call **replaces** the contact's **identifiers**, **dataFields**, **lists** and **preferences**. Identifiers and data fields you do not specify are removed, and the contact is removed from lists and preferences you do not specify. If you do not specify **mobileNumber**, the contact's mobile number is deleted, and **mobileNumber** then has the value **deleted**.\n  * This call does **not** replace the email channel properties. If the contact already has an email channel, the **emailType**, **optInType**, **status** and **openTracking** properties you do not specify remain unaltered. Defaults are only applied when the contact does not have an email channel yet.\n  * This call does **not** change consent records. The contact's existing consent records are kept. To add consent records, use **importContact** (PATCH) or **importContacts**.\n  * To change only some fields, use the PATCH call.",
        "operationId": "replaceContact",
        "parameters": [
          {
            "name": "identifier",
            "in": "path",
            "description": "The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of **contactId**, **email** or **mobileNumber**",
            "required": true,
            "schema": {
              "maxLength": 50,
              "minLength": 1,
              "pattern": "(^[-A-Za-z0-9_]{1,50}$)",
              "type": "string"
            },
            "examples": {
              "email": {
                "summary": "Email address",
                "value": "email"
              },
              "mobileNumber": {
                "summary": "Mobile number",
                "value": "mobileNumber"
              },
              "contactId": {
                "summary": "Contact ID",
                "value": "contactId"
              },
              "customIdentifier": {
                "summary": "Custom identifier",
                "value": "loyaltyId"
              }
            }
          },
          {
            "name": "value",
            "in": "path",
            "description": "The unique value to identify the contact.<br>***Note:** Must be the same type as the **identifier***",
            "required": true,
            "schema": {
              "maxLength": 256,
              "minLength": 1,
              "type": "string"
            },
            "examples": {
              "email": {
                "summary": "Email address (use with the email identifier)",
                "value": "amelia.thornbury@emailsim.io"
              },
              "mobileNumber": {
                "summary": "Mobile number (use with the mobileNumber identifier)",
                "value": "447700900184"
              },
              "contactId": {
                "summary": "Contact ID (use with the contactId identifier)",
                "value": "35212311"
              },
              "customIdentifier": {
                "summary": "Custom identifier value (use with the loyaltyId identifier)",
                "value": "LOY-000184"
              }
            }
          },
          {
            "name": "x-ddg-integration-token",
            "in": "header",
            "description": "If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.com/docs/verified-integration-tracking) here.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "5a96bc79-19a7-4544-973b-e2da0c9136f9"
            }
          }
        ],
        "requestBody": {
          "description": "The contact data. **Note:** It is not possible to modify the **contactId** field",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/replaceContactRequest"
              },
              "examples": {
                "replaceDataAndLists": {
                  "summary": "Replace a contact's identifiers, data fields, lists and preferences",
                  "description": "Replaces the contact found by the path parameters. After the call, the contact has only the identifiers, data fields, lists and preferences in the request.<br>\n**Request:** `PUT /contacts/v3/email/amelia.thornbury@emailsim.io`<br><br>\n**Note:** Because this call replaces the contact, send every identifier, data field, list and preference that you want to keep. Consent records are always kept.",
                  "value": {
                    "identifiers": {
                      "email": "amelia.thornbury@emailsim.io",
                      "mobileNumber": "447700900184",
                      "loyaltyId": "LOY-000184"
                    },
                    "dataFields": {
                      "FIRSTNAME": "Amelia",
                      "LASTNAME": "Thornbury",
                      "GENDER": "female",
                      "LOYALTYTIER": "Platinum"
                    },
                    "lists": [
                      345579,
                      345612
                    ],
                    "preferences": [
                      {
                        "id": 1021,
                        "isOptedIn": true
                      }
                    ]
                  }
                },
                "removeMobileNumber": {
                  "summary": "Replace a contact and remove its mobile number",
                  "description": "The request does not include **mobileNumber**, so the contact's mobile number is deleted. After the call, **mobileNumber** has the value **deleted**, and the contact's SMS and WhatsApp channels are not included in the response.<br>\n**Request:** `PUT /contacts/v3/email/marcus.oldacre@emailsim.io`<br><br>\n**Note:** Because this call replaces the contact, send every identifier, data field, list and preference that you want to keep. Consent records are always kept.",
                  "value": {
                    "identifiers": {
                      "email": "marcus.oldacre@emailsim.io"
                    },
                    "dataFields": {
                      "FIRSTNAME": "Marcus",
                      "LASTNAME": "Oldacre",
                      "GENDER": "male"
                    },
                    "lists": [
                      345579
                    ]
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Contact replaced",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/contact"
                },
                "examples": {
                  "replaceDataAndLists": {
                    "summary": "Contact after the identifiers, data fields, lists and preferences were replaced",
                    "description": "The response to the **replaceDataAndLists** request example. The response contains the full contact.<br><br>\n**Note:**\n* Every data field in your account is returned. Data fields that have no value are **null**. This example shows only some of them.\n* Every identifier in your account is returned. Identifiers that have no value are empty.\n* Lists, preferences and consent records are only included if the contact has them.",
                    "value": {
                      "contactId": 35212311,
                      "status": "subscribed",
                      "created": "2025-03-04T09:15:22.483",
                      "updated": "2026-10-16T14:07:04.217",
                      "identifiers": {
                        "email": "amelia.thornbury@emailsim.io",
                        "mobileNumber": "447700900184",
                        "loyaltyId": "LOY-000184"
                      },
                      "dataFields": {
                        "FIRSTNAME": "Amelia",
                        "GENDER": "female",
                        "LASTNAME": "Thornbury",
                        "LOYALTYTIER": "Platinum"
                      },
                      "channelProperties": {
                        "email": {
                          "status": "subscribed",
                          "emailType": "html",
                          "optInType": "double",
                          "openTracking": "subscribed"
                        },
                        "sms": {
                          "status": "subscribed",
                          "countryCode": "GB"
                        },
                        "whatsApp": {
                          "status": "noSubscription"
                        }
                      },
                      "lists": [
                        {
                          "id": 345579,
                          "name": "Monthly newsletter",
                          "status": "subscribed"
                        },
                        {
                          "id": 345612,
                          "name": "Loyalty members",
                          "status": "subscribed"
                        }
                      ],
                      "preferences": [
                        {
                          "publicName": "Special offers",
                          "privateName": "specialOffers",
                          "id": 1021,
                          "isOptedIn": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                },
                "example": {
                  "errorCode": "contacts:invalidId",
                  "description": "The id value '123646' is invalid for the identifier 'email'"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "Contact not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                },
                "example": {
                  "errorCode": "contacts:contactNotFound",
                  "description": "The following contacts could not be found.",
                  "details": [
                    {
                      "item": "35219999",
                      "description": "Not found using the identifier 'ContactId'."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "optInType": {
        "type": "string",
        "description": "Channel opt-in type for the contact",
        "example": "double",
        "enum": [
          "unknown",
          "single",
          "double",
          "verifiedDouble"
        ]
      },
      "status": {
        "type": "string",
        "description": "The opt in status for the contact. Only **getContacts** returns contacts with the status **deleted**.",
        "example": "subscribed",
        "enum": [
          "subscribed",
          "unsubscribed",
          "pendingOptIn",
          "deleted",
          "suppressed",
          "binned",
          "noSubscription"
        ]
      },
      "preference": {
        "required": [
          "id",
          "isOptedIn"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "ID of the preference",
            "format": "int32",
            "example": 1
          },
          "isOptedIn": {
            "type": "boolean",
            "description": "Specify whether the contact is opted into this preference"
          }
        }
      },
      "preferenceFull": {
        "required": [
          "id",
          "isOptedIn",
          "privateName",
          "publicName"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "ID of the preference",
            "format": "int32",
            "example": 1
          },
          "isOptedIn": {
            "type": "boolean",
            "description": "Indicates whether the contact is opted into this preference"
          },
          "publicName": {
            "type": "string",
            "description": "Public name of the marketing preference",
            "example": "Mens fashion"
          },
          "privateName": {
            "type": "string",
            "description": "Private name of the marketing preference",
            "example": "mensFashion01"
          }
        }
      },
      "consentRecord": {
        "required": [
          "dateTimeConsented",
          "ipAddress",
          "text",
          "url",
          "userAgent"
        ],
        "type": "object",
        "properties": {
          "text": {
            "minLength": 1,
            "type": "string",
            "description": "Consent text displayed to the contact",
            "example": "Yes, I would like to receive a monthly newsletter"
          },
          "dateTimeConsented": {
            "type": "string",
            "description": "ISO 8601 UTC timestamp for when the consent was obtained",
            "format": "date-time",
            "example": "2023-01-26T21:29:00Z"
          },
          "url": {
            "type": "string",
            "description": "URL the consent was obtained with",
            "format": "uri",
            "example": "http://www.example.com/signup"
          },
          "ipAddress": {
            "oneOf": [
              {
                "type": "string",
                "description": "IPv4 address of the contact the consent was obtained for",
                "format": "ipv4",
                "example": "129.168.0.2"
              },
              {
                "type": "string",
                "description": "IPv6 address of the contact the consent was obtained for",
                "format": "ipv6",
                "example": "2b01:1234:136:0:116f:3244:a476:d6b7"
              }
            ]
          },
          "userAgent": {
            "minLength": 1,
            "type": "string",
            "description": "User agent header of the browser used by the contact the consent was obtained for",
            "example": "Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36"
          }
        },
        "description": "Marketing consent records to be associated with the contact"
      },
      "consentRecords": {
        "type": "array",
        "description": "Marketing consent records associated with the contact. If the contact has no consent records, this property is an empty array or is not included, depending on the call.",
        "items": {
          "example": {
            "text": "Yes, I would like to receive a monthly newsletter",
            "dateTimeConsented": "2023-01-26T21:29:00",
            "url": "http://www.example.com/signup",
            "ipAddress": "129.168.0.2",
            "userAgent": "Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36",
            "dateTimeCreated": "2023-01-26T22:55:00"
          },
          "allOf": [
            {
              "$ref": "#/components/schemas/consentRecord"
            },
            {
              "required": [
                "dateTimeCreated"
              ],
              "type": "object",
              "properties": {
                "dateTimeCreated": {
                  "type": "string",
                  "description": "UTC timestamp for when the consent record was created, in ISO 8601 format. Depending on the call, it is returned with or without the **Z** time zone designator and fractional seconds. For example, **getContact** returns **2023-07-11T11:19:06.2514793Z** and **createContact** returns **2026-10-16T13:17:36**.",
                  "format": "date-time",
                  "example": "2023-01-26T22:55:00Z"
                }
              }
            }
          ]
        }
      },
      "contactBasicDetails": {
        "required": [
          "contactId",
          "created",
          "identifiers",
          "status",
          "updated"
        ],
        "type": "object",
        "properties": {
          "contactId": {
            "$ref": "#/components/schemas/contactId"
          },
          "status": {
            "$ref": "#/components/schemas/status"
          },
          "created": {
            "type": "string",
            "description": "UTC timestamp for when the contact was created, in ISO 8601 format. Depending on the call, it is returned with or without the **Z** time zone designator, and with up to 7 fractional-second digits. For example, **getContacts** returns **2025-03-04T09:15:22.483** and **createContact** returns **2026-10-16T13:17:36.4759674Z**.",
            "format": "date-time"
          },
          "updated": {
            "type": "string",
            "description": "UTC timestamp for when the contact was last updated, in ISO 8601 format. Depending on the call, it is returned with or without the **Z** time zone designator, and with up to 7 fractional-second digits. For example, **getContacts** returns **2026-10-12T14:03:51.27** and **createContact** returns **2026-10-16T13:17:36.4759674Z**.",
            "format": "date-time"
          },
          "identifiers": {
            "$ref": "#/components/schemas/identifiers"
          }
        }
      },
      "contact": {
        "allOf": [
          {
            "$ref": "#/components/schemas/contactBasicDetails"
          },
          {
            "type": "object",
            "properties": {
              "dataFields": {
                "type": "object",
                "additionalProperties": true,
                "description": "Addtional data fields for the contact specified for the contact",
                "example": {
                  "FIRSTNAME": "John",
                  "LASTNAME": "Doe",
                  "GENDER": "male"
                }
              },
              "channelProperties": {
                "type": "object",
                "properties": {
                  "email": {
                    "required": [
                      "emailType",
                      "openTracking",
                      "optInType",
                      "status"
                    ],
                    "type": "object",
                    "properties": {
                      "emailType": {
                        "type": "string",
                        "description": "The format the contact expects emails in.",
                        "example": "html",
                        "enum": [
                          "plainText",
                          "html"
                        ]
                      },
                      "optInType": {
                        "$ref": "#/components/schemas/optInType"
                      },
                      "status": {
                        "$ref": "#/components/schemas/emailChannelStatus"
                      },
                      "openTracking": {
                        "type": "string",
                        "description": "Specifies if you are allowed to track email opens for the contact. **unknown** means that no explicit opt-in or opt-out record exists.",
                        "example": "subscribed",
                        "enum": [
                          "unknown",
                          "subscribed",
                          "unsubscribed"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "sms": {
                    "required": [
                      "countryCode",
                      "status"
                    ],
                    "type": "object",
                    "properties": {
                      "countryCode": {
                        "type": "string",
                        "description": "[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code the contacts **mobileNumber**",
                        "example": "GB"
                      },
                      "status": {
                        "$ref": "#/components/schemas/smsChannelStatus"
                      }
                    },
                    "additionalProperties": false
                  },
                  "whatsApp": {
                    "required": [
                      "status"
                    ],
                    "type": "object",
                    "properties": {
                      "status": {
                        "$ref": "#/components/schemas/whatsAppChannelStatus"
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "additionalProperties": false,
                "description": "Properties associated with each channel for a contact, for example message format or subscription status. A channel the contact does not have, or a channel that was deleted, is not included."
              },
              "lists": {
                "type": "array",
                "description": "Lists the contact belongs to",
                "items": {
                  "required": [
                    "id",
                    "name",
                    "status"
                  ],
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Immutable unique list ID",
                      "format": "int32",
                      "example": 12345
                    },
                    "name": {
                      "maxLength": 128,
                      "type": "string",
                      "description": "Name of the list",
                      "example": "Top customers"
                    },
                    "status": {
                      "type": "string",
                      "description": "The list status for the contact",
                      "example": "subscribed",
                      "enum": [
                        "subscribed",
                        "suppressed",
                        "pending"
                      ]
                    }
                  }
                }
              },
              "preferences": {
                "type": "array",
                "description": "Marketing preferences of the contact. If the contact has no preferences, this property is an empty array or is not included, depending on the call.",
                "items": {
                  "$ref": "#/components/schemas/preferenceFull"
                }
              },
              "consentRecords": {
                "$ref": "#/components/schemas/consentRecords"
              }
            },
            "description": "A contact"
          }
        ]
      },
      "baseContact": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "dataFields": {
                "type": "object",
                "additionalProperties": true,
                "description": "Addtional data fields for the contact",
                "example": {
                  "FIRSTNAME": "John",
                  "LASTNAME": "Doe",
                  "GENDER": "male"
                }
              }
            }
          },
          {
            "$ref": "#/components/schemas/channelProperties"
          },
          {
            "type": "object",
            "properties": {
              "lists": {
                "maxItems": 100,
                "minItems": 1,
                "type": "array",
                "description": "List IDs for the lists the contact should be added to",
                "items": {
                  "type": "integer",
                  "description": "Unique list id",
                  "format": "int32",
                  "example": 345579
                }
              },
              "preferences": {
                "minItems": 1,
                "type": "array",
                "description": "Preferences you want to opt the contact into. ***Note:** Only required for preferences and not preference categories*",
                "items": {
                  "$ref": "#/components/schemas/preference"
                }
              }
            }
          }
        ]
      },
      "replaceContactRequest": {
        "allOf": [
          {
            "required": [
              "identifiers"
            ],
            "type": "object",
            "properties": {
              "identifiers": {
                "allOf": [
                  {
                    "description": "Identifiers this contact can be referenced by"
                  },
                  {
                    "$ref": "#/components/schemas/identifiers"
                  }
                ]
              }
            }
          },
          {
            "$ref": "#/components/schemas/baseContact"
          },
          {
            "$ref": "#/components/schemas/channelPropertiesWithResubscribe"
          }
        ]
      },
      "channelStatusUpdate": {
        "type": "string",
        "description": "The subscription status for the channel; if not specified it remains unaltered for existing contacts, and for new contacts this defaults to values defined in _Settings > Contacts > Mobile subscription_",
        "example": "subscribed",
        "enum": [
          "noSubscription",
          "subscribed",
          "unsubscribed",
          "suppressed"
        ]
      },
      "emailChannelStatus": {
        "type": "string",
        "description": "Current status of the email channel for the contact",
        "example": "subscribed",
        "enum": [
          "subscribed",
          "unsubscribed",
          "suppressed",
          "binned",
          "pendingOptIn",
          "softBounced",
          "hardBounced",
          "ispComplained",
          "mailBlocked",
          "directComplaint",
          "spamTrap",
          "blockedLocalPart",
          "sharedSuppression",
          "sharedDomainSuppression",
          "purchased",
          "knownComplainer",
          "knownLitigator",
          "domainSuppression",
          "noMXRecord"
        ]
      },
      "whatsAppChannelStatus": {
        "type": "string",
        "description": "The current status for the WhatsApp channel for this contact",
        "example": "subscribed",
        "enum": [
          "noSubscription",
          "subscribed",
          "unsubscribed",
          "suppressed",
          "binned"
        ]
      },
      "smsChannelStatus": {
        "type": "string",
        "description": "The current status for the SMS channel for this contact",
        "example": "subscribed",
        "enum": [
          "noSubscription",
          "subscribed",
          "unsubscribed",
          "suppressed",
          "binned",
          "bounced"
        ]
      },
      "channelProperties": {
        "type": "object",
        "properties": {
          "channelProperties": {
            "type": "object",
            "properties": {
              "email": {
                "type": "object",
                "properties": {
                  "emailType": {
                    "type": "string",
                    "description": "Format the contact receives emails in.<br>\n* **New contacts, or contacts that do not have an email channel yet:** If not specified, this is set to **html**.\n* **Contacts that already have an email channel:** If not specified, the existing value remains unaltered.<br>\n***Note:** When you import a collection of contacts and one or more contacts in the collection specify **emailType**, then the contacts in the same collection that do not specify it are set to **html**. To keep the existing value, specify **emailType** for each contact, or do not specify it for any contact in the collection.*",
                    "example": "html",
                    "enum": [
                      "plainText",
                      "html"
                    ]
                  },
                  "optInType": {
                    "type": "string",
                    "description": "Email opt-in type for the contact.<br>\n* **New contacts, or contacts that do not have an email channel yet:** If not specified, this is set to **unknown**.\n* **Contacts that already have an email channel:** If not specified, the existing value remains unaltered.<br>\n***Note:** If you set this to **verifiedDouble**, or the account setting *Enforce double opt-in for all signups, including bulk uploads* is on, the contact is sent an email to confirm their subscription. Until the contact confirms, the email channel status is **pendingOptIn** and **optInType** remains **unknown**.*",
                    "example": "double",
                    "enum": [
                      "unknown",
                      "single",
                      "double",
                      "verifiedDouble"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "description": "The subscription status for the email channel.<br>\n* **New contacts, or contacts that do not have an email channel yet:** If not specified, this is set to **subscribed**.\n* **Contacts that already have an email channel:** If not specified, the existing value remains unaltered.<br>\n***Note:** If you change the email address of an existing contact and the current email channel status is **subscribed**, **binned** or **deleted**, the status is set to **subscribed**. If the current status is **subscribed** and the account setting *Enforce double opt-in for all signups, including bulk uploads* is on, the status is set to **pendingOptIn** until the contact confirms.*",
                    "enum": [
                      "subscribed",
                      "unsubscribed",
                      "suppressed"
                    ]
                  },
                  "openTracking": {
                    "type": "string",
                    "description": "Specifies if you are allowed to track email opens for the contact.<br>\n* **New contacts, or contacts that do not have an email channel yet:** If not specified, this is set to **unknown** and no explicit opt-in or opt-out record is written.\n* **Contacts that already have an email channel:** If not specified, the existing value remains unaltered.",
                    "enum": [
                      "unknown",
                      "subscribed",
                      "unsubscribed"
                    ],
                    "default": "unknown"
                  }
                },
                "description": "The channel properties for email. All properties are optional. Specify only the properties you want to set. For contacts that already have an email channel, properties you do not specify remain unaltered."
              },
              "sms": {
                "type": "object",
                "properties": {
                  "status": {
                    "$ref": "#/components/schemas/channelStatusUpdate"
                  }
                },
                "additionalProperties": false,
                "description": "The channel properties for SMS/MMS"
              },
              "whatsApp": {
                "type": "object",
                "properties": {
                  "status": {
                    "$ref": "#/components/schemas/channelStatusUpdate"
                  }
                },
                "additionalProperties": false,
                "description": "The channel properties for WhatsApp"
              }
            },
            "additionalProperties": false,
            "description": "Properties associated with each channel for a contact. For example, message format or subscription status"
          }
        }
      },
      "channelPropertiesWithResubscribe": {
        "type": "object",
        "properties": {
          "channelProperties": {
            "type": "object",
            "properties": {
              "email": {
                "type": "object",
                "properties": {
                  "resubscribeOptions": {
                    "type": "object",
                    "properties": {
                      "resubscribeWithNoChallenge": {
                        "type": "boolean",
                        "description": "Set to **true** to resubscribe the contact without sending a resubscription confirmation email. If not specified, this is set to **false**, so the contact is sent a resubscription confirmation email.",
                        "default": false
                      },
                      "preferredLocale": {
                        "type": "string",
                        "description": "The language code for the language of the resubscription confirmation email. If not specified, the default locale of the account is used.<br><br>\n**Note:** Use the values exactly as listed. Some of them are not standard locale codes, for example **en-EN** for English and **se-SE** for Swedish.\n\n| Value | Language |\n|---|---|\n| `cs-CS` | Czech |\n| `da-DA` | Danish |\n| `de-DE` | German |\n| `el-EL` | Greek |\n| `en-EN` | English |\n| `es-ES` | Spanish (Spain) |\n| `es` | Spanish |\n| `fi-FI` | Finnish |\n| `fr-FR` | French |\n| `hu-HU` | Hungarian |\n| `it-IT` | Italian |\n| `nl-NL` | Dutch |\n| `nb-NO` | Norwegian Bokmål |\n| `pl-PL` | Polish |\n| `pt-PT` | Portuguese |\n| `ru-RU` | Russian |\n| `se-SE` | Swedish |\n| `sk-SK` | Slovak |\n| `tr-TR` | Turkish |\n| `zh-CN` | Chinese (Simplified) |",
                        "enum": [
                          "cs-CS",
                          "da-DA",
                          "de-DE",
                          "el-EL",
                          "en-EN",
                          "es-ES",
                          "es",
                          "fi-FI",
                          "fr-FR",
                          "hu-HU",
                          "it-IT",
                          "nl-NL",
                          "nb-NO",
                          "pl-PL",
                          "pt-PT",
                          "ru-RU",
                          "se-SE",
                          "sk-SK",
                          "tr-TR",
                          "zh-CN"
                        ]
                      },
                      "redirectUrlAfterChallenge": {
                        "type": "string",
                        "description": "The URL to send the contact to after they confirm their resubscription. If not specified, the standard default redirect page is used.",
                        "format": "uri",
                        "example": "https://somedomain.io/some/page"
                      }
                    },
                    "description": "Options for resubscribing the email channel of a contact. A resubscription is only triggered when you specify **resubscribeOptions**; if you do not specify it, no resubscription occurs."
                  }
                }
              }
            }
          }
        }
      },
      "errorResponse": {
        "required": [
          "description",
          "errorCode"
        ],
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "string",
            "description": "Unique error code"
          },
          "description": {
            "type": "string",
            "description": "Description of the issue"
          },
          "details": {
            "type": "array",
            "items": {
              "required": [
                "description",
                "item"
              ],
              "type": "object",
              "properties": {
                "item": {
                  "type": "string",
                  "description": "Item the error is associated with, for example, field name, unique identifier for an entity or item in batch"
                },
                "description": {
                  "type": "string",
                  "description": "Description of the error"
                }
              }
            }
          }
        }
      },
      "contactId": {
        "minimum": 0,
        "type": "integer",
        "description": "Immutable unique identifier for the contact",
        "example": 35212311
      },
      "identifiers": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Contact email address",
            "nullable": true,
            "example": "someone@emailsim.io"
          },
          "mobileNumber": {
            "type": "string",
            "description": "Contact phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164)",
            "nullable": true,
            "example": "447123123123"
          }
        },
        "additionalProperties": {
          "type": "string",
          "description": "Any additional custom identifiers. Property names must match one of the custom identifiers that exists in the account.",
          "nullable": true
        },
        "description": "Identifiers this contact can be referenced by",
        "example": {
          "email": "someone@emailsim.io",
          "mobileNumber": "447123123123",
          "myCustomId": "MYID_12345"
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "x-ddg-notes": "This version corrects the schema and documentation for importing contacts and for email channel properties. The changes are additive; the API behaviour does not change.\n* **importContacts:** Added request examples for these use cases: update data fields and identifiers, unsubscribe from email, set email open tracking, add a consent record, and update data fields, identifiers and list membership.\n* **getContacts:** Added response examples: key details only, selected data fields with lists and preferences, a page with a next link, contacts modified since the last poll, and modified contacts in a list or a segment.\n* **importContact:** Added request examples for the same use cases, and an example to resubscribe a contact to email. Added request examples that create and then update a contact, with their 201 and 200 response examples. The description now states that a new contact needs **identifiers.email** or **identifiers.mobileNumber** in the request body, and a 400 example shows the error.\n* **deleteContacts:** Each item must now contain exactly one identifier. Items that use **email** or **mobileNumber** are now valid against the schema. Added a request example and corrected the 400 error example.\n* **getImportStatus:** Added response examples, including a contact that has only a custom identifier. **matchIdentifier** is no longer required in **failures**, because the API does not return it. Replaced the failures example.\n* **Contact responses:** The email, SMS and WhatsApp channel status values now match the values the API returns. A deleted channel is not included in **channelProperties**.\n* **getContact:** Added examples for each identifier type in the path, and response examples for a full contact and for a contact whose mobile number was deleted.\n* **replaceContact:** Added examples for each identifier type in the path, request examples to replace data and lists and to remove a mobile number, and a response example.\n* **deleteContact:** Added examples for each identifier type in the path, and a response example.\n* **getContact, replaceContact and deleteContact:** Corrected the 404 error examples to match the API.\n* **getDeleteStatus:** Added response examples. Corrected the 404 response, which described an import request in place of a delete job.\n* **createContact:** Added request examples: email address only, a full profile with channels, lists, preferences and consent, verified double opt-in, and mobile number only. Added a 201 response example. Corrected the 409 error example. The description now states that the request must contain **email** or **mobileNumber**, and a 400 example shows the error.\n* **importContacts:** The description now states that a new contact needs **email** or **mobileNumber** in its identifiers, and the failure the import reports if it does not.\n* **importContacts:** Contacts that match on **contactId** are now valid against the schema. The request uses the new **contactRequestIdentifiers** schema, where **contactId** is an integer.\n* **Email channel properties:** **emailType**, **optInType**, **status** and **openTracking** are no longer required. The descriptions now give the default for contacts that do not have an email channel yet, and the behaviour for contacts that already have one.\n* **Email channel properties:** **resubscribeOptions** can now be sent together with the other email channel properties.\n* **resubscribeWithNoChallenge:** The default is now **false**, which agrees with the API behaviour.\n* **Contact responses:** Email channel properties now pass validation. **emailType** and **optInType** values are now camelCase (for example **html** and **single**), which agrees with the API. **openTracking** is now included and is always returned. The request channel properties schema is no longer applied to responses, so all email and SMS statuses and the SMS **countryCode** are now valid.\n* **Contact responses:** Consent records and preferences now pass validation. Preferences require **publicName** and **privateName**, which the API returns, in place of the undefined **name** property.\n* **x-ddg-integration-token:** The header now uses **format: uuid** in place of a pattern that rejected every value. Send the token as a UUID without braces.\n* **Contact responses:** The **created**, **updated** and consent record **dateTimeCreated** descriptions now state the formats the API returns. The **preferences** and **consentRecords** arrays can now be empty or not included.\n* **Deleted contacts:** The descriptions now explain when **email** and **mobileNumber** have the value **deleted**.\n* **replaceContact:** The description now states that email channel properties you do not specify remain unaltered.",
  "x-samples-languages": [
    "curl",
    "csharp",
    "java",
    "javascript",
    "node",
    "python",
    "php",
    "ruby"
  ]
}
```

# Sibling pages

* [Get contacts based on your criteria](https://marketing.developer.dotdigital.com/reference/getcontacts-1.md)
* [Import contact collection](https://marketing.developer.dotdigital.com/reference/importcontacts-1.md)
* [Get the status of a contacts import request](https://marketing.developer.dotdigital.com/reference/getimportstatus.md)
* [Get a contact by an identifier](https://marketing.developer.dotdigital.com/reference/getcontact.md)
* [Get the status of a delete contacts job](https://marketing.developer.dotdigital.com/reference/getdeletestatus.md)
* [Delete multiple contacts](https://marketing.developer.dotdigital.com/reference/deletecontacts.md)
* [Create a contact](https://marketing.developer.dotdigital.com/reference/createcontact-1.md)
* [Deletes a contact using a specific identifier](https://marketing.developer.dotdigital.com/reference/deletecontact-1.md)
* [Import a single contact](https://marketing.developer.dotdigital.com/reference/importcontact.md)