openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorIQ Payments Creator Payment Info API
  description: 'The Payments API exposes read-only access to a partner''s creator payouts,

    payables and creator payment-info collection status. It is the public

    counterpart of the CreatorIQ Payments product and lets integrators reconcile

    payout data, monitor payable statuses and track which creators still need to

    submit their payment information.


    ## Key Use Cases:

    - **Reconcile payouts**: Retrieve a paginated list of payouts (creator view) with amounts, statuses and payout dates to reconcile against your own ledger.

    - **Track payables**: List individual payables with their campaign, currency, due/completion dates and current status.

    - **Monitor payment-info collection**: Identify creators whose payment info, tax info or approval is still pending so payouts are not blocked.


    ## Authentication

    All requests are authenticated with your API key sent in the `X-API-KEY`

    header. The platform gateway validates the key and implicitly scopes every

    response to the authenticated partner (and division, when the key is

    division-scoped).


    ## Pagination

    All endpoints use keyset (cursor) pagination. Send `PageSize`, `Direction`,

    `SortField` and `SortOrder` on the first request, then pass the `EndCursor`

    (forward) or `StartCursor` (backward) returned in `Metadata.Pagination` as the

    `Cursor` value to fetch the next page.

    '
  termsOfService: https://www.creatoriq.com/legal/terms-of-use
  contact:
    name: CreatorIQ
    url: https://www.creatoriq.com
    email: support@creatoriq.com
  license:
    url: https://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
- url: https://apis.creatoriq.com
  description: Live
security:
- apiKey: []
tags:
- name: Creator Payment Info
  description: Creator payment-info collection status
paths:
  /payments/v1/publishers/payment-info-collection-status:
    get:
      tags:
      - Creator Payment Info
      summary: Get creators' payment info collection status
      description: 'Returns a paginated list describing, per creator, whether payment info,

        tax info and approval have been collected. Replaces the legacy Creator

        Payment Info Status report and lets you identify creators whose payouts

        are blocked pending information.

        '
      operationId: getPaymentInfoCollectionStatus
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Direction'
      - $ref: '#/components/parameters/SortOrder'
      - name: SortField
        in: query
        description: Field to sort by. Currently only PublisherId is supported.
        required: true
        schema:
          const: PublisherId
          examples:
          - PublisherId
        examples:
          default:
            value: PublisherId
      - name: PayableStatus
        in: query
        description: Filters by whether the creator is payable (eligible to be paid).
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          examples:
          - 'true'
        examples:
          default:
            value: 'true'
      - name: PaymentInfoStatus
        in: query
        description: 'Comma-separated list of payment-info statuses to filter by. Valid values: Not Submitted, Received, Invalid.'
        required: false
        schema:
          type: string
          examples:
          - Received,Invalid
        examples:
          default:
            value: Received,Invalid
      - name: ApprovalStatus
        in: query
        description: Filters by approval state. `true` (approved), `false` (not approved) or `null` (no approval required).
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - 'null'
          examples:
          - 'true'
        examples:
          default:
            value: 'true'
      responses:
        '200':
          description: A paginated list of creator payment-info collection statuses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorPaymentInfoStatusCollectionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
