openapi: 3.0.3
info:
  title: Contacts
  description: 'Create, Get, update, and delete contacts. Use this API to look up contacts

    by identifier, perform full or partial updates on a single contact, bulk-import

    collections of contacts asynchronously, and bulk-delete contacts. When listing

    contacts you can filter by contact status, list subscription status, list

    membership, segment, or creation and modification date. Each contact can carry

    data fields, channel properties (email, SMS, WhatsApp), list memberships,

    marketing preferences, and consent records.'
  version: 3.4.3
externalDocs:
  description: Learn more about Dotdigital APIs
  url: https://developer.dotdigital.com
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      description: The Dotdigital region id your account belongs to
      enum:
      - r1
      - r2
      - r3
      default: r1
security:
- basicAuth: []
paths:
  /contacts/v3:
    get:
      summary: Get contacts based on your criteria
      description: 'Get contacts based on criteria you specify. Contacts are returned with full data, specified data fields, or key information and identifiers only.<br/><br/>


        *Note: All data is returned in ascending order*'
      operationId: getContacts
      parameters:
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      - name: data-fields
        in: query
        description: Contact data is returned with a minimum of **contactId** and any associated **identifiers**. Use this field to specify any additional data fields you want to return. Enter a pipe delimited string of the contact data fields required or **[[ALL]]** to Get all data fields.
        required: false
        style: pipeDelimited
        explode: false
        schema:
          type: array
          example:
          - FIRSTNAME
          - LASTNAME
          - FULLNAME
          - GENDER
          - POSTCODE
          items:
            type: string
      - name: include
        in: query
        description: Specify additional data sets associated with the contact to include in the returned data.
        required: false
        style: pipeDelimited
        explode: false
        schema:
          type: array
          example:
          - preferences
          - lists
          items:
            type: string
            enum:
            - channelProperties
            - lists
            - preferences
            - consentRecords
      - name: ~created
        in: query
        description: 'Filter by created date.<br/>

          ***Note:***

          * The date must be in ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601))

          * Can''t be used in conjunction with the **~modified** parameter.'
        schema:
          pattern: ^gte::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$
          type: string
        examples:
          Greater than or equal to created date:
            value: gte::2021-12-17T00:00:00Z
      - name: ~modified
        in: query
        description: 'Filter by last modified date.<br/>

          ***Note:***

          * The date must be in ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601))'
        schema:
          pattern: ^gte::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$
          type: string
        examples:
          Greater than or equal to modified date:
            value: gte::2021-12-17T00:00:00Z
      - name: ~listId
        in: query
        description: 'Filter by a specific list.<br/>

          ***Note:***

          * Can''t be used in conjunction with the **~segmentId** parameter.'
        schema:
          type: integer
        example: 54321
      - name: ~segmentId
        in: query
        description: 'Filter by a specific segment.<br/>

          ***Note:***

          * Can''t be used in conjunction with the **~listId** parameter.'
        schema:
          type: integer
        example: 12345
      - name: limit
        in: query
        description: Maximum number of records to retrieve per page
        schema:
          maximum: 5000
          minimum: 1
          type: integer
          format: int32
          example: 1000
      - name: marker
        in: query
        description: Pagination marker to retrieve the data from
        schema:
          type: string
          example: RXhhbXBsZSBhbXJrZXIgdmFsdWU=
      responses:
        '200':
          description: Contacts retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidFilter
                description: The filter value '2022-08-01T00:00:00Z' is invalid
        '401':
          description: Unauthorized
    post:
      summary: Create a contact
      description: Creates a contact if the identifiers passed are unique in the account then a new contact will be created, otherwise it will fail the call with a 409.
      operationId: createContact
      parameters:
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      requestBody:
        description: Contact data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createContactRequest'
        required: true
      responses:
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidId
                description: The id value '123646' is invalid for the identifier 'email'
        '401':
          description: Unauthorized
        '409':
          description: Identifier conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:idAlreadyExists
                description: The id value 'jane.doe@emailsim.io for the identifier 'email' already exists. All identifiers must be unique!
  /contacts/v3/delete:
    post:
      summary: Delete multiple contacts
      description: Async deletes multiple contacts using whichever identifier you wish.
      operationId: deleteContacts
      parameters:
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      requestBody:
        description: The contact references you want to delete
        content:
          application/json:
            schema:
              maxItems: 5000
              minItems: 1
              type: array
              items:
                $ref: '#/components/schemas/contactIdentifier'
        required: true
      responses:
        '202':
          description: Delete request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_202'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:noContactsSpecified
                description: You must specifiy 1 or more contacts to be deleted!
        '401':
          description: Unauthorized
        '429':
          description: Too many bulk delete jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:tooManyBulkDeleteJobs
                description: Your bulk delete request cannot be accepted as too many bulk delete jobs are being processed for you account. Please wait for a bulk delete job to complete and then resubmit.
  /contacts/v3/delete/{deleteId}:
    get:
      summary: Get the status of a delete contacts job
      description: Gets the status of a delete contacts job and the results if complete.
      operationId: getDeleteStatus
      parameters:
      - name: deleteId
        in: path
        description: The delete job id you want the status for
        required: true
        schema:
          type: string
          example: c4920aee-3add-44e4-b8c0-dcbfacbfee40
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_1'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidDeleteId
                description: The id value '123646' is not a recognized deletion job identifier
        '401':
          description: Unauthorized
        '404':
          description: Import request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:importNotFound
                description: The import request 'd7de900d-d337-43f6-b1e1-c8ec73e1a434' could not be found!
  /contacts/v3/import:
    put:
      summary: Import contact collection
      description: Imports a collection of contacts. Creates contacts if they do not exist and updates contacts if they do. This is an async operation and you will need to check when it is complete by calling **getImportStatus** <br><br>**Note:** It isn't possible to specify the value for the **contactId** field when creating a contact, so it is only used to check for a matching contact when specified
      operationId: importContacts
      parameters:
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      requestBody:
        description: Contact data collection
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v3_import_body'
            example:
              mergeOption: overwrite
              contacts:
              - matchIdentifier: email
                identifiers:
                  email: jane.doe@emailsim.io
                dataFields:
                  firstName: Jane
                  lastName: Doe
                  gender: female
              - matchIdentifier: mobileNumber
                identifiers:
                  email: john.doe@emailsim.io
                  mobileNumber: '447123123123'
                dataFields:
                  firstName: John
                  lastName: Doe
                  gender: male
                channelProperties:
                  email:
                    emailType: Html
              - matchIdentifier: contactId
                identifiers:
                  contactId: 123456
                  email: my-new-email@emailsim.io
        required: true
      responses:
        '202':
          description: Import processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_202_1'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:badJson
                description: The request JSON is badly formed
        '401':
          description: Unauthorized
        '429':
          description: Too many import requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:tooManyActiveImports
                description: Your import request cannot be accepted as too many imports are being processed for you account. Please wait for an import to complete and then resubmit.
  /contacts/v3/import/{importId}:
    get:
      summary: Get the status of a contacts import request
      description: Gets the status of a contacts import request and the results if available.<br><br>**Note:** When importing, contacts are created or updated but if any associated data sets fail to import then details of these are included in the **failures** results
      operationId: getImportStatus
      parameters:
      - name: importId
        in: path
        description: The import id you want the status for
        required: true
        schema:
          type: string
          example: d7de900d-d337-43f6-b1e1-c8ec73e1a434
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_2'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidId
                description: The id value '123646' is invalid for the identifier 'email'
        '401':
          description: Unauthorized
        '404':
          description: Import request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:importNotFound
                description: The import request 'd7de900d-d337-43f6-b1e1-c8ec73e1a434' could not be found!
  /contacts/v3/{identifier}/{value}:
    get:
      summary: Get a contact by an identifier
      description: Get a contact's details using a specific identifier
      operationId: getContact
      parameters:
      - name: identifier
        in: path
        description: The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of **contactId**, **email** or **mobileNumber**
        required: true
        schema:
          maxLength: 50
          minLength: 1
          pattern: (^[-A-Za-z0-9_]{1,50}$)
          type: string
      - name: value
        in: path
        description: The unique value to identify the contact.<br>***Note:** Must be the same type as the **identifier***
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidId
                description: The id value '123646' is invalid for the identifier 'email'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:contactNotFound
                description: The following contacts could not be found
                details:
                - item: unknown@emailsim.io
                  description: Not found using the identifier 'email'
    put:
      summary: Replace a contact
      description: "Replaces a contact entirly with the data passed in the request.<br><br>\n  **Note:**\n  * This call will **replace the entire contact** when updating with the data passed; if would like to change just select fields then use the PATCH call."
      operationId: replaceContact
      parameters:
      - name: identifier
        in: path
        description: The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of **contactId**, **email** or **mobileNumber**
        required: true
        schema:
          maxLength: 50
          minLength: 1
          pattern: (^[-A-Za-z0-9_]{1,50}$)
          type: string
      - name: value
        in: path
        description: The unique value to identify the contact.<br>***Note:** Must be the same type as the **identifier***
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      requestBody:
        description: The contact data. **Note:** It is not possible to modify the **contactId** field
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/replaceContactRequest'
        required: true
      responses:
        '200':
          description: Contact replaced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidId
                description: The id value '123646' is invalid for the identifier 'email'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:contactNotFound
                description: The following contacts could not be found
                details:
                - item: '354265'
                  description: Not found using the identifier 'contactId'
    delete:
      summary: Deletes a contact using a specific identifier
      description: Delete a contact using a specific identifier
      operationId: deleteContact
      parameters:
      - name: identifier
        in: path
        description: The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of **contactId**, **email** or **mobileNumber**
        required: true
        schema:
          maxLength: 50
          minLength: 1
          pattern: (^[-A-Za-z0-9_]{1,50}$)
          type: string
      - name: value
        in: path
        description: The unique value to identify the contact.<br>***Note:** Must be the same type as the **identifier***
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      responses:
        '200':
          description: Contact deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_3'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidId
                description: The id value '123646' is invalid for the identifier 'email'
        '401':
          description: Unauthorized
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:contactNotFound
                description: The following contacts could not be found
                details:
                - item: '354265'
                  description: Not found using the identifier 'contactId'
    patch:
      summary: Import a single contact
      description: Imports a single contact; if it is an existing contact it updates the contact with just the fields passed in the request with a choice of how to handle the merging of data, otherwise it create a new contact.
      operationId: importContact
      parameters:
      - name: identifier
        in: path
        description: The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of **contactId**, **email** or **mobileNumber**
        required: true
        schema:
          maxLength: 50
          minLength: 1
          pattern: (^[-A-Za-z0-9_]{1,50}$)
          type: string
      - name: value
        in: path
        description: The unique value to identify the contact.<br>***Note:** Must be the same type as the **identifier***
        required: true
        schema:
          maxLength: 256
          minLength: 1
          type: string
      - name: x-ddg-integration-token
        in: header
        description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
        required: false
        schema:
          pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
          type: string
          example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
      - name: merge-option
        in: query
        description: Set the behavior of how the new data should be merged into existing contacts.
        required: false
        schema:
          type: string
          example: overwrite
          enum:
          - overwrite
          - overwrite-if-not-empty
          - overwrite-if-empty
          default: overwrite
      requestBody:
        description: The contact fields to update. **Note:** It is not possible to modify the **contactId** field
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateContactRequest'
        required: true
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
        '201':
          description: Contact created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contact'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:invalidId
                description: The id value '123646' is invalid for the identifier 'email'
        '401':
          description: Unauthorized
        '409':
          description: Identifier conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: contacts:idAlreadyExists
                description: The id value 'jane.doe@emailsim.io for the identifier 'email' already exists. All identifiers must be unique!
