Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Emarsys Contact API
version: v2
description: 'Operations tagged Contact across 3 of this provider''s published API definitions: emarsys-contact-and-email-data-openapi.yml, emarsys-contacts-openapi.yml, emarsys-fields-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emarsys.net/api
tags:
- name: Contact
paths:
/v2/contact/getchanges:
post:
summary: Export Updated Contacts
description: "Exports the specified fields of contacts that have been modified within a certain time period. The changes must come from the specified form or API source to be included.\n\n| SOURCE | |UPDATED FIELDS | | \n| --- | --- | --- | --- |\n| | **Email address** | **Opt-in status** | **Other** | \n| **Forms (`register.php`)** | contact exported | contact exported | contact exported |\n| **API: [Contact update](reference/openapi.json/paths/~1v2~1contact~1/put)** | contact exported | contact exported | contact exported |\n| **[Data import](https://help.emarsys.com/hc/en-us/articles/360013356254-Overview-Data-Import-Overview)** | contact **not** exported | contact **not** exported | contact **not** exported |\n\n**Important:** \n\nThe results are saved as a CSV file that you can access in multiple ways.\n- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.\n- Exports flagged as `sftp` can be accessed via SFTP.\n\n**Implementation**\n\n You can implement this method as follows:\n -Poll the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint to track the export status. When done, access the file at the [Download Export Data](reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get) endpoint.\n- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response. Failures are retried 5 times, with a one-minute wait between each try.\n\n\n**Notes**\n- As we are using a proxy for SFTP traffic, it is not necessary to whitelist any IPs on our side.\n- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or SFTP access, contact Emarsys support.\n\n**Example**\n```csv\nuser_id;First Name;Last Name;E-Mail;Company\n8019189;user3;test_import;test1@emarsys.com;\n49036141;user3;test_import;test1@emarsys.com;\n50123406;user3;test_import;test1@emarsys.com;\n85600590;user3;test_import;test1@emarsys.com;\n```"
operationId: exportChangedContacts
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
additionalProperties: false
properties:
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).
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/default-response'
security:
- X-WSSE: []
servers:
- url: https://api.emarsys.net/api
requestBody:
content:
application/json:
schema:
type: object
properties:
distribution_method:
type: string
enum:
- sftp
- local
description: 'The method to access the export.
**Note:** If the `sftp` option is selected, you must provide the SFTP configuration settings in the `ftp_settings` parameter.'
origin:
type: string
enum:
- form
- api
- all
description: Indicates which platform triggered the change.
origin_id:
type: string
description: 'The origin identifier. The default value *0* indicates no source. Other values specify a custom contact source.
| Origin Type | Identifier |
| --- | --- |
| Form | Form identifier |
| API | *0* |'
default: 0
time_range:
type: array
description: 'A two-element array that contains the *start date* and *end date* values.
**Accepted format:** YYYY-MM-DD
**datetime** format is available upon request, turn to support to enable it.'
items:
type: string
contact_fields:
type: array
description: 'The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |'
minItems: 1
maxItems: 20
items:
type: integer
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: The language of the export. The default is the account’s language. For the list of language codes, see [language codes](docs/appendix/language-codes.md).
pattern: ^[a-z]{2}
minLength: 2
maxLength: 2
ftp_settings:
type: object
description: Mandatory distribution settings parameter, if the `distribution_method` is `ftp`. For `local`, these settings are ignored.
properties:
host:
type: string
description: The address of the FTP host.
format: uri
port:
type: string
description: The port of the FTP host.
username:
type: string
description: The login user name.
password:
type: string
description: The login password.
folder:
type: string
description: The folder on the FTP that contains the export file. Optional.
notification_url:
type: string
description: 'Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.'
format: uri
required:
- distribution_method
- origin
- origin_id
- time_range
- contact_fields
x-examples:
- distribution_method: sftp
origin: form
origin_id: '123'
time_range:
- '2012-02-09'
- '2012-04-02'
contact_fields:
- 1
- 3
- 106533
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: https://www.example.com/
port: '1234'
username: user
password: pass
folder: path/of/a/folder
tags:
- Contact
servers:
- url: https://api.emarsys.net/api
/v2/contact/getregistrations:
post:
summary: Export Contact Registrations
description: "Exports the specified fields of contacts registered through an Emarsys form within the specified time period as a CSV file.\n\n**Tip:** If you want to export registrations from other sources, use the [Export Updated Contacts](/reference/openapi.json/paths/~1v2~1contact~1getchanges/post) endpoint.\n\n\n**Important:** \n\nThe results are saved as a CSV file that you can access in multiple ways.\n- Exports flagged as `local` are stored on the Emarsys server that you can download via WebDAV or an API call.\n- Exports flagged as `sftp` can be accessed via SFTP.\n\n**Implementation**\n\nou can implement this method as follows:\n- Poll the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint to track the export status. When done, access the file at the [Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get) endpoint.\n- Set the `notification_url` parameter to implement a callback mechanism. When the export is ready, a request is sent to the provided URL with the same payload as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response. Failures are retried 5 times, with a one-minute wait between each try.\n\n**Notes**\n- WebDAV access must be enabled first, and requires authentication to use. For a WebDAV account or SFTP access, contact Emarsys support.\n\n**Example**\n```csv\nuser_id;First Name;Last Name;E-Mail;Company;last update\n135369573;user3;test_import;test1@emarsys.com;;\n171879718;user3;test_import;test1@emarsys.com;;\n183453150;user3;test_import;test1@emarsys.com;;\n188925627;user3;test_import;test1@emarsys.com;;\n```"
operationId: exportContactRegistrations
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
additionalProperties: false
properties:
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).
data:
type: object
description: The requested data.
properties:
id:
type: integer
description: The export identifier that you can use to poll export status ([Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get)) and download the export file ([Download Export Data](/reference/openapi.json/paths/~1v2~1export~1{exportId}~1data/get)).
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/default-response'
security:
- X-WSSE: []
servers:
- url: https://api.emarsys.net/api
requestBody:
content:
application/json:
schema:
type: object
properties:
distribution_method:
type: string
enum:
- local
- sftp
description: 'The method to access the export.
**Note:** If the `ftp` option is selected, provide the mandatory FTP configuration settings in the `ftp_settings` parameter.'
contactlist:
type: integer
description: The identifier of the contact list to filter the results.
time_range:
type: array
description: 'A two-element array that contains the *start date* and *end date* values.
**Accepted format:** YYYY-MM-DD HH-SS'
minItems: 2
maxItems: 2
items:
type: string
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}
with_timestamp:
type: integer
enum:
- 0
- 1
description: Determines whether the registration timestamp is included in the export.
default: 1
contact_fields:
type: array
description: 'The field identifiers to include in the export. The following fields cannot be exported:
| Field Identifier | Description |
| --- | --- |
| 27 | Average length of visit |
| 28 | Average pages per day |
| 29 | Last mail received |
| 32 | User status |
| 33 | Contact source |'
minItems: 1
maxItems: 20
items:
type: integer
delimiter:
type: string
enum:
- ','
- ;
description: The delimiter character to be used in the CSV export.
default: ','
add_field_names_header:
type: integer
enum:
- 0
- 1
description: Determines whether to insert a header row into the CSV file.
default: 1
language:
type: string
description: The language of the export. The default is the account’s language. For the list of language codes, see [language codes](docs/appendix/language-codes.md).
pattern: ^[a-z]{2}
minLength: 2
maxLength: 2
sftp_settings:
type: object
description: Mandatory distribution settings parameter, if the `distribution_method` is `sftp`. For `local`, these settings are ignored.
properties:
host:
type: string
port:
type: string
username:
type: string
password:
type: string
folder:
type: string
notification_url:
type: string
description: 'Sends a request to the provided URL when the export is ready.
Set this parameter to implement a callback mechanism instead of polling the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) endpoint.
**Note:** The payload is the same as the [Check Export Status](/reference/openapi.json/paths/~1v2~1export~1{exportId}/get) response.'
required:
- distribution_method
- time_range
- contact_fields
x-examples:
- distribution_method: ftp
contactlist: 111111111
time_range:
- '2012-02-09'
- '2012-04-02'
contact_fields:
- 1
- 3
- 106533
delimiter: ;
add_field_names_header: 1
language: en
ftp_settings:
host: www.example.com
port: '1234'
username: user
password: pass
folder: path/of/a/folder
tags:
- Contact
servers:
- url: https://api.emarsys.net/api
/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).\n\n> **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.\n\n**Note:**\n\nThe 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:\n ```\n {\n \"key_id\" : \"3\",\n \"3\" : \"johndoe@example.com\",\n \"1\" : \"John\",\n \"2\" : \"Doe\"\n}\n```\n\n**To consider:**\n- The maximum payload size is 10 MB, therefore the maximum number of new contacts per call depends on the amount of data per contact.\n- The maximum batch size is 1000 contacts per call.\n\n**Note:** Due to limitations of API specification languages, dynamic keys are indicated by curly brackets or by a regex pattern.\n\n**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
responses:
'200':
description: ''
content:
application/json:
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: ''
content:
application/json:
schema:
$ref: '#/components/schemas/default-response_2'
'2020':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: string
replyCode:
type: integer
replyText:
type: string
description: 'Invalid contact list id: `contact_list_id`'
security:
- X-WSSE: []
servers:
- url: https://api.emarsys.net/api
requestBody:
content:
application/json:
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
tags:
- Contact
servers:
- url: https://api.emarsys.net/api
v2/contact/:
put:
summary: Update Contacts
description: "Updates multiple contacts, or creates them if they do not exist.\n\nIt 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`.\n\nYou 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.\n\nFor details, see [Concepts](docs/before-you-start/concepts.md).\n\n> **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.\n\n> **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. \n> Key considerations:\n> - if the contact already exists, the response will return its existing string ID.\n> - 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.\n\n\n> **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.\n\n**Notes:**\n- The maximum payload size is 8 MB, therefore the maximum number of contacts per call depends on the amount of data per contact.\n- The maximum batch size is 1000 contacts per call.\n- 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.\n- 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.\n- 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.\n- 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. \n- 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). \n- Updating **multi-choice fields** is also possible. The following is a simple verification example for this scenario:\n\n``\nPUT https://api.emarsys.net/api/v2/contact/?create_if_not_exists=1\n``\n```json\n{\n \"3\": \"myemail@gmail.com\",\n \"8765\": [\n \"foo\",\n \"bar\",\n \"baz\",\n \"qux\"\n ],\n \"key_id\": \"3\"\n}\n```\n\nSee [Create Contacts](paths/~1v2~1contact/post) for more information on contact details.\n\n> **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.<br><br>**Tip:** You can use the [Postman Collection](https://raw.githubusercontent.com/emartech/developer-hub-public-assets/master/resources/EmarsysV2PostmanCollection.json) to test the endpoint.\n\n**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
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*.
schema:
type: integer
format: int32
enum:
- 0
- 1
responses:
'200':
description: Returns the `id` of the updated or created contacts.
content:
application/json:
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. |'
content:
application/json:
schema:
$ref: '#/components/schemas/default-response_2'
'2020':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: string
replyCode:
type: integer
replyText:
type: string
description: 'Invalid contact list id: `contact_list_id`'
security:
- X-WSSE: []
servers:
- url: https://api.emarsys.net/api
requestBody:
content:
application/json:
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'
tags:
- Contact
servers:
- url: https://api.emarsys.net/api
/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
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/openapi/emarsys-contact-api-openapi.yml