components:
  responses:
    ForbiddenError:
      description: Forbidden - the API key is missing, invalid or lacks access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequestError:
      description: Bad Request - invalid or missing query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CollectionMetadata:
      type: object
      description: Metadata wrapper carrying pagination details.
      properties:
        Pagination:
          $ref: '#/components/schemas/PaginationResponse'
      required:
      - Pagination
    PaginationResponse:
      type: object
      description: Keyset pagination metadata.
      properties:
        StartCursor:
          type:
          - string
          - 'null'
          description: Cursor pointing at the first row of the current page. Pass it with `Direction=backward` to page back.
          examples:
          - cGF5b3V0X2RhdGU7OzEyMzQ1
        EndCursor:
          type:
          - string
          - 'null'
          description: Cursor pointing at the last row of the current page. Pass it with `Direction=forward` to page ahead.
          examples:
          - cGF5b3V0X2RhdGU7OzEyMzk5
        HasNextPage:
          type: boolean
          description: Whether more items are available after the current page.
          examples:
          - true
        HasPreviousPage:
          type: boolean
          description: Whether items are available before the current page.
          examples:
          - false
        PageSize:
          type: integer
          description: Number of items returned in the current page.
          examples:
          - 50
      required:
      - StartCursor
      - EndCursor
      - HasNextPage
      - HasPreviousPage
      - PageSize
    CreatorPaymentInfoStatus:
      type: object
      description: Payment-info collection status for a single creator.
      properties:
        PublisherId:
          type: integer
          description: Creator (publisher) id.
          examples:
          - 20985049
        PayableStatus:
          type: boolean
          description: Whether the creator is payable (eligible to be paid).
          examples:
          - true
        PaymentInfoStatus:
          type:
          - string
          - 'null'
          description: 'Payment-info collection status: Not Submitted, Received or Invalid.'
          examples:
          - Received
        TaxInfoStatus:
          type:
          - string
          - 'null'
          description: Tax-info collection status.
          examples:
          - Received
        ApprovalStatus:
          type:
          - boolean
          - 'null'
          description: Approval state, or null when no approval is required.
          examples:
          - true
        PayoutCurrency:
          type:
          - string
          - 'null'
          description: The creator's payout currency (ISO 4217).
          examples:
          - USD
      required:
      - PublisherId
      - PayableStatus
    ErrorResponse:
      type: object
      description: Standard error response body.
      properties:
        ErrorMessage:
          type: string
          description: Human-readable error message.
          examples:
          - 'Invalid SortField, need one of: PayoutDate, PublisherID, CreatedAt'
        Type:
          type: string
          description: Error type identifier.
          examples:
          - InvalidPayoutFiltersError
        Details:
          type: array
          description: Additional error details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        Context:
          type: object
          description: Additional error context.
      required:
      - ErrorMessage
    ErrorDetail:
      type: object
      description: A single error detail entry.
      properties:
        Type:
          type: string
          description: Detail type.
          examples:
          - validation
        Message:
          type: string
          description: Detail message.
          examples:
          - PageSize must not exceed 200
        Context:
          type: object
          description: Detail context.
      required:
      - Type
    CreatorPaymentInfoStatusCollectionResponse:
      type: object
      description: A page of creator payment-info statuses with pagination metadata.
      properties:
        Data:
          type: array
          description: Creator payment-info statuses in this page.
          items:
            $ref: '#/components/schemas/CreatorPaymentInfoStatus'
        Metadata:
          $ref: '#/components/schemas/CollectionMetadata'
      required:
      - Data
      - Metadata
  parameters:
    SortOrder:
      name: SortOrder
      in: query
      description: Sort order for the selected `SortField`.
      required: true
      schema:
        type: string
        enum:
        - asc
        - desc
        examples:
        - desc
      examples:
        default:
          value: desc
    Cursor:
      name: Cursor
      in: query
      description: Base64 keyset pagination cursor. Pass the `EndCursor` (forward) or `StartCursor` (backward) from the previous response's `Metadata.Pagination`. Omit on the first request.
      required: false
      schema:
        type: string
        examples:
        - cGF5b3V0X2RhdGU7OzEyMzQ1
      examples:
        default:
          value: cGF5b3V0X2RhdGU7OzEyMzQ1
    PageSize:
      name: PageSize
      in: query
      description: Number of items to return per page. Must be a positive integer, capped at 200.
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 200
        examples:
        - 50
      examples:
        default:
          value: 50
    Direction:
      name: Direction
      in: query
      description: Pagination direction relative to the supplied cursor.
      required: true
      schema:
        type: string
        enum:
        - forward
        - backward
        examples:
        - forward
      examples:
        default:
          value: forward
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-KEY
      in: header