Inflection.io Lists API

openapi: 3.2.0
info:
  title: Inflection Developer Lists API
  version: 1.0.0
  description: 'The Inflection Developer API (`/v2`). Authenticate with a Personal Access

    Token (`Authorization: Bearer inf_pat_...`).


    **`/v2` is `/v1` plus more.** Every `/v1` endpoint is served here unchanged,

    so a client can pin to one version and reach the whole API. On top of those

    sit reads `/v1` never had: journeys, journey and email stats with a journey

    rollup, and the email and list collections. `/v1` remains published.


    **Response envelope.** Every response is wrapped:

    `{ "data": …, "pagination": …, "errors": [...], "meta": { "status": "SUCCESS|FAILURE", "timestamp": "…" } }`.

    `data` carries the payload, `pagination` appears only on paged lists, and on

    failures `errors` is populated with `meta.status: "FAILURE"`.


    **Query parameters are camelCase**: `pageNumber`, `pageSize`, `startTime`,

    `folderId`. The journeys, emails, lists and stats reads additionally accept

    the snake_case spelling of every scalar parameter (`page_number`,

    `folder_id`, …); the contact, activity and list-member endpoints do not.

    Repeatable parameters also accept a `[]` suffix (`status[]`, `tag[]`).


    **Asynchronous contact writes.** `POST/PATCH /v2/contacts*` are processed

    asynchronously: they return **200** with a `PENDING` transaction

    acknowledgement (not the created/updated contact). Poll

    `GET /v2/contacts/transactions/{transactionId}` for the per-contact result.


    **Status-code quirks** (documented per-operation): a missing **contact** is

    reported as **400** (not 404), whereas a missing **list**, **email** or

    **journey** is **404**. For journeys and emails that also covers a

    soft-deleted record and a malformed id. Nothing returns 201 or 204.


    **Empty results are not errors.** On the paged reads, a `tag`, `folderId` or

    `search` that matches nothing returns an empty page, not a 404.


    **Errors.** Failures use the envelope above

    (`errors[].{errorCode,message,detail}`). Authentication and authorization

    failures (401/403) are returned with an empty body. The journey stats rollup

    adds `RESULT_SET_TOO_LARGE` (a **400**) when a filter matches more journeys

    than one request may cover; narrow it rather than paging further.


    **Rate limiting.** Requests are metered per tenant. Exceeding the budget

    yields **429** (empty body) on any endpoint; the `Retry-After` header gives

    the seconds to wait and `X-RateLimit-Limit` the sustained per-second budget.'
servers:
- url: https://api.inflection.io
  description: Production
security:
- PatAuth: []
tags:
- name: Lists
  description: Static and dynamic lists, and static-list members.