components:
  schemas:
    optInType:
      type: string
      description: Channel opt-in type for the contact
      example: Double
      enum:
      - Unknown
      - Single
      - Double
      - VerifiedDouble
    status:
      type: string
      description: The opt in status for the contact
      example: subscribed
      enum:
      - subscribed
      - unsubscribed
      - pendingOptIn
      - deleted
      - suppressed
      - binned
      - noSubscription
    preference:
      required:
      - id
      - isOptedIn
      type: object
      properties:
        id:
          type: integer
          description: ID of the preference
          format: int32
          example: 1
        isOptedIn:
          type: boolean
          description: Specify whether the contact is opted into this preference
    preferenceFull:
      required:
      - id
      - isOptedIn
      - name
      type: object
      properties:
        id:
          type: integer
          description: ID of the preference
          format: int32
          example: 1
        isOptedIn:
          type: boolean
          description: Indicates whether the contact is opted into this preference
        publicName:
          type: string
          description: Public name of the marketing preference
          example: Mens fashion
        privateName:
          type: string
          description: Private name of the marketing preference
          example: mensFashion01
    consentRecord:
      required:
      - dateTimeConsented
      - ipAddress
      - text
      - url
      - userAgent
      type: object
      properties:
        text:
          minLength: 1
          type: string
          description: Consent text displayed to the contact
          example: Yes, I would like to receive a monthly newsletter
        dateTimeConsented:
          type: string
          description: ISO 8601 UTC timestamp for when the consent was obtained
          format: date-time
          example: '2023-01-26T21:29:00Z'
        url:
          type: string
          description: URL the consent was obtained with
          format: uri
          example: http://www.example.com/signup
        ipAddress:
          oneOf:
          - type: string
            description: IPv4 address of the contact the consent was obtained for
            format: ipv4
            example: 129.168.0.2
          - type: string
            description: IPv6 address of the contact the consent was obtained for
            format: ipv6
            example: 2b01:1234:136:0:116f:3244:a476:d6b7
        userAgent:
          minLength: 1
          type: string
          description: User agent header of the browser used by the contact the consent was obtained for
          example: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36
      additionalProperties: false
      description: Marketing consent records to be associated with the contact
    consentRecordsToBeInserted:
      maxItems: 5
      minItems: 1
      type: array
      description: The marketing consent records to be associated with the contact
      items:
        $ref: '#/components/schemas/consentRecord'
    consentRecords:
      type: array
      description: Marketing consent records associated with the contact
      items:
        example:
          text: Yes, I would like to receive a monthly newsletter
          dateTimeConsented: '2023-01-26T21:29:00'
          url: http://www.example.com/signup
          ipAddress: 129.168.0.2
          userAgent: Mozilla/5.0 (X11; OpenBSD i386) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.125 Safari/537.36
          dateTimeCreated: '2023-01-26T22:55:00'
        allOf:
        - $ref: '#/components/schemas/consentRecord'
        - required:
          - dateTimeCreated
          type: object
          properties:
            dateTimeCreated:
              type: string
              description: ISO 8601 UTC timestamp for when the consent was created
              format: date-time
              example: '2023-01-26T22:55:00Z'
    contactBasicDetails:
      required:
      - contactId
      - created
      - identifiers
      - status
      - updated
      type: object
      properties:
        contactId:
          $ref: '#/components/schemas/contactId'
        status:
          $ref: '#/components/schemas/status'
        created:
          type: string
          description: ISO 8601 UTC timestamp for when the contact was created
          format: date-time
        updated:
          type: string
          description: ISO 8601 UTC timestamp for when the contact was last updated
          format: date-time
        identifiers:
          $ref: '#/components/schemas/identifiers'
    contact:
      allOf:
      - $ref: '#/components/schemas/contactBasicDetails'
      - type: object
        properties:
          dataFields:
            type: object
            additionalProperties: true
            description: Addtional data fields for the contact specified for the contact
            example:
              firstName: John
              lastName: Doe
              gender: male
          channelProperties:
            $ref: '#/components/schemas/contact_channelProperties'
          lists:
            type: array
            description: Lists the contact belongs to
            items:
              $ref: '#/components/schemas/contact_lists'
          preferences:
            minItems: 1
            type: array
            description: Preferences the contact is opted-in to
            items:
              $ref: '#/components/schemas/preferenceFull'
          consentRecords:
            $ref: '#/components/schemas/consentRecords'
        description: A contact
    baseContact:
      allOf:
      - type: object
        properties:
          dataFields:
            type: object
            additionalProperties: true
            description: Addtional data fields for the contact
            example:
              firstName: John
              lastName: Doe
              gender: male
      - $ref: '#/components/schemas/channelProperties'
      - type: object
        properties:
          lists:
            maxItems: 100
            minItems: 1
            type: array
            description: List IDs for the lists the contact should be added to
            items:
              type: integer
              description: Unique list id
              format: int32
              example: 345579
          preferences:
            minItems: 1
            type: array
            description: Preferences you want to opt the contact into. ***Note:** Only required for preferences and not preference categories*
            items:
              $ref: '#/components/schemas/preference'
    baseContactRequest:
      allOf:
      - $ref: '#/components/schemas/baseContact'
      - type: object
        properties:
          consentRecords:
            $ref: '#/components/schemas/consentRecordsToBeInserted'
    createContactRequest:
      allOf:
      - required:
        - identifiers
        type: object
        properties:
          identifiers:
            allOf:
            - description: Identifiers this contact can be referenced by
            - $ref: '#/components/schemas/identifiers'
      - $ref: '#/components/schemas/baseContactRequest'
    updateContactRequest:
      allOf:
      - type: object
        properties:
          identifiers:
            allOf:
            - description: Identifiers this contact can be referenced by
            - $ref: '#/components/schemas/identifiers'
      - $ref: '#/components/schemas/baseContactRequest'
      - $ref: '#/components/schemas/channelPropertiesWithResubscribe'
    replaceContactRequest:
      allOf:
      - required:
        - identifiers
        type: object
        properties:
          identifiers:
            allOf:
            - description: Identifiers this contact can be referenced by
            - $ref: '#/components/schemas/identifiers'
      - $ref: '#/components/schemas/baseContact'
      - $ref: '#/components/schemas/channelPropertiesWithResubscribe'
    contactRequest:
      allOf:
      - required:
        - identifiers
        - matchIdentifier
        type: object
        properties:
          matchIdentifier:
            type: string
            description: Specify which identifier in the provided `identifiers` should be used to match the contact to an existing record. This can be a custom identifier or a contact identifier of contactId, email or mobileNumber.
            example: mobileNumber
          identifiers:
            allOf:
            - description: Identifiers this contact can be referenced by
            - $ref: '#/components/schemas/contactIdObject'
        description: The contact data
      - $ref: '#/components/schemas/updateContactRequest'
    contactIdentifier:
      oneOf:
      - required:
        - contactId
        type: object
        properties:
          contactId:
            type: integer
            format: int64
            example: 12345
        description: Contact Id identifier to identify the contact
      - required:
        - email
        type: object
        properties:
          email:
            type: string
            example: john.doe@emailsim.io
        description: Email identifier to identify the contact
      - required:
        - mobileNumber
        type: object
        properties:
          mobileNumber:
            type: string
            example: '447123123123'
        description: Phone number identifier to identify the contact
      - maxProperties: 1
        minProperties: 1
        type: object
        additionalProperties:
          type: string
          example: C00000000001
        description: Custom identifier to identify the contact. This custom identifier must exist in the account.
    channelStatusUpdate:
      type: string
      description: The subscription status for the channel; if not specified it remains unaltered for existing contacts, and for new contacts this defaults to values defined in _Settings > Contacts > Mobile subscription_
      example: subscribed
      enum:
      - noSubscription
      - subscribed
      - unsubscribed
      - suppressed
    emailChannelStatus:
      type: string
      description: Current status of the email channel for the contact
      example: subscribed
      enum:
      - noSubscription
      - subscribed
      - unsubscribed
      - softBounced
      - hardBounced
      - ispComplained
      - pendingOptIn
      - directComplaint
      - spamTrap
      - deleted
      - blockedlocalpart
      - sharedsuppression
      - sharedDomainSuppression
      - suppressed
      - purchased
      - knownComplainer
      - knownLitigator
      - binned
      - domainSuppressed
    whatsAppChannelStatus:
      type: string
      description: The current status for the WhatsApp channel for this contact
      example: subscribed
      enum:
      - noSubscription
      - subscribed
      - unsubscribed
      - suppressed
    smsChannelStatus:
      type: string
      description: The current status for the SMS channel for this contact
      example: subscribed
      enum:
      - noSubscription
      - subscribed
      - unsubscribed
      - bounced
      - deleted
      - suppressed
      - binned
    channelProperties:
      type: object
      properties:
        channelProperties:
          $ref: '#/components/schemas/channelProperties_channelProperties'
    channelPropertiesWithResubscribe:
      type: object
      properties:
        channelProperties:
          $ref: '#/components/schemas/channelPropertiesWithResubscribe_channelProperties'
    paginationLinks:
      required:
      - first
      - self
      type: object
      properties:
        self:
          $ref: '#/components/schemas/paginationLinks_self'
        first:
          $ref: '#/components/schemas/paginationLinks_first'
        prev:
          $ref: '#/components/schemas/paginationLinks_prev'
        next:
          $ref: '#/components/schemas/paginationLinks_next'
        last:
          $ref: '#/components/schemas/paginationLinks_last'
      description: Pagination links
    errorResponse:
      required:
      - description
      - errorCode
      type: object
      properties:
        errorCode:
          type: string
          description: Unique error code
        description:
          type: string
          description: Description of the issue
        details:
          type: array
          items:
            $ref: '#/components/schemas/errorResponse_details'
    contactReference:
      required:
      - contactId
      - identifiers
      type: object
      properties:
        contactId:
          $ref: '#/components/schemas/contactId'
        identifiers:
          $ref: '#/components/schemas/identifiers'
      description: Contact reference
    contactId:
      minimum: 0
      type: integer
      description: Immutable unique identifier for the contact
      example: 35212311
    identifiers:
      type: object
      properties:
        email:
          description: Contact email address
          example: someone@emailsim.io
        mobileNumber:
          description: Contact phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164)
          example: '447123123123'
      additionalProperties:
        type: string
        description: Any additional custom identifiers. Property names must match one of the custom identifiers that exists in the account.
      description: Identifiers this contact can be referenced by
      example:
        email: someone@emailsim.io
        mobileNumber: '447123123123'
        myCustomId: MYID_12345
    contactIdObject:
      type: object
      properties:
        contactId:
          minimum: 0
          type: integer
          description: Immutable unique identifier for the contact
          example: 35212311
    inline_response_200:
      required:
      - _items
      - _links
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/paginationLinks'
        _items:
          type: array
          description: Returned contacts
          items:
            $ref: '#/components/schemas/contact'
    inline_response_202:
      type: object
      properties:
        deleteId:
          type: string
          example: c4920aee-3add-44e4-b8c0-dcbfacbfee40
    inline_response_200_1:
      required:
      - deleteId
      - status
      type: object
      properties:
        deleteId:
          type: string
          description: The delete job request id
          example: c4920aee-3add-44e4-b8c0-dcbfacbfee40
        status:
          type: string
          enum:
          - NotStarted
          - NotFinished
          - Finished
          - Failed
        summary:
          $ref: '#/components/schemas/inline_response_200_1_summary'
        deleted:
          type: array
          description: The contacts that were successfully deleted
          items:
            $ref: '#/components/schemas/contactIdentifier'
        failures:
          type: array
          description: The contacts that failed to be deleted
          items:
            $ref: '#/components/schemas/inline_response_200_1_failures_1'
    v3_import_body:
      required:
      - contacts
      type: object
      properties:
        mergeOption:
          type: string
          description: Specify how the merging of new data with existing data is handled
          example: overwrite
          enum:
          - overwrite
          - overwriteIfNotEmpty
          - overwriteIfEmpty
          default: overwrite
        contacts:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/contactRequest'
    inline_response_202_1:
      type: object
      properties:
        importId:
          type: string
          example: d7de900d-d337-43f6-b1e1-c8ec73e1a434
    inline_response_200_2:
      required:
      - importId
      - status
      type: object
      properties:
        importId:
          type: string
          description: The import id you want the status for
          example: d7de900d-d337-43f6-b1e1-c8ec73e1a434
        status:
          type: string
          enum:
          - Finished
          - NotFinished
          - RejectedByWatchdog
          - Failed
          - ExceedsAllowedContactLimit
        summary:
          $ref: '#/components/schemas/inline_response_200_2_summary'
        created:
          type: array
          description: Contacts that were successfully created
          items:
            $ref: '#/components/schemas/contactReference'
        updated:
          type: array
          description: Contacts that were successfully updated
          items:
            $ref: '#/components/schemas/contactReference'
        failures:
          type: array
          description: Contacts that were not imported
          example:
          - contactId: 12345
            matchIdentifier: email
            identifiers:
              email: bob@emailsim@io.com
            failures:
            - failureCode: invalidEmail
              description: Invalid value for 'email'
          - matchIdentifier: email
            identifiers:
              email: bob@emailsim@io.com
            failures:
            - failureCode: invalidEmail
              description: Invalid value for 'email'
          - matchIdentifier: email
            identifiers:
              email: emma@emailsim.io
            failures:
            - failureCode: duplicateIdentifier
              description: Duplicate identifier detected for email 'emma@emailsim.io'
          - matchIdentifier: email
            identifiers:
              email: frank@emailsim.io
            failures:
            - failureCode: consentRecordsNotApplied
              description: The provided consent records could not be applied as they were incorrectly formatted
          items:
            $ref: '#/components/schemas/inline_response_200_2_failures_1'
    inline_response_200_3:
      required:
      - contactId
      type: object
      properties:
        contactId:
          $ref: '#/components/schemas/contactId'
      description: The contact id of the deleted contact
    contact_channelProperties_email:
      required:
      - emailType
      - optInType
      - status
      type: object
      properties:
        emailType:
          type: string
          description: The format the contact expects emails in.
          example: Html
          enum:
          - PlainText
          - Html
        optInType:
          $ref: '#/components/schemas/optInType'
        status:
          $ref: '#/components/schemas/emailChannelStatus'
      additionalProperties: false
    contact_channelProperties_sms:
      required:
      - countryCode
      - status
      type: object
      properties:
        countryCode:
          type: string
          description: '[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code the contacts **mobileNumber**'
          example: GB
        status:
          $ref: '#/components/schemas/smsChannelStatus'
      additionalProperties: false
    contact_channelProperties_whatsApp:
      required:
      - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/whatsAppChannelStatus'
      additionalProperties: false
    contact_channelProperties:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/contact_channelProperties_email'
        sms:
          $ref: '#/components/schemas/contact_channelProperties_sms'
        whatsApp:
          $ref: '#/components/schemas/contact_channelProperties_whatsApp'
      additionalProperties: false
      description: Properties associated with each channel for a contact. For exmaple, message format or subscription status.
    contact_lists:
      required:
      - id
      - name
      - status
      type: object
      properties:
        id:
          type: integer
          description: Immutable unique list ID
          format: int32
          example: 12345
        name:
          maxLength: 128
          type: string
          description: Name of the list
          example: Top customers
        status:
          type: string
          description: The list status for the contact
          example: subscribed
          enum:
          - subscribed
          - suppressed
          - pending
    channelProperties_channelProperties_email:
      type: object
      properties:
        emailType:
          type: string
          description: Format the contact receives emails in
          example: html
          enum:
          - plainText
          - html
        optInType:
          type: string
          description: Email opt-in type for the contact, if set to verified double for email or the account setting *Enforce double opt-in for all signups, including bulk uploads* is set, then the email holder will be sent an email to confirm their subscription, and in the meantime the email channel status will be **pendingOptIn**
          example: double
          enum:
          - unknown
          - single
          - double
          - verifiedDouble
        status:
          type: string
          description: The subscription status for the channel; if not specified it remains unaltered for existing contacts, and for new contacts this defaults to **subscribed**
          enum:
          - subscribed
          - unsubscribed
          - suppressed
      additionalProperties: false
      description: The channel properties for email
    channelProperties_channelProperties_sms:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/channelStatusUpdate'
      additionalProperties: false
      description: The channel properties for SMS/MMS
    channelProperties_channelProperties_whatsApp:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/channelStatusUpdate'
      additionalProperties: false
      description: The channel properties for WhatsApp
    channelProperties_channelProperties:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/channelProperties_channelProperties_email'
        sms:
          $ref: '#/components/schemas/channelProperties_channelProperties_sms'
        whatsApp:
          $ref: '#/components/schemas/channelProperties_channelProperties_whatsApp'
      additionalProperties: false
      description: Properties associated with each channel for a contact. For example, message format or subscription status
    channelPropertiesWithResubscribe_channelProperties_email_resubscribeOptions:
      type: object
      properties:
        resubscribeWithNoChallenge:
          type: boolean
          description: If resubscribing the channel should we not send a resubscription confirmation email?
          default: true
        preferredLocale:
          type: string
          description: The language code for the language you would like the resubscribe request email to be sent to the contact in
          enum:
          - cs-CS
          - da-DA
          - de-DE
          - el-EL
          - en-EN
          - es-ES
          - es
          - fi-FI
          - fr-FR
          - hu-HU
          - it-IT
          - nl-NL
          - nb-NO
          - pl-PL
          - pt-PT
          - ru-RU
          - se-SE
          - sk-SK
          - tr-TR
          - zh-CN
        redirectUrlAfterChallenge:
          type: string
          description: The URL you would like to redirect challenged contacts to after they have completed their resubscription
          format: uri
          example: https://somedomain.io/some/page
    channelPropertiesWithResubscribe_channelProperties_email:
      type: object
      properties:
        resubscribeOptions:
          $ref: '#/components/schemas/channelPropertiesWithResubscribe_channelProperties_email_resubscribeOptions'
    channelPropertiesWithResubscribe_channelProperties:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/channelPropertiesWithResubscribe_channelProperties_email'
    paginationLinks_self:
      required:
      - link
      - marker
      type: object
      properties:
        marker:
          type: string
          description: Pagination marker to be passed to API calls to retrieve this data page
        link:
          type: string
          description: Link to retrieve the data page
      description: Details for accessing this data page via pagination
    paginationLinks_first:
      required:
      - link
      - marker
      type: object
      properties:
        marker:
          type: string
          description: Pagination marker to be passed to API calls to retrieve this data page
        link:
          type: string
          description: Link to retrieve the data page
      description: Details for accessing the first page worth of data
    paginationLinks_prev:
      required:
      - link
      - marker
      type: object
      properties:
        marker:
          type: string
          description: Pagination marker to be passed to API calls to retrieve this data page
        link:
          type: string
          description: Link to retrieve the data page
      description: Details for accessing the previous pagea worth of data
    paginationLinks_next:
      required:
      - link
      - marker
      type: object
      properties:
        marker:
          type: string
          description: Pagination marker to be passed to API calls to retrieve this data page
        link:
          type: string
          description: Link to retrieve the data page
      description: Details for accessing the next pages worth of data
    paginationLinks_last:
      required:
      - link
      - marker
      type: object
      properties:
        marker:
          type: string
          description: Pagination marker to be passed to API calls to retrieve this data page
        link:
          type: string
          description: Link to retrieve the data page
      description: Details for accessing the last pages worth of data
    errorResponse_details:
      required:
      - description
      - item
      type: object
      properties:
        item:
          type: string
          description: Item the error is associated with, for example, field name, unique identifier for an entity or item in batch
        description:
          type: string
          description: Description of the error
    inline_response_200_1_summary:
      required:
      - deletedContacts
      - invalidEntries
      - requestedContacts
      - unknownContacts
      type: object
      properties:
        requestedContacts:
          type: integer
          description: The number of contacts requested to be deleted
          format: int32
          example: 100
        deletedContacts:
          type: integer
          description: The number of contacts deleted
          format: int32
          example: 95
        unknownContacts:
          type: integer
          description: The number of contacts that could not be identified
          format: int32
          example: 4
        invalidEntries:
          type: integer
          description: The number of contacts that could not be processed
          format: int32
          example: 1
    inline_response_200_1_failures:
      required:
      - description
      - failureCode
      type: object
      properties:
        failureCode:
          type: string
          description: The unique failure code for this failure reason
          example: invalidEmail
        description:
          type: string
          description: The English reason for the failure
          example: Invalid value for 'email'
      description: A failure reason
    inline_response_200_1_failures_1:
      required:
      - failures
      - identifier
      type: object
      properties:
        identifier:
          $ref: '#/components/schemas/contactIdentifier'
        failures:
          type: array
          description: The reasons the contact failed to import
          example:
          - failureCode: invalidEmail
            description: Invalid value for 'email'
          - failureCode: contactNotFound
            description: The contact could not be found
          items:
            $ref: '#/components/schemas/inline_response_200_1_failures'
      description: Contact delete failure summary
    inline_response_200_2_summary:
      type: object
      properties:
        newContacts:
          type: integer
          description: Number of new contacts added
          format: int32
          example: 10
        updatedContacts:
          type: integer
          description: Number of contacts updated
          format: int32
          example: 14
        globallySuppressed:
          type: integer
          description: Number of contacts that are suppressed at the account level, so can't be updated
          format: int32
          example: 0
        invalidEntries:
          type: integer
          description: Number of contacts with invalid data, so can't be updated or created
          format: int32
          example: 2
        duplicateIdentifiers:
          type: integer
          description: Number of contacts with a duplicate identifier, so can't be updated or created
          format: int32
          example: 2
    inline_response_200_2_failures:
      required:
      - description
      - failureCode
      type: object
      properties:
        failureCode:
          type: string
          description: Unique failure code for this failure reason
          example: invalidEmail
        description:
          type: string
          description: Description of the reason for the failure
          example: Invalid value for 'email'
      description: A failure reason
    inline_response_200_2_failures_1:
      required:
      - failures
      - identifiers
      - matchIdentifier
      type: object
      properties:
        contactId:
          $ref: '#/components/schemas/contactId'
        matchIdentifier:
          maxLength: 50
          minLength: 1
          pattern: (^[-A-Za-z0-9_]{1,50}$)
          type: string
          description: Which identifier in the provided `identifiers` was used to match the contact to an existing record. This can also include the name of a custom identifier.
          example: mobileNumber
        identifiers:
          $ref: '#/components/schemas/identifiers'
        failures:
          type: array
          description: Reasons the contact failed to import
          items:
            $ref: '#/components/schemas/inline_response_200_2_failures'
      description: Contact import failure summary
  parameters:
    integrationTrackingToken:
      name: x-ddg-integration-token
      in: header
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      required: false
      schema:
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        type: string
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    createdFilter:
      name: ~created
      in: query
      description: 'Filter by created date.<br/>

        ***Note:***

        * The date must be in ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601))

        * Can''t be used in conjunction with the **~modified** parameter.'
      schema:
        pattern: ^gte::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$
        type: string
      examples:
        Greater than or equal to created date:
          value: gte::2021-12-17T00:00:00Z
    modifiedFilter:
      name: ~modified
      in: query
      description: 'Filter by last modified date.<br/>

        ***Note:***

        * The date must be in ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601))'
      schema:
        pattern: ^gte::\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$
        type: string
      examples:
        Greater than or equal to modified date:
          value: gte::2021-12-17T00:00:00Z
    listFilter:
      name: ~listId
      in: query
      description: 'Filter by a specific list.<br/>

        ***Note:***

        * Can''t be used in conjunction with the **~segmentId** parameter.'
      schema:
        type: integer
      example: 54321
    segmentFilter:
      name: ~segmentId
      in: query
      description: 'Filter by a specific segment.<br/>

        ***Note:***

        * Can''t be used in conjunction with the **~listId** parameter.'
      schema:
        type: integer
      example: 12345
    limit:
      name: limit
      in: query
      description: Maximum number of records to retrieve per page
      schema:
        maximum: 5000
        minimum: 1
        type: integer
        format: int32
        example: 1000
    marker:
      name: marker
      in: query
      description: Pagination marker to retrieve the data from
      schema:
        type: string
        example: RXhhbXBsZSBhbXJrZXIgdmFsdWU=
    identifier:
      name: identifier
      in: path
      description: The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of **contactId**, **email** or **mobileNumber**
      required: true
      schema:
        maxLength: 50
        minLength: 1
        pattern: (^[-A-Za-z0-9_]{1,50}$)
        type: string
    value:
      name: value
      in: path
      description: The unique value to identify the contact.<br>***Note:** Must be the same type as the **identifier***
      required: true
      schema:
        maxLength: 256
        minLength: 1
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-ddg-notes: This version removes:\n* ~contactStatuses filter added to Get Contacts
x-samples-languages:
- curl
- csharp
- java
- javascript
- node
- python
- php
- ruby