openapi: '3.0.0'
info:
  title: Audience API
  version: "1.0"
  contact:
    name: MX API
    url: "https://www.mx.com/products/"
  description: Audience API
servers:
  - url: "http://yourdomain.access.mx.com"
paths:
  /api/token:
    post:
      summary: Create Access Token
      tags:
        - tokens
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: generated_token_string
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
      operationId: 1-token
      description: |-
        The Access Token, a JSON Web Token (JWT), is required for all requests to the Audience Service API and is created using your `client_id` and `client_secret`.

        Tokens may be revoked using the Revoke Access Token endpoint or will expire within 5 minutes. The expiration time may be found within the payload. However, information within the payload should not be used for any other purpose.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Credentials"
        description: The Create Access Token endpoint requires API Credentials,
          `client_id`  and `client_secret`, included in the body of the request.
  /api/token/{token}:
    delete:
      summary: Revoke Access Token

        - tokens
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      operationId: 2-revoke-token
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Credentials"
      description: Revokes an API Access Token.
      parameters:
        - $ref: "#/components/parameters/token"
  "/api/{version}/audiences":
    parameters:
      - $ref: "#/components/parameters/version"
    get:
      summary: Available Audiences
      tags:
        - audiences
      operationId: get-audience-available
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Audiences"
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
      parameters: []
      security:
        - bearerAuth: []
      description: Provides a list of available audiences.
  "/api/{version}/audience/{id_or_slug}/count":
    parameters:
      - $ref: "#/components/parameters/version"
      - $ref: "#/components/parameters/id_or_slug"
    get:
      summary: Audience Count
      tags:
        - audiences
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Count"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      operationId: get-audience-count
      description: Fetches the count of a specific audience.
      parameters:
        - $ref: "#/components/parameters/institution_public_id"
      security:
        - bearerAuth: []
  "/api/{version}/audience/{id_or_slug}/list":
    parameters:
      - $ref: "#/components/parameters/version"
      - $ref: "#/components/parameters/id_or_slug"
    get:
      summary: Audience List
      tags:
        - audiences
      operationId: get-audience-list
      responses:
        "200":
          description: Responses in JSON or CSV
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/List-JSON"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "406":
          description: Not Acceptable
        "500":
          description: Internal Server Error
      parameters:
        - $ref: "#/components/parameters/institution_public_id"
      security:
        - bearerAuth: []
      description: Retrieves a list of available audiences in either JSON or CSV format.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Audiences:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            example: CCR-01
          slug:
            type: string
            example: external-credit-card-no-internal-credit-card
          name:
            type: string
            example: External Credit Card / No internal Credit Card
          description:
            type: string
            example: Pending
      x-examples:
        Example 1:
          - id: CCR-01
            slug: external-credit-card-no-internal-credit-card
            name: External Credit Card / No internal Credit Card
            description: Pending
          - id: RTL-01
            slug: no-internal-checking-account
            name: No internal Checking Account
            description: Pending
          - id: RTL-07
            slug: no-direct-deposit-setup
            name: No Direct Deposit Setup
            description: Pending
          - id: MTG-03
            slug: external-mortgage-holders
            name: External Mortgage Holders
            description: Pending
          - id: PRL-05
            slug: internal-auto-loan-holders
            name: Internal Auto Loan Holders
            description: Pending
    Credentials:
      type: object
      required:
        - client_id
        - client_secret
      properties:
        client_id:
          type: string
          example: mock_client_id
        client_secret:
          type: string
          example: mock_client_secret
      title: API credentials
      description: |-
        All API Access Token endpoints require API Credentials, `client_id`  and `client_secret`, included in the request.
    Count:
      type: object
      properties:
        audience_id:
          type: string
          example: audience_1
        count:
          type: integer
          example: 100
        institution_id:
          type: string
          example: INST_PUBLIC_ID
        updated_on:
          type: string
          example: "2023-10-01"
    List-JSON:
      type: object
      properties:
        audience_id:
          type: string
          example: audience_1
        count:
          type: integer
          example: 5
        institution_id:
          type: string
          example: INST_PUBLIC_ID
        list:
          type: array
          items:
            type: string
            example: 02b70bd917264a3181beac85c1abd71e
        updated_on:
          type: string
          example: "2023-10-01"
      title: JSON List
    List-CSV:
      title: List-CSV
      type: string
      example: 02b70bd917264a3181beac85c1abd71e 8e468df6954c4d29b63aa983d8cf6155
        17093a20cf144035a20b46544075fb08 92246bce171a4d6dbd708a25656c2da4
        c248c09004c4460398535caeeb753b91
  parameters:
    version:
      name: version
      in: path
      required: true
      schema:
        type: string
        default: v1
        example: v1
      description: Audience API version
    id_or_slug:
      name: id_or_slug
      in: path
      required: true
      schema:
        type: string
      description: The ID or slug of the audience.
    institution_public_id:
      name: institution_public_id
      in: query
      required: true
      schema:
        type: string
        example: NST_PUBLIC_ID
      description: The public id of the institution.
    token:
      name: token
      in: path
      required: true
      schema:
        type: string
      description: The token to be deleted.
tags:
  - name: audiences
    description: Audience API endpoints
  - name: tokens
    description: Tokens for Audience API