swagger: '2.0'
info:
title: Emarsys Core API - Contacts endpoint batch
description: In this batch you may find endpoints related to contacts.
version: v2
host: api.emarsys.net
basePath: /api
schemes:
- https
paths:
/v2/contact:
post:
summary: Create Contact
description: |-
Creates new contacts, returns their automatically generated unique identifier (`id`), and maps their data to the relevant fields using the respective field identifiers. For details, see [Concepts](docs/before-you-start/concepts.md).
> **Important**: If you use a custom field for `key_id` during customer identification, this field has to be indexed. This can be requested by [raising a support ticket](https://help.emarsys.com/hc/en-us/articles/360012853058-Raising-a-support-request) at our Help Portal.
**Note:**
The example below in the Request Body section shows the scenario when multiple contacts are created. However, when only a single contact is to be added, the following JSON structure must be used:
```
{
"key_id" : "3",
"3" : "johndoe@example.com",
"1" : "John",
"2" : "Doe"
}
```
**To consider:**
- The maximum payload size is 10 MB, therefore the maximum number of new contacts per call depends on the amount of data per contact.
- The maximum batch size is 1000 contacts per call.
**Note:** Due to limitations of API specification languages, dynamic keys are indicated by curly brackets or by a regex pattern.
**Important:** When [Exporting updated contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post), contacts that were updated through this endpoint will only be exported if their email address or opt-in status were updated.
operationId: createContacts
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
contacts:
type: array
items:
type: object
properties:
'2':
type: string
'3':
type: string
key_id:
description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
anyOf:
- type: string
- type: integer
required:
- key_id
x-examples:
- contacts:
- '{newFieldIdentifier}': cupidatat eiusmod eu consequat
- source_id: -80543794
'{newFieldIdentifier}': nostrud Excepteur qui consequat
key_id: -54315715
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
data:
type: object
description: The requested data.
properties:
errors:
type: object
description: List of errors during creating contacts.
patternProperties:
'^[\W\w]+':
type: object
description: Identifies the contact by the value of the requested `key_id`.
properties:
'2009':
type: string
ids:
type: array
description: List of contact identifiers (id) of successfully created contacts.
items:
type: integer
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
'2020':
description: ''
schema:
type: object
properties:
data:
type: string
replyCode:
type: integer
replyText:
type: string
description: 'Invalid contact list id: `contact_list_id`'
examples:
Invalid contact list id:
data: ''
replyCode: 2020
replyText: 'Invalid contact list id: 8789789789789789789'
example-1:
data: string
replyCode: 0
replyText: string
security:
- X-WSSE: []
v2/contact/:
put:
summary: Update Contacts
description: |-
Updates multiple contacts, or creates them if they do not exist.
It is recommended to use the `id` or `uid` fields to identify contacts in order to avoid conflicts when using a non-unique field, such as `email`.
You can also create a new contact **and** add it to an exsiting contact list *in one go* using this command with the optional `contact_list_id` parameter.
For details, see [Concepts](docs/before-you-start/concepts.md).
> **Important**: If you use a custom field for `key_id` during customer identification, this field has to be indexed. This can be requested by [raising a support ticket](https://help.emarsys.com/hc/en-us/articles/360012853058-Raising-a-support-request) at our Help Portal.
> **Caution**: The `create_if_not_exists` parameter is designed as a convenience feature to streamline API integrations by eliminating the need for clients to check a contact's existence before updating. When this parameter is enabled, the API will internally verify the contact's existence and, if necessary, create a new contact before proceeding with the update.
> Key considerations:
> - if the contact already exists, the response will return its existing string ID.
> - If the contact does not exist, it will be created automatically, and its assigned ID will follow the response format of the Create Contacts API—meaning it will be an integer.
> **Caution**: The endpoint is sensitive to race conditions for the same contact identifier. Simultaneous or near-simultaneous calls can result in conflicts. If you receive a `Contact with the external id already exists` message but no contact is created, please retry the operation.
**Notes:**
- The maximum payload size is 8 MB, therefore the maximum number of contacts per call depends on the amount of data per contact.
- The maximum batch size is 1000 contacts per call.
- Only use the values *1*, *2*, or *null* to update opt-in status. Boolean string literals are not supported. For details, see [Automated double opt-in program](https://help.emarsys.com/hc/en-us/articles/360006090693-Automated-double-opt-in-program) and the [Manage Double Opt-in for Contacts](docs/contact-use-cases/manage-opt-in-for-contacts.md) use case.
- Updating a contact is an idempotent method, meaning that it can be called multiple times with the same outcome. Note that as a `PUT` request, it replaces all contact information for the contact fields included in the request body (only for the contacts specified in the request), so please make sure that you either: a) include **only** the fields you want to update, or b) populate **all the current field values** and then **add a new value** to the fields that need to be updated.
- In case you are using the `setEmail` Web Extend command to identify your customers, whenever an update is done by your customers in their email addresses, please make sure to set the `predictUserID` and the `predictSecret` fields to `""` (empty) in the payload. This is done to make sure that a new Predict user ID is created for them as soon as the web behavior field updates take place, usually within 2 hours. Only in this 2-hour period are personalized recommendations not available to view.
- When using this endpoint to unsubscribe contacts from an email campaign, also do register the unsubscribe with the [/v2/email/unsubscribe](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NDU) call.
- If you want to update a **single-choice field**, use the `choice` identifier that you can find out via [List Available Choices of a Single-choice Field](reference/openapi.json/paths/~1v2~1field~1{fieldID}~1choice~1translate~1{languageId}/get). Do not use `sort_id` to specify a choice or a field. For further details, see our [help portal](https://help.emarsys.com/hc/en-us/articles/115004634689-end-user-guides-creating-custom-fields#field-type-attributes-and-values).
- Updating **multi-choice fields** is also possible. The following is a simple verification example for this scenario:
``
PUT https://api.emarsys.net/api/v2/contact/?create_if_not_exists=1
``
```json
{
"3": "myemail@gmail.com",
"8765": [
"foo",
"bar",
"baz",
"qux"
],
"key_id": "3"
}
```
See [Create Contacts](paths/~1v2~1contact/post) for more information on contact details.
> **Important:** Due to limitations of API specification languages, dynamic keys are not yet supported in query strings on the interactive demo page (**Try it out**). We are working on this issue.
**Tip:** You can use the [Postman Collection](https://raw.githubusercontent.com/emartech/developer-hub-public-assets/master/resources/EmarsysV2PostmanCollection.json) to test the endpoint.
**Important:** When [Exporting updated contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post), contacts that were updated through this endpoint will only be exported if their email address or opt-in status were updated.
operationId: updateContacts
produces:
- application/json
consumes:
- application/json
parameters:
- name: create_if_not_exists
in: query
description: 'If set to *1*, creates a new contact if it does not exist yet. If not set, defaults to *0*.'
type: integer
format: int32
enum:
- 0
- 1
- in: body
name: body
schema:
type: object
properties:
contact_list_id:
type: integer
description: |
The id of the contact list to add all the identifiable contacts to in the request payload. Must be an exisitng contact list.
contacts:
type: array
items:
type: object
properties:
'2':
type: string
'3':
type: string
key_id:
description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
oneOf:
- type: integer
- type: string
x-examples:
- '3'
required:
- key_id
x-examples:
- contact_list_id: 969
contacts:
- '2': Selvig
'3': erik.selvig@example.com
- '2': Boothby
'3': ian.boothby@example.com
- '2': Rhodes
'3': james.rhodes@example.com
- '2': Potts
'3': pepper.potts@example.com
key_id: '3'
schemes:
- https
responses:
'200':
description: Returns the `id` of the updated or created contacts.
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
data:
type: object
description: The requested data.
properties:
errors:
type: object
description: List of any errors that occurred during the update. The error message is returned with the value of the `key_id`.
ids:
type: array
description: Array of the `id`s of the contacts updated successfully.
items:
oneOf:
- type: string
- type: array
items:
type: string
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
'400':
description: |-
| Reply Code | Message | Description |
|--|--|--|
| 2010 | More contacts found with the external ID: `field_id` – `value` | More than one contact with the provided key field value exists in the database. A unique external key must be provided. Please note that using multiple identifiers is not possible via the API. If you need multiple identifiers, you need to use the Import page. |
| 2008 | No contact found with the external ID: `field_id` – `value` | No contact with the provided key field value exists in the database. The contact must be created; see Create a Contact. |
| 2004 | Cannot use id or uid as key on contact creation | IDs cannot be specified manually. |
| 2007 | Cannot set id or uid on contact creation | IDs cannot be specified manually. |
| 1000 | The request exceeded the maximum batch size 1,000 | Too many contacts were requested; contact creation is limited to 1,000. |
schema:
$ref: '#/definitions/default-response'
'2020':
description: ''
schema:
type: object
properties:
data:
type: string
replyCode:
type: integer
replyText:
type: string
description: 'Invalid contact list id: `contact_list_id`'
examples:
Batch mode for contact_list_id:
contact_list_id: '12345678'
contacts:
- '2': Rhodes
'3': james.rhodes@example.com
- '2': Potts
'3': pepper.potts@example.com
key_id: ....
Invalid contact list id:
data: ''
replyCode: 2020
replyText: 'Invalid contact list id: 8789789789789789789'
security:
- X-WSSE: []
/v2/contact/delete:
post:
summary: Delete Contacts
description: |-
Deletes a single or multiple contacts. If the provided identifier is not unique (such as email or custom field value), duplicate contacts are not deleted.
The maximum **batch** size is 1000 contacts per call.
**Important:** This action cannot be reverted, and removes all existing data associated with the contact. To *unsubscribe* contacts, set their opt-in status to *false* instead.
**Note:** Due to limitations of API specification languages, dynamic keys are indicated by curly brackets or by a regex pattern.
operationId: deleteContactsBackup
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
contact_list_id:
type: integer
description: The id of the contact list to delete all the identifiable contacts from.
key_id:
description: |-
Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.
**Tip:** If the key identifier is *3* (email), the `key_id` property can be omitted.
**Note:** If an external identifier (`eid`) is configured for your account, it can serve as the key identifier. This is an experimental feature, please contact Emarsys Support.
oneOf:
- type: integer
- type: string
'{keyFieldIdentifier}':
type: array
description: |-
Array of values of the key field identifier. If the identifier value is *3* (email), the `key_id` property can be omitted.
Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.
**Note:** If an external identifier (`eid`) is configured for your account, it can serve as the key identifier. This is an experimental feature, please contact Emarsys Support.
items:
type: string
required:
- '{keyFieldIdentifier}'
x-examples:
- '{keyFieldIdentifier}':
- UniqueIdentifier1
- UniqueIdentifier2
contact_list_id: 45678
key_id: '4427'
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See [Response Codes](docs/response-codes/error-codes.md) for details.'
properties:
data:
type: object
description: 'Contains the number of deleted contacts as well as any errors, if applicable.'
properties:
errors:
type: object
replyCode:
type: integer
description: The Emarsys response code. Successful requests return *0*.
default: 0
replyText:
type: string
description: Additional information on the status of the request.
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
'404':
description: ''
schema:
$ref: '#/definitions/default-response'
'2020':
description: ''
schema:
type: object
properties:
data:
type: string
replyCode:
type: integer
replyText:
type: string
description: 'Invalid contact list id: `contact_list_id`'
security:
- X-WSSE: []
/v2/contact/query/:
get:
summary: List Contact Data
description: |-
Returns a list of the values of the specified field as well as the related contact identifiers (`id`). See [Concepts](docs/before-you-start/concepts.md) for details.
**Example:** The field identifier *1* returns the first names of all contacts.
>***Tip:** You can use the [Postman Collection](https://raw.githubusercontent.com/emartech/developer-hub-public-assets/master/resources/EmarsysV2PostmanCollection.json) to test the endpoint.
operationId: listContactData
produces:
- application/json
parameters:
- $ref: '#/parameters/trait:offset:offset'
- $ref: '#/parameters/trait:limit10K:limit'
- name: excludeempty
in: query
description: |-
If `true`, contacts with a null or empty value in the specified field are not returned.
**Note:** Any value except for `true` is interpreted as false.
required: false
type: boolean
- name: return
in: query
description: Specifies the field identifier to filter contacts.
required: true
type: integer
- name: '{fieldId}'
in: query
description: |-
The field identifier and it's value to filter the result.
**Note:** Send an empty string as the field value to return fields with `null` value.
required: false
type: string
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
data:
type: object
description: The requested data.
properties:
result:
type: array
items:
type: object
properties:
id:
type: integer
description: 'The numeric contact identifier. For details, [concepts](docs/before-you-start/concepts.md).'
patternProperties:
'^[0-9]+':
type: string
description: The requested field identifier and its value.
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
'/v2/contact/query/?{keyId}={keyValue}':
get:
summary: Get Internal Contact Identifiers
description: |-
Returns the internal identifier of a contact by the specified field and its value. For details about contact identifiers, see [Concepts](docs/before-you-start/concepts.md).
**Important:** This endpoint requires indexed fields. When you select a `keyId`, it needs to have an index.
**Note:** As with [List Contact Data](reference/openapi.json/paths/~1v2~1contact~1query~1/get), the interactive demo page (Try it out) is not functional for this eddpoint. We are working on this issue.
operationId: getContactId
produces:
- application/json
parameters:
- name: keyValue
in: path
description: |-
The value of the key field to identify the contact.
**Note:** Specify array values by a comma-separated list. For example `98012=1,2,3,4`.
required: true
type: string
- name: keyId
in: path
description: The identifier of the key field to use. Must be indexed.
required: true
type: integer
- $ref: '#/parameters/trait:excludeEmptyResults:excludeempty'
- $ref: '#/parameters/trait:offset:offset'
- $ref: '#/parameters/trait:limit1M:limit'
- name: return
in: query
description: 'The identifier of the field to return along with the contact identifier. If not provided, only the contact identifier is returned.'
required: true
type: integer
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: The numeric contact identifier.
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
security:
- X-WSSE: []
/v2/contact/getdata:
post:
summary: Get Contact Data
description: |
Returns the field values of the contacts specified by either their internal identifiers or by a custom property.
It is recommended to use the `id` or `uid` fields to identify contacts in order to avoid conflicts when using a non-unique field, such as `email`.
For details about customer identifiers and properties, see [Concepts](docs/before-you-start/concepts.md).
**Note:** The maximum number of objects per request is 1000.
>When a contact is not found, the reply code is still `200`. The reply text makes this clear by the message: **No contact found**.
>
>If all contact identifiers given in a call fail to parse, the result will be ``false`` and **not** an array. Possible reasons for the ``false`` result:
>- incorrect contact ``id`` or ``key`` format
>- typo
>- contact ``id`` does not exist in the database
operationId: getContactData
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
fields:
type: array
items:
type: string
keyId:
description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
oneOf:
- type: integer
- type: string
keyValues:
type: array
items:
type: string
x-examples:
- fields:
- '1'
- '2'
- '3'
keyId: '3'
keyValues:
- steve.rogers@example.com
- peter.parker@example.com
schemes:
- https
responses:
'200':
description: This is an OK response.
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
data:
type: object
description: The requested data.
properties:
errors:
type: array
items:
type: object
result:
type: array
items:
type: object
properties:
id:
type: integer
description: 'The numeric contact identifier. For details, see [concepts](docs/before-you-start/concepts.md).'
uid:
type: string
description: 'The string contact identifier. For details, see [concepts](docs/before-you-start/concepts.md).'
patternProperties:
'^[0-9]+':
type: string
description: The field identifier and its value.
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
security:
- X-WSSE: []
/v2/contact/checkids:
post:
summary: Verify Internal Contact Identifiers
description: |-
Generates a list of existing contacts and errors indexed by the specified key identifier.
For details about contact identifiers, see [Concepts](docs/before-you-start/concepts.md).
Errors are collected in the following cases:
- The provided key identifier is invalid
- No contact is found
- More than one contact is found with the same key value
operationId: verifyContactInternalIdentifiers
produces:
- application/json
consumes:
- application/json
parameters:
- in: body
name: body
schema:
type: object
properties:
contact_list_id:
type: integer
description: The id of the contact list to add all the identifiable contacts to in the request payload.
external_ids:
description: |-
Filters the contacts by the values of the specified key field (`key_id`).
The accepted type depends on the key field type. For example, custom numeric fields require an integer, while multi-choice fields requre an array.
oneOf:
- type: array
items:
type: string
- type: string
- type: integer
get_multiple_ids:
type: boolean
description: Lists all internal contact identifiers if the request matches multiple external identifiers.
default: false
key_id:
description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
oneOf:
- type: string
- type: integer
required:
- external_ids
- key_id
x-examples:
- contact_list_id: 46714
external_ids:
- obadiah@example.com
- jinsen@example.com
- raza@example.com
key_id: '3'
schemes:
- https
responses:
'200':
description: ''
schema:
type: object
description: 'See the example or [Response Codes](docs/response-codes/error-codes.md) for details.'
additionalProperties: false
properties:
data:
type: object
description: The requested data.
properties:
errors:
type: object
description: A list of errors for contacts as key-value pairs of the specified key field values and their respective internal contact identifiers.
ids:
type: object
description: A list of contacts as key-value pairs of the specified key field values and their respective internal contact identifiers.
replyCode:
type: integer
description: 'The Emarsys [response code](docs/response-codes/error-codes.md).'
replyText:
type: string
description: 'The summary of the [response](docs/response-codes/error-codes.md).'
'400':
description: ''
schema:
$ref: '#/definitions/default-response'
'2020':
description: ''
schema:
type: object
properties:
data:
type: string
replyCode:
type: integer
replyText:
type: string
description: 'Invalid contact list id: `contact_list_id`'
security:
- X-WSSE: []
definitions:
default-response:
type: object
title: Default Response
description: |-
See the following documents for details on the error codes:
- [HTTP 200 errors](docs/response-codes/http-200-responses.md)
- [HTTP 400 errors](docs/response-codes/http-400-errors.md)
- [HTTP 401-429 errors](docs/response-codes/http-401-429-errors.md)
- [HTTP 500 errors](docs/response-codes/http-500-errors.md)
properties:
replyCode:
type: integer
description: 'The Emarsys response code. Successful requests return *0*; otherwise, see [errors](docs/response-codes/http-400-errors.md).'
default: 0
replyText:
type: string
description: Additional information on the status of the request.
data:
description: 'Contains the requested data, if applicable.'
oneOf:
- type: string
- type: integer
- x-nullable: true
- type: object
properties:
'':
type: object
x-examples:
- replyCode: 0
replyText: OK
data: {}
parameters:
'trait:filter:filter':
name: filter
in: query
type: string
'trait:limit10K:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 10000
maximum: 10000
minimum: 1
'trait:offset:offset':
name: offset
in: query
description: Specifies an offset for pagination. The offset of the first record is *0*.
type: integer
default: 0
'trait:limit1M:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 1000000
maximum: 1000000
minimum: 1
'trait:interval:start_date':
name: start_date
in: query
description: |-
Returns results from the specified date.
**Accepted formats:** YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD
type: string
'trait:interval:end_date':
name: end_date
in: query
description: |-
Returns results until the specified date.
**Accepted formats:** YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DD
type: string
'trait:excludeEmptyResults:excludeempty':
name: excludeempty
in: query
description: |-
If `true`, contacts with a null or empty value in the specified field are not returned.
**Note:** Any value except for `true` is interpreted as false.
type: boolean
'trait:limit10M:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 10000000
maximum: 10000000
minimum: 1
'trait:limit1MRequired:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
required: true
type: integer
default: 1000000
maximum: 1000000
minimum: 1
'trait:limit1K:limit':
name: limit
in: query
description: Specifies the maximum number of records to return.
type: integer
default: 1000
maximum: 1000
minimum: 1
securityDefinitions:
X-WSSE:
type: apiKey
name: X-WSSE
in: header