openapi: 3.0.3
info:
title: Contacts
description: 'Create, Get, update, and delete contacts. Use this API to look up contacts
by identifier, perform full or partial updates on a single contact, bulk-import
collections of contacts asynchronously, and bulk-delete contacts. When listing
contacts you can filter by contact status, list subscription status, list
membership, segment, or creation and modification date. Each contact can carry
data fields, channel properties (email, SMS, WhatsApp), list memberships,
marketing preferences, and consent records.'
version: 3.4.3
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:
get:
summary: Get contacts based on your criteria
description: 'Get contacts based on criteria you specify. Contacts are returned with full data, specified data fields, or key information and identifiers only.<br/><br/>
*Note: All data is returned in ascending order*'
operationId: getContacts
parameters:
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
- name: data-fields
in: query
description: Contact data is returned with a minimum of **contactId** and any associated **identifiers**. Use this field to specify any additional data fields you want to return. Enter a pipe delimited string of the contact data fields required or **[[ALL]]** to Get all data fields.
required: false
style: pipeDelimited
explode: false
schema:
type: array
example:
- FIRSTNAME
- LASTNAME
- FULLNAME
- GENDER
- POSTCODE
items:
type: string
- name: include
in: query
description: Specify additional data sets associated with the contact to include in the returned data.
required: false
style: pipeDelimited
explode: false
schema:
type: array
example:
- preferences
- lists
items:
type: string
enum:
- channelProperties
- lists
- preferences
- consentRecords
- name: ~created
in: query
description: 'Filter by created date.<br/>
***Note:***
* The date must be in ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601))
* Can''t be used in conjunction with the **~modified** parameter.'
schema:
pattern: ^gte::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$
type: string
examples:
Greater than or equal to created date:
value: gte::2021-12-17T00:00:00Z
- name: ~modified
in: query
description: 'Filter by last modified date.<br/>
***Note:***
* The date must be in ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601))'
schema:
pattern: ^gte::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$
type: string
examples:
Greater than or equal to modified date:
value: gte::2021-12-17T00:00:00Z
- name: ~listId
in: query
description: 'Filter by a specific list.<br/>
***Note:***
* Can''t be used in conjunction with the **~segmentId** parameter.'
schema:
type: integer
example: 54321
- name: ~segmentId
in: query
description: 'Filter by a specific segment.<br/>
***Note:***
* Can''t be used in conjunction with the **~listId** parameter.'
schema:
type: integer
example: 12345
- name: limit
in: query
description: Maximum number of records to retrieve per page
schema:
maximum: 5000
minimum: 1
type: integer
format: int32
example: 1000
- name: marker
in: query
description: Pagination marker to retrieve the data from
schema:
type: string
example: RXhhbXBsZSBhbXJrZXIgdmFsdWU=
responses:
'200':
description: Contacts retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:invalidFilter
description: The filter value '2022-08-01T00:00:00Z' is invalid
'401':
description: Unauthorized
post:
summary: Create a contact
description: Creates a contact if the identifiers passed are unique in the account then a new contact will be created, otherwise it will fail the call with a 409.
operationId: createContact
parameters:
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
requestBody:
description: Contact data
content:
application/json:
schema:
$ref: '#/components/schemas/createContactRequest'
required: true
responses:
'201':
description: Contact created
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
'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
'409':
description: Identifier conflict
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:idAlreadyExists
description: The id value 'jane.doe@emailsim.io for the identifier 'email' already exists. All identifiers must be unique!
/contacts/v3/delete:
post:
summary: Delete multiple contacts
description: Async deletes multiple contacts using whichever identifier you wish.
operationId: deleteContacts
parameters:
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
requestBody:
description: The contact references you want to delete
content:
application/json:
schema:
maxItems: 5000
minItems: 1
type: array
items:
$ref: '#/components/schemas/contactIdentifier'
required: true
responses:
'202':
description: Delete request accepted
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_202'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:noContactsSpecified
description: You must specifiy 1 or more contacts to be deleted!
'401':
description: Unauthorized
'429':
description: Too many bulk delete jobs
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:tooManyBulkDeleteJobs
description: Your bulk delete request cannot be accepted as too many bulk delete jobs are being processed for you account. Please wait for a bulk delete job to complete and then resubmit.
/contacts/v3/delete/{deleteId}:
get:
summary: Get the status of a delete contacts job
description: Gets the status of a delete contacts job and the results if complete.
operationId: getDeleteStatus
parameters:
- name: deleteId
in: path
description: The delete job id you want the status for
required: true
schema:
type: string
example: c4920aee-3add-44e4-b8c0-dcbfacbfee40
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200_1'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:invalidDeleteId
description: The id value '123646' is not a recognized deletion job identifier
'401':
description: Unauthorized
'404':
description: Import request not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:importNotFound
description: The import request 'd7de900d-d337-43f6-b1e1-c8ec73e1a434' could not be found!
/contacts/v3/import:
put:
summary: Import contact collection
description: Imports a collection of contacts. Creates contacts if they do not exist and updates contacts if they do. This is an async operation and you will need to check when it is complete by calling **getImportStatus** <br><br>**Note:** It isn't possible to specify the value for the **contactId** field when creating a contact, so it is only used to check for a matching contact when specified
operationId: importContacts
parameters:
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
requestBody:
description: Contact data collection
content:
application/json:
schema:
$ref: '#/components/schemas/v3_import_body'
example:
mergeOption: overwrite
contacts:
- matchIdentifier: email
identifiers:
email: jane.doe@emailsim.io
dataFields:
firstName: Jane
lastName: Doe
gender: female
- matchIdentifier: mobileNumber
identifiers:
email: john.doe@emailsim.io
mobileNumber: '447123123123'
dataFields:
firstName: John
lastName: Doe
gender: male
channelProperties:
email:
emailType: Html
- matchIdentifier: contactId
identifiers:
contactId: 123456
email: my-new-email@emailsim.io
required: true
responses:
'202':
description: Import processing
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_202_1'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:badJson
description: The request JSON is badly formed
'401':
description: Unauthorized
'429':
description: Too many import requests
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:tooManyActiveImports
description: Your import request cannot be accepted as too many imports are being processed for you account. Please wait for an import to complete and then resubmit.
/contacts/v3/import/{importId}:
get:
summary: Get the status of a contacts import request
description: Gets the status of a contacts import request and the results if available.<br><br>**Note:** When importing, contacts are created or updated but if any associated data sets fail to import then details of these are included in the **failures** results
operationId: getImportStatus
parameters:
- name: importId
in: path
description: The import id you want the status for
required: true
schema:
type: string
example: d7de900d-d337-43f6-b1e1-c8ec73e1a434
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200_2'
'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: Import request not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:importNotFound
description: The import request 'd7de900d-d337-43f6-b1e1-c8ec73e1a434' could not be found!
/contacts/v3/{identifier}/{value}:
get:
summary: Get a contact by an identifier
description: Get a contact's details using a specific identifier
operationId: getContact
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
- 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
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
'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: unknown@emailsim.io
description: Not found using the identifier 'email'
put:
summary: Replace a contact
description: "Replaces a contact entirly with the data passed in the request.<br><br>\n **Note:**\n * This call will **replace the entire contact** when updating with the data passed; if would like to change just select fields then 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
- 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
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
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'
required: true
responses:
'200':
description: Contact replaced
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
'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: '354265'
description: Not found using the identifier 'contactId'
delete:
summary: Deletes a contact using a specific identifier
description: Delete a contact using a specific identifier
operationId: deleteContact
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
- 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
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
responses:
'200':
description: Contact deleted
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200_3'
'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: '354265'
description: Not found using the identifier 'contactId'
patch:
summary: Import a single contact
description: Imports a single contact; if it is an existing contact it updates the contact with just the fields passed in the request with a choice of how to handle the merging of data, otherwise it create a new contact.
operationId: importContact
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
- 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
- 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.co/docs/verified-integration-tracking) here.
required: false
schema:
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
type: string
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
- name: merge-option
in: query
description: Set the behavior of how the new data should be merged into existing contacts.
required: false
schema:
type: string
example: overwrite
enum:
- overwrite
- overwrite-if-not-empty
- overwrite-if-empty
default: overwrite
requestBody:
description: The contact fields to update. **Note:** It is not possible to modify the **contactId** field
content:
application/json:
schema:
$ref: '#/components/schemas/updateContactRequest'
required: true
responses:
'200':
description: Contact updated
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
'201':
description: Contact created
content:
application/json:
schema:
$ref: '#/components/schemas/contact'
'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
'409':
description: Identifier conflict
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
errorCode: contacts:idAlreadyExists
description: The id value 'jane.doe@emailsim.io for the identifier 'email' already exists. All identifiers must be unique!
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
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
- name
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
additionalProperties: false
description: Marketing consent records to be associated with the contact
consentRecordsToBeInserted:
maxItems: 5
minItems: 1
type: array
description: The marketing consent records to be associated with the contact
items:
$ref: '#/components/schemas/consentRecord'
consentRecords:
type: array
description: Marketing consent records associated with the contact
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: ISO 8601 UTC timestamp for when the consent was created
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: ISO 8601 UTC timestamp for when the contact was created
format: date-time
updated:
type: string
description: ISO 8601 UTC timestamp for when the contact was last updated
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:
$ref: '#/components/schemas/contact_channelProperties'
lists:
type: array
description: Lists the contact belongs to
items:
$ref: '#
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dotdigital/refs/heads/main/openapi/dotdigital-contacts-openapi.yml