openapi: 3.2.0
info:
  title: Lists API
  description: Lists
  version: v3
servers:
- url: https://api.us1.odp.optimizely.com/v3
  description: United States
- url: https://api.eu1.odp.optimizely.com/v3
  description: Europe
- url: https://api.au1.odp.optimizely.com/v3
  description: Asia-Pacific
security:
- x-api-key: []
tags:
- name: Lists
paths:
  /lists/subscriptions:
    get:
      tags:
      - Lists
      summary: Get Subscription Status
      description: Get the subscription status of a customer identifier to an Optimizely Data Platform (ODP) list.
      operationId: get-subscription-status
      parameters:
      - name: identifiers
        in: query
        description: The identifier type, for example "email".
        required: true
        style: form
        explode: true
        schema:
          type: object
          additionalProperties:
            type: string
        examples:
          Email Identifier:
            description: Email Identifier
            value:
              email: customer@email.com
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                example: '{ "customer": { "email": "sample@test.com" }, "opted_in": true, "explicit_opt_in": true, "subscriptions": [ { "name": "True List Name", "list_id": "sample_list", "subscribed": true, "ts_status_updated": 1583868571 } ] }'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                example: '{"title":"Bad Request","status":400,"timestamp":"2018-09-10T21:07:10-05:00","detail":{"invalids":[{"field":"delimiter","reason":"Unrecognized delimiter, valid options are comma, tab or pipe"}]}}'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                example: '{  "message": "Forbidden"}'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                example: '{ "title": "Not Found", "status": 404, "timestamp": "2023-07-10T21:07:10-05:00", "detail": { "message": "Customer with email sample@test.com was not found" } }'
    post:
      tags:
      - Lists
      summary: Subscribe/Unsubscribe
      description: Subscribe or unsubscribe a customer identifier to or from an Optimizely Data Platform (ODP) list.
      operationId: subscribeunsubscribe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscribe'
            examples:
              Example Payload:
                description: Example Payload
                value:
                  list_id: sample_list
                  email: sample@test.com
                  subscribed: false
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                example: '{ "updates": [ { "list_id": "sample_list", "email": "sample@test.com", "subscribed": true } ] }'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                example: '{"title":"Bad Request","status":400,"timestamp":"2018-09-10T21:07:10-05:00","detail":{"invalids":[{"field":"delimiter","reason":"Unrecognized delimiter, valid options are comma, tab or pipe"}]}}'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                example: '{  "message": "Forbidden"}'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                example: '{"title":"Bad Request","status":404,"timestamp":"2018-09-10T21:07:10-05:00","detail":{"message":"Not found description"}}'
  /lists:
    get:
      tags:
      - Lists
      summary: Get Lists
      description: Get all lists associated with an Optimizely Data Platform (ODP) account.
      operationId: get-lists
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                example: '{ "lists": [ { "name": "Example List", "created_at": "2018-09-10T21:07:10+00:00", "list_id": "example_list" }, { "name": "Example List 2", "created_at": "2018-10-15T13:43:46+00:00", "list_id": "example_list_2" } ] }'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                example: '{  "message": "Forbidden"}'
    post:
      tags:
      - Lists
      summary: Create List
      description: Create a new list within an Optimizely Data Platform (ODP) account.
      operationId: create-list
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateList'
            examples:
              Example Payload:
                description: Example Payload
                value:
                  name: My List
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                example: '{ "updates": [ { "list_id": "sample_list", "email": "sample@test.com", "subscribed": true } ] }'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                example: '{"title":"Bad Request","status":400,"timestamp":"2018-09-10T21:07:10-05:00","detail":{"invalids":[{"field":"delimiter","reason":"Unrecognized delimiter, valid options are comma, tab or pipe"}]}}'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                example: '{  "message": "Forbidden"}'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                example: '{"title":"Bad Request","status":404,"timestamp":"2018-09-10T21:07:10-05:00","detail":{"message":"Not found description"}}'
components:
  schemas:
    CreateList:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: The name of the list to create.
          example: My List
    Subscribe:
      required:
      - identifer
      - list_id
      type: object
      properties:
        subscribed:
          type: boolean
          description: whether or not the messaging identifier is subscribed to the list
          example: false
        list_id:
          type: string
          description: the name of the list
          example: sample_list
      additionalProperties:
        type: string
        description: the messaging identifier to act upon (for example. email). Required.
        example:
          email: sample@test.com
  securitySchemes:
    x-api-key:
      type: apiKey
      name: x-api-key
      in: header
x-readme:
  explorer-enabled: true
  proxy-enabled: true