swagger: '2.0' info: title: Emarsys Core API - Fields endpoint batch description: In this batch you may find endpoints related to fields. version: v2 host: api.emarsys.net basePath: /api schemes: - https paths: /v2/field: post: summary: Create a Field description: |- Creates a new field in the contact database. Please note that you cannot create single- or multi-choice fields via the API, nor can you create more than one field at a time. **Note:** The endpoint replicates the functionality of the **Field Generator** in the Emarsys application. To manage fields, go to **Admin** > **Field Editor** > **Create Field**. operationId: createField produces: - application/json consumes: - application/json parameters: - in: body name: body schema: type: object properties: name: type: string description: The unique name of the new field. application_type: type: string enum: - shorttext - longtext - largetext - date - url - numeric description: |- The type of the new field. **Supported values:** | Type | Description | | --- | --- | | shorttext | Text field, maxiumum 60 characters | |longtext| Text field, maximum 255 characters | |largetext| Text field, no limitations | |date| Date field | |url| URL field | |numeric| Numeric field, maxiumum 24 digits | **Note:** Single- and multichoice fields are not supported. required: - name - application_type x-examples: - name: The name of the new field application_type: shorttext 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: replyCode: type: integer description: 'The Emarsys [response code](docs/response-codes/error-codes.md).' format: int32 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 identifier of the new field. '400': description: '' schema: $ref: '#/definitions/default-response' security: - X-WSSE: [] '/v2/field/translate/{languageId}': get: summary: List Available Fields description: Generates a list of the available contact fields. operationId: listAvailableFields produces: - application/json parameters: - name: languageId in: path description: |- The two-letter ISO 639-1 language code. See available [language codes](docs/appendix/language-codes.md). **Note:** Using the `/field` URI without the `translate/{languageId}` path returns the default English fields. required: true type: string default: en maxLength: 2 minLength: 2 enum: - ar - bg - bp - cn - cz - de - dk - el - en - es - et - fi - fr - he - hi - hr - hu - it - jp - ko - lt - lv - mk - mo - mx - nl - 'no' - pl - pr - ro - ru - sc - sk - sl - sr - sv - th - tr - uk - vi 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: replyCode: type: integer description: 'The Emarsys [response code](docs/response-codes/error-codes.md).' format: int32 replyText: type: string description: 'The summary of the [response](docs/response-codes/error-codes.md).' data: type: array description: The requested data. items: type: object properties: id: type: string description: The field identifier. name: type: string description: The field name. application_type: type: string description: The field type. string_id: type: string description: identifier of the string examples: example-1: replyCode: 0 replyText: OK data: - id: 14 name: Country or region application_type: singlechoice string_id: country '400': description: '' schema: $ref: '#/definitions/default-response' examples: example-1: replyCode: 0 replyText: OK data: {} security: - X-WSSE: [] '/v2/field/{fieldID}/choice/translate/{languageId}': get: summary: List Available Choices of a Single-choice Field description: |- Gives you a list of all available options for any given single or multi-choice field. **Tip**: See [List customer forms](/reference/openapi.json/paths/~1v2~1form/get) for how to list forms and newsletters. If you want to update a contact's single choice field, use this endpoint to find out the relevant `choice` identifier. operationId: listAvailableChoicesOfASingleField produces: - application/json parameters: - name: fieldID in: path description: The field identifier. required: true type: integer - name: languageId in: path description: |- The two-letter ISO 639-1 language code. See available [language codes](docs/appendix/language-codes.md). **Note:** Using the `/field/{fieldId}/choice` URI without the `translate/{languageId}` path returns the default English fields. required: true type: string default: en maxLength: 2 minLength: 2 enum: - ar - bg - bp - cn - cz - de - dk - el - en - es - et - fi - fr - he - hi - hr - hu - it - jp - ko - lt - lv - mk - mo - mx - nl - 'no' - pl - pr - ro - ru - sc - sk - sl - sr - sv - th - tr - uk - vi 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: replyCode: type: integer description: 'The Emarsys [response code](docs/response-codes/error-codes.md).' format: int32 replyText: type: string description: 'The summary of the [response](docs/response-codes/error-codes.md).' data: type: array items: type: object properties: id: type: string choice: type: string bit_position: type: integer description: |- The position of an element in a multi-choice field. **Note:** The `bit_position` value of a choice is not the same as the choice `id`. '400': description: '' schema: $ref: '#/definitions/default-response' security: - X-WSSE: [] /v2/field/choices: get: summary: List Available Choices of a Multiple-choice Field description: |- Generates a list of all available options for the specified multi-choice field. **Tip**: See [List customer forms](/reference/openapi.json/paths/~1v2~1form/get) for how to list forms and newsletters. operationId: listAvailableChoicesOfMultipleField produces: - application/json parameters: - name: fields in: query description: The field identifier. required: true type: integer - name: language in: query description: |- The two-letter ISO 639-1 language code. For available language codes, see [Language codes](docs/appendix/language-codes.md). **Note:** Using the `/field/{fieldId}/choice` URI without the `translate/{languageId}` path returns the default English fields. required: true type: string default: en enum: - ar - bg - bp - cn - cz - de - dk - el - en - es - et - fi - fr - he - hi - hr - hu - it - jp - ko - lt - lv - mk - mo - mx - nl - 'no' - pl - pr - ro - ru - sc - sk - sl - sr - sv - th - tr - uk - vi 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: replyCode: type: integer description: 'The Emarsys [response code](docs/response-codes/error-codes.md).' format: int32 replyText: type: string description: 'The summary of the [response](docs/response-codes/error-codes.md).' data: type: object properties: '{fieldId}': type: array items: type: object properties: id: type: string choice: type: string bit_position: type: integer description: |- The position of an element in a multi-choice field. **Note:** The `bit_position` value of a choice is not the same as the choice `id`. '400': description: '' schema: $ref: '#/definitions/default-response' security: - X-WSSE: [] '/v2/field/{fieldId}': delete: summary: Delete a Field description: |- Deletes a custom contact field. **Important:** This action cannot be reverted, and removes all existing contact data associated with the field. operationId: deleteField produces: - application/json parameters: - name: fieldId in: path description: The identifier of the field to be deleted. required: true type: integer schemes: - https responses: '200': description: '' schema: $ref: '#/definitions/default-response' '400': description: '' schema: $ref: '#/definitions/default-response' '404': description: '' schema: $ref: '#/definitions/default-response' security: - X-WSSE: [] /v2/contact/last_change: post: summary: Query Field Changes description: |- > #### IMPORTANT > **Please note that this endpoint has been decommisioned as of November 10, 2023.** > > **The endpoint and its documentation will be fully removed on November 10, 2024.** Returns information about the latest change of the specified fields, inclucing the change timestamp, as well as the old and the current values. operationId: queryFieldChanges produces: - application/json consumes: - application/json parameters: - in: body name: body schema: type: object properties: keyId: description: |- 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. oneOf: - type: integer - type: string keyValues: type: array description: The array of values of the specific key field. items: type: string fieldId: type: integer description: The field identifier. required: - keyId - keyValues - fieldId x-examples: - keyId: 3 keyValues: - test_1@emarsys.com - test_2@emarsys.com - test_3@emarsys.com fieldId: 31 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: replyCode: type: integer description: 'The Emarsys [response code](docs/response-codes/error-codes.md).' format: int32 replyText: type: string description: 'The summary of the [response](docs/response-codes/error-codes.md).' data: type: object description: The requested data. properties: result: type: object patternProperties: ^\w+: type: object description: 'The value of the specified key field. For example, the email address of the contact.' properties: old_value: description: The previous value of the field. oneOf: - type: integer - type: string current_value: description: The current value of the field. oneOf: - type: integer - type: string time: type: string description: The date and time of the last modification. '400': description: '' schema: $ref: '#/definitions/default-response' 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