paths:
  /v2/lists:
    get:
      tags:
      - Lists
      operationId: listLists
      summary: List static and dynamic lists
      description: 'Both kinds behind one endpoint: static rows first, then dynamic, each

        stamped with `type`. The row shape differs by kind. Discriminate on

        `type`. Here `type` is **single-valued** rather than repeatable; omit it

        to get both. `pagination.totalElements` is the sum of the two sources''

        own counts. This endpoint takes no `folderId`.'
      parameters:
      - $ref: '#/components/parameters/ListKind'
      - $ref: '#/components/parameters/Search'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Paged lists, static first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Lists
      operationId: createList
      summary: Create a static list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListInput'
      responses:
        '200':
          description: The created list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse'
        '400':
          description: Validation error, or a list with that name already exists (`LIST_ALREADY_EXISTS`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/lists/{id}:
    get:
      tags:
      - Lists
      operationId: getList
      summary: Get a static list
      parameters:
      - $ref: '#/components/parameters/ListId'
      responses:
        '200':
          description: The list (with a refreshed member count).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      tags:
      - Lists
      operationId: updateList
      summary: Update a static list
      description: At least one of `name` or `folder` must be provided.
      parameters:
      - $ref: '#/components/parameters/ListId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUpdateInput'
      responses:
        '200':
          description: Update result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMutationResponse'
        '400':
          description: No field provided / blank name, or a rename collides with an existing list (`LIST_ALREADY_EXISTS`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      tags:
      - Lists
      operationId: deleteList
      summary: Delete a static list
      description: Soft delete. Returns **200** with a result body (not 204).
      parameters:
      - $ref: '#/components/parameters/ListId'
      responses:
        '200':
          description: Delete result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMutationResponse'
        '400':
          description: The list has dependants and cannot be deleted (`LIST_HAS_DEPENDANTS`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/lists/{id}/members:
    get:
      tags:
      - Lists
      operationId: getListMembers
      summary: Get members of a static list
      parameters:
      - $ref: '#/components/parameters/ListId'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Paged list members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembersResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Lists
      operationId: addListMembers
      summary: Add members to a static list
      description: 'Adds contacts (by id) to the list. Unknown contact ids are skipped and

        reported in `errors` with a still-successful **200** (partial success).'
      parameters:
      - $ref: '#/components/parameters/ListId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddMembersInput'
      responses:
        '200':
          description: Members added. May include `errors` for skipped ids (partial success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddMembersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/lists/{id}/members/{contactId}:
    delete:
      tags:
      - Lists
      operationId: removeListMember
      summary: Remove a member from a static list
      parameters:
      - $ref: '#/components/parameters/ListId'
      - name: contactId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Removal result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveMemberResponse'
        '404':
          description: The list, or the contact id, was not found (`NOT_FOUND` / `CONTACT_NOT_FOUND`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Member:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        companyName:
          type: string
        title:
          type: string
        phoneNumber:
          type: string
        createdTime:
          type: string
        createdBy:
          type: string
        source:
          type: string
    AddMembersResult:
      type: object
      properties:
        staticListId:
          type: string
        added:
          type: integer
    ListInput:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
        folder:
          type: string
          description: Optional folder/directory id.
    ListResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/StaticList'
        meta:
          $ref: '#/components/schemas/Meta'
    RemoveMemberResult:
      type: object
      properties:
        staticListId:
          type: string
        removed:
          type: integer
    ListMutationResult:
      type: object
      properties:
        staticListId:
          type: string
        success:
          type: boolean
    ErrorItem:
      type: object
      properties:
        errorCode:
          type: string
          examples:
          - NOT_FOUND
        message:
          type: string
        detail:
          type: string
      required:
      - errorCode
      - message
    ListUpdateInput:
      type: object
      description: At least one field must be provided.
      properties:
        name:
          type: string
          minLength: 1
        folder:
          type: string
    DynamicListSummary:
      type: object
      description: 'A dynamic list as it appears in the combined list collection. Every key

        is always present; unset ones are null.

        '
      properties:
        dynamicListId:
          type: string
        name:
          type: string
        description:
          type: string
        listType:
          type: string
          enum:
          - dynamic_list_asset
          - campaign_audience
          description: Internal classification. Unrelated to the `type` filter.
        generatedQueryContext:
          type: string
          enum:
          - person
          - person_org
        isValidQuery:
          type: boolean
          description: True once a query has been compiled for this list.
        directoryId:
          type: string
        directoryName:
          type: string
        createdAt:
          type: string
        createdBy:
          type: integer
        updatedAt:
          type: string
        updatedBy:
          type: integer
        type:
          type: string
          enum:
          - dynamic
    StaticList:
      type: object
      properties:
        staticListId:
          type: string
        name:
          type: string
        createdBy:
          type: integer
          description: Account id.
        updatedBy:
          type: integer
        createdAt:
          type: string
        updatedAt:
          type: string
        numRecords:
          type: integer
          description: Current member count.
        directoryId:
          type: string
          description: Present when the list is in a folder.
        isDeleted:
          type: boolean
    Meta:
      type: object
      description: Envelope metadata present on every response.
      properties:
        status:
          type: string
          enum:
          - SUCCESS
          - FAILURE
        timestamp:
          type: string
          format: date-time
      required:
      - status
    RemoveMemberResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RemoveMemberResult'
        meta:
          $ref: '#/components/schemas/Meta'
    ListPageResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ListItem'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/Meta'
    StaticListSummary:
      description: A static list as it appears in the combined list collection.
      allOf:
      - $ref: '#/components/schemas/StaticList'
      - type: object
        properties:
          type:
            type: string
            enum:
            - static
          flow:
            type: object
            additionalProperties: true
    AddMembersResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AddMembersResult'
        errors:
          type: array
          description: Present on partial success (e.g. skipped unknown contact ids).
          items:
            $ref: '#/components/schemas/ErrorItem'
        meta:
          $ref: '#/components/schemas/Meta'
    MembersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/Meta'
    AddMembersInput:
      type: object
      required:
      - contactIds
      properties:
        contactIds:
          type: array
          minItems: 1
          items:
            type: string
          description: Contact ids to add (resolved to contacts server-side).
    ListMutationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ListMutationResult'
        meta:
          $ref: '#/components/schemas/Meta'
    Pagination:
      type: object
      description: Present only on paged list responses.
      properties:
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalElements:
          type: integer
        totalPages:
          type: integer
    ErrorEnvelope:
      type: object
      description: Standard failure envelope.
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
        meta:
          $ref: '#/components/schemas/Meta'
    ListItem:
      description: 'A static or dynamic list. The two shapes differ; discriminate on `type`.

        '
      oneOf:
      - $ref: '#/components/schemas/StaticListSummary'
      - $ref: '#/components/schemas/DynamicListSummary'
  parameters:
    ListId:
      name: id
      in: path
      required: true
      description: Static list id.
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      required: false
      description: Items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
    PageNumber:
      name: pageNumber
      in: query
      required: false
      description: 1-based page number.
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647
        default: 1
    ListKind:
      name: type
      in: query
      required: false
      description: 'Which kind of list to return. **Single-valued**, unlike the other `type`

        filters; omit it to return both kinds. Unrelated to the `listType` field

        on a dynamic-list row, which is an internal classification.

        '
      schema:
        type: string
        enum:
        - static
        - dynamic
    Search:
      name: search
      in: query
      required: false
      description: 'Case-insensitive substring match on the asset''s name. Regex

        metacharacters are escaped, not interpreted.

        '
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid Personal Access Token. Empty body.
    BadRequest:
      description: Malformed request or validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TooManyRequests:
      description: 'Per-tenant rate limit exceeded. Empty body. Retry after the number of

        seconds given in the `Retry-After` header.

        '
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Sustained request budget, in requests per second, per tenant.
          schema:
            type: integer
    Forbidden:
      description: The PAT lacks the required scope (READ for reads, WRITE for writes). Empty body.
    NotFound:
      description: 'The requested resource was not found (`errorCode: NOT_FOUND`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    PatAuth:
      type: http
      scheme: bearer
      bearerFormat: inf_pat
      description: 'Personal Access Token or OAuth 2.1 access token, sent as a bearer

        credential (`Authorization: Bearer inf_pat_...`). Read operations

        require a token with the `READ` scope; write operations

        (POST/PATCH/DELETE) require `WRITE`.

        '
x-provenance:
  method: harvested
  publisher: Inflection.io
  source: https://docs.inflection.io/api-reference/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)