openapi: 3.0.3
info:
  title: Dotdigital Configuration Service
  description: 'Retrieve and update configuration settings for your account. Use this API to

    list, create, and delete custom contact identifiers that can be used to

    uniquely identify contacts across your account.'
  version: 3.0.2
externalDocs:
  description: Learn more about Dotdigital APIs
  url: https://developer.dotdigital.com
servers:
- url: https://r1-api.dotdigital.com
- url: https://r2-api.dotdigital.com
- url: https://r3-api.dotdigital.com
security:
- basicAuth: []
paths:
  /configuration/v3/customIdentifiers:
    get:
      tags:
      - Custom identifiers
      summary: Get all custom identifiers
      description: Gets all the custom identifiers defined for the account.
      operationId: getCustomIdentifiers
      responses:
        '200':
          description: Custom identifiers retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/customIdentifier'
        '401':
          description: Unauthorized
    post:
      tags:
      - Custom identifiers
      summary: Creates a custom identifier.
      description: Creates a new custom identifier that will be available to identify contacts.
      operationId: createCustomIdentifier
      requestBody:
        description: The custom identifier and its properties.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customIdentifierRequest'
        required: true
      responses:
        '201':
          description: Custom identifier created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customIdentifier'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: customIdentifiers:nameTooLong
                description: The custom identifier is too long. It must be less than 50 characters.
        '401':
          description: Unauthorized
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: customIdentifiers:nameAlreadyExists
                description: The custom identifier already exists.
        '412':
          description: Custom identifier limit reached
  /configuration/v3/customIdentifiers/{name}:
    delete:
      tags:
      - Custom identifiers
      summary: Delete a custom identifier by name
      description: Delete a custom identifier by name if it exists.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          example: crm-id
      responses:
        '204':
          description: Custom identifier deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
                errorCode: customIdentifiers:inUse
                description: The custom identiefier is in use by another entity.
                details:
                  items:
                  - item: segment:1002
                    description: Custom Identifier is used by segment 'CRM Contacts'
                  - item: program:2569
                  description: Custom Identifier is used by program 'CRM Contacts Sync'
        '401':
          description: Unauthorized
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
              example:
              - errorCode: customIdentifiers:notExist
                description: The custom identifier does not exist.
components:
  schemas:
    customIdentifierRequest:
      required:
      - name
      type: object
      properties:
        name:
          maxLength: 50
          minLength: 1
          pattern: (^[-A-Za-z0-9_]{1,50}$)
          type: string
          description: The unique custom identifier name.
          example: crm-id
    customIdentifier:
      type: object
      properties:
        name:
          type: string
          description: The unique custom identifier name.
          example: crm-id
        created:
          type: string
          description: ISO 8601 UTC timestamp for when the record was created.
          format: date-time
          example: '2024-05-21T12:34:56Z'
        updated:
          type: string
          description: ISO 8601 UTC timestamp for when the record was last updated.
          format: date-time
          example: '2024-05-21T12:34:56Z'
    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'
    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
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-samples-languages:
- curl
- csharp
- java
- javascript
- node
- python
- php
- ruby