swagger: '2.0'
info:
  title: Emarsys Core API - Contact lists endpoint batch
  description: In this batch you may find endpoints related to contact lists.
  version: v2
host: api.emarsys.net
basePath: /api
schemes:
  - https
paths:
  /v2/contactlist:
    post:
      summary: Create a Contact List
      description: |
        Creates or updates a contact list with the provided parameters. 
      operationId: createContactList
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              key_id:
                description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
                default: 3
                oneOf:
                  - type: string
                  - type: integer
              name:
                type: string
                description: The unique name of the contact list.
              description:
                type: string
                description: Additional information about the contact list.
              external_ids:
                description: |-
                  List of contact identifiers to be inserted.

                  **Format:**
                  | Value | Type | Example |
                  | --- | --- | --- |
                  | Simple | string or integer | [<br>    "thor@example.com",<br>    "odin@example.com",<br>    "loki@example.com"<br> ] |
                  | Multichoice | array | [<br>    [1,2,3],<br>    [2,3],<br>    [1,4]<br>] |
                oneOf:
                  - type: integer
                  - type: string
                  - type: array
            required:
              - key_id
              - name
              - external_ids
            x-examples:
              - key_id: '3'
                name: asgard_protectors
                description: those who fight for Asgard
                external_ids:
                  - thor@example.com
                  - odin@example.com
                  - loki@example.com
      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 contact list identifier.
                  errors:
                    type: object
                    description: |-
                      Details any contacts not added to the list, expressed as an array that contains the error code and reason.

                      **Note:** The `errors` property is not included if the contact list is empty. If the contact list contains contacts, but no error occurred, the `errors` property is an empty array.
          examples:
            example-1:
              replyCode: -2147483648
              replyText: string
              data:
                id: 0
                errors: {}
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
    get:
      summary: List Contact Lists
      description: Returns a list of the available contact lists.
      operationId: listContactLists
      produces:
        - application/json
      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
                      description: Contact list identifier
                    name:
                      type: string
                      description: Contact list name
                    created:
                      type: string
                      description: The date of creation.
                    type:
                      type: integer
                      description: 'Note: This is a standard response, reserved for future use.'
                      default: 0
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/rename':
    post:
      summary: Rename a Contact List
      description: Renames an existing contact list.
      operationId: renameContactList
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - in: body
          name: body
          schema:
            type: object
            properties:
              name:
                type: string
                description: The new unique name of the contact list.
            required:
              - name
            x-examples:
              - name: blade
      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 contact list identifier.
                  name:
                    type: string
                    description: The new name of the contact list.
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/replace':
    post:
      summary: Replace a Contact List
      description: Overwrites an existing contact list.
      operationId: replaceContactList
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - in: body
          name: body
          schema:
            type: object
            properties:
              key_id:
                description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
                default: 3
                oneOf:
                  - type: string
                  - type: integer
              external_ids:
                description: |-
                  List of contact identifiers to be included.

                  **Format:**
                  | Value | Type | Example |
                  | --- | --- | --- |
                  | Simple | string or integer | [<br>    "thor@example.com",<br>    "odin@example.com",<br>    "loki@example.com"<br> ] |
                  | Multichoice | array | [<br>    [1,2,3],<br>    [2,3],<br>    [1,4]<br>] |
                oneOf:
                  - type: integer
                  - type: string
                  - type: array
            required:
              - key_id
              - external_ids
            x-examples:
              - key_id: '3'
                external_ids:
                  - natasha.romanoff@example.com
                  - loki@example.com
      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).'
              replyText:
                type: string
                description: 'The summary of the [response](docs/response-codes/error-codes.md).'
              data:
                type: object
                description: The requested data.
                properties:
                  inserted_contacts:
                    type: integer
                    description: The number of contacts successfully added to the list.
                  errors:
                    type: object
                    description: 'Details any contacts not added to the list, expressed as an array that contains the error code and reason.'
                    properties:
                      loki@example.com:
                        type: object
                        properties:
                          '2008':
                            type: string
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/deletelist':
    post:
      summary: Delete a Contact List
      description: |-
        Deletes a contact list.

        **Note:** Contacts in the list are not affected.

        **Warning:** If a contact list is used in a combined segment, you cannot delete it (error  ``400``, reply ``3008``).
      operationId: deleteContactList
      produces:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          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/contactlist/{listId}/add':
    post:
      summary: Add Contacts to a Contact List
      description: Adds new contacts to an existing contact list.
      operationId: addContactsToContactList
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - in: body
          name: body
          schema:
            type: object
            properties:
              key_id:
                description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
                default: 3
                oneOf:
                  - type: string
                  - type: integer
              external_ids:
                description: |-
                  List of contact identifiers to be inserted.

                  **Format:**
                  | Value | Type | Example |
                  | --- | --- | --- |
                  | Simple | string or integer | [<br>    "thor@example.com",<br>    "odin@example.com",<br>    "loki@example.com"<br> ] |
                  | Multichoice | array | [<br>    [1,2,3],<br>    [2,3],<br>    [1,4]<br>] |
                oneOf:
                  - type: integer
                  - type: string
                  - type: array
            required:
              - key_id
              - external_ids
            x-examples:
              - key_id: '3'
                external_ids:
                  - thor@example.com
                  - odin@example.com
                  - loki@example.com
      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:
                  inserted_contacts:
                    type: integer
                    description: The number of contacts successfully added to the list.
                  errors:
                    type: object
                    description: 'Details any contacts not added to the list, expressed as an array that contains the error code and reason.'
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/count':
    get:
      summary: Count Contacts in a Contact List
      description: Returns the number of contacts in a contact list.
      operationId: countContactsInContactLict
      produces:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          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:
              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: integer
                description: The number of contacts in the contact list.
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/contacts':
    get:
      summary: List Contacts in a Contact List
      description: |-
        <!-- theme: warning -->
        > #### Important!
        >
        > Please note that this endpoint is now deprecated. It will be decommisioned in December 2024.
        >
        > We recommend using the [Fetch contacts in a contact list](https://dev.emarsys.com/docs/core-api-reference/20nck8oujcus8-fetch-contacts-in-a-contact-list) endpoint instead.

        Returns a list of contacts and their identifiers (`id`) in a contact list.

        **Example**

        https://api.emarsys.net/api/v2/contactlist/123456789/contacts/?limit=100000&offset=0
      operationId: listContactsInContactList
      produces:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - $ref: '#/parameters/trait:offset:offset'
        - $ref: '#/parameters/trait:limit1M:limit'
      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).'
              replyText:
                type: string
                description: 'The summary of the [response](docs/response-codes/error-codes.md).'
              data:
                type: array
                description: The list of contact identifiers (`id`) in the contact list.
                items:
                  type: string
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      deprecated: true
      security:
        - X-WSSE: []
  '/v2/contactlist/{contactlistId}/contactIds':
    get:
      summary: Fetch Contacts in a Contact List
      description: |-
        Returns a list of contact identifiers (`contactIds`) from the contact list.

        **Example**

        https://api.emarsys.net/api/v2/contactlist/123456789/contactIds?$skiptoken=330&$top=10000
      operationId: fetchContactsInContactList
      produces:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - name: $top
          in: query
          description: Number of contact ids to be batched together in the response.
          required: false
          type: integer
          default: 10000
          maximum: 100000
          minimum: 1
        - name: $skiptoken
          in: query
          description: A token which specifies the position of the page to be fetched.
          required: false
          type: integer
          default: 0
      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:
              value:
                type: array
                description: List of contact ids.
                x-examples:
                  - - 1
                    - 2
                    - 3
              next:
                type: string
                description: 'Path that can be used to obtain the next result chunk. In case `next` is null in the response, then this was the last chunk, no further chunks can be obtained.'
                x-examples:
                  - /contactlist/330/contactIds?$skiptoken=750&$top=1000
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/contacts/data':
    get:
      summary: Get Contact Data in a Contact List
      description: |-
        <!-- theme: warning -->
        > #### Important!
        >
        > Please note that this endpoint is now deprecated. It will be decommisioned in December 2024.
        >
        > As a replacement, we recommend using the [Fetch contacts in a contact list](https://dev.emarsys.com/docs/core-api-reference/20nck8oujcus8-fetch-contacts-in-a-contact-list) endpoint first and then the [Get contact data](https://dev.emarsys.com/docs/core-api-reference/blzojxt3ga5be-get-contact-data) endpoint.
        Returns the data of the specified contacts in a contact list.
      operationId: getContactDataInContactList
      produces:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - name: fields
          in: query
          description: |-
            Specifies the fields by identifier or name to include in the returned result.

            Multiple fields must be separated by a comma. For example `1,2,3` or `email,first_name`.
          required: true
          type: string
        - name: limit
          in: query
          description: Specifies the maximum number of records to return.
          type: integer
          default: 1000
          maximum: 1000000
          minimum: 1
        - $ref: '#/parameters/trait:offset:offset'
      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).'
              replyText:
                type: string
                description: 'The summary of the [response](docs/response-codes/error-codes.md).'
              data:
                type: object
                description: The requested data.
                patternProperties:
                  '^[0-9]+':
                    type: object
                    description: The contact identifier (`id`).
                    properties:
                      fields:
                        type: object
                        properties:
                          id:
                            type: string
                            description: The contact identifier (`id`).
                          uid:
                            type: string
                            description: The contact identifier (`uid`).
                        patternProperties:
                          '^[0-8]':
                            description: The requested field and its value.
                            oneOf:
                              - type: string
                              - type: integer
                              - type: array
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      deprecated: true
      security:
        - X-WSSE: []
  '/v2/contactlist/{listId}/delete':
    post:
      summary: Remove Contacts from a Contact List
      description: |-
        Removes contacts from an existing contact list.

        **Note:** At most 10,000 contacts can be deleted by each request.
      operationId: removeContactsFromContactList
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: listId
          in: path
          description: The contact list identifier.
          required: true
          type: integer
        - in: body
          name: body
          schema:
            type: object
            properties:
              key_id:
                description: 'Identifies the contact by their `id`, `uid`, or the name/integer id of a custom field, such as `email`.'
                default: 3
                oneOf:
                  - type: string
                  - type: integer
              external_ids:
                description: |-
                  List of contact identifiers to be inserted.

                  **Format:**
                  | Value | Type | Example |
                  | --- | --- | --- |
                  | Simple | string or integer | [<br>    "thor@example.com",<br>    "odin@example.com",<br>    "loki@example.com"<br> ] |
                  | Multichoice | array | [<br>    [1,2,3],<br>    [2,3],<br>    [1,4]<br>] |
                oneOf:
                  - type: integer
                  - type: string
                  - type: array
            required:
              - key_id
              - external_ids
      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).'
              replyText:
                type: string
                description: 'The summary of the [response](docs/response-codes/error-codes.md).'
              data:
                type: object
                description: The requested data.
                properties:
                  deleted_contacts:
                    type: integer
                    description: The number of contacts successfully removed from the list.
                  errors:
                    type: object
                    description: 'Details any contacts not removed from the list, expressed as an array that contains the error code and reason.'
        '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
security:
  - X-WSSE: []