Inflection.io Product Users API

openapi: 3.2.0
info:
  title: Inflection Developer Product Users 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: Product Users
  description: 'Read product users -- the logins underneath a contact -- by id or email,

    and list them for a contact or an organization.'
paths:
  /v2/users:
    post:
      tags:
      - Product Users
      operationId: createProductUser
      summary: Create a product user
      description: 'Asynchronous. The response is a transaction to poll, not the created user,

        because product-user writes are resolved by the ingestion pipeline that

        owns per-field source precedence.


        `orgIds` is a convenience for creating memberships in the same call; each

        one becomes its own item in the transaction. An organization id that is

        neither a known organization nor already referenced by a membership is

        rejected. Organizations are never created implicitly.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUserInput'
      responses:
        '200':
          description: A pending transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A product user with this id already exists; use PATCH instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/users/transactions/{transactionId}:
    get:
      tags:
      - Product Users
      operationId: getProductUserTransaction
      summary: Get a product-user write transaction
      description: 'Poll until `status` is `DONE`. Per-item results appear once every item has

        been processed and is readable; while `PENDING` only the status and

        `createdAt` are returned.'
      parameters:
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
        description: The transaction id returned by the write.
      responses:
        '200':
          description: The transaction's current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/users/by-email/{email}:
    get:
      tags:
      - Product Users
      operationId: getProductUserByEmail
      summary: Get a product user by email
      description: '`email` is the product user''s own address. It is indexed but **not**

        unique, so an address shared by two **different** product users is

        rejected with **400** rather than picking one -- look those up by id. A

        single user belonging to several organizations is not ambiguous and

        resolves normally. Returns the same membership shape as

        `/v2/users/{id}`.'
      parameters:
      - $ref: '#/components/parameters/ProductUserEmail'
      responses:
        '200':
          description: 'The product user, as one membership. `data.properties` carries every

            remaining column of the stored row.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserResponse'
        '400':
          description: 'Malformed request, or the email is shared by more than one product

            user (`errorCode` is then a bad-request, not a 404).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/users/{id}:
    get:
      tags:
      - Product Users
      operationId: getProductUser
      summary: Get a product user
      description: 'One membership for this product user, carrying the login''s fields and

        that organization''s fields together. A product user in several

        organizations has one row per organization; this returns one of them

        under a stable order, preferring a row that names an organization, and

        reports which one in `orgId`. Use `/v2/contacts/{id}/users` to see all

        of them.'
      parameters:
      - $ref: '#/components/parameters/ProductUserId'
      responses:
        '200':
          description: 'The product user, as one membership. `data.properties` carries every

            remaining column of the stored row.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      tags:
      - Product Users
      operationId: updateProductUser
      summary: Update a product user
      description: 'Asynchronous, like create. The response is a transaction to poll.

        Properties are merged by the ingestion pipeline; the email cannot be

        changed here.'
      parameters:
      - $ref: '#/components/parameters/ProductUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUserPatch'
      responses:
        '200':
          description: A pending transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/contacts/{id}/users:
    get:
      tags:
      - Product Users
      operationId: listContactProductUsers
      summary: List a contact's product users
      description: 'One entry per membership, so a product user in three organizations

        appears three times with a different `orgId`. Each entry carries the

        login''s fields **and** that organization''s fields.'
      parameters:
      - $ref: '#/components/parameters/ContactId'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Paged memberships.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserMembershipListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/orgs/{id}/users:
    get:
      tags:
      - Product Users
      operationId: listOrganizationProductUsers
      summary: List an organization's product users
      description: One entry per membership, carrying the login's fields and this organization's fields.
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Paged memberships.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUserMembershipListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  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'
  parameters:
    ProductUserEmail:
      name: email
      in: path
      required: true
      description: The product user's own email address. Max 200 characters.
      schema:
        type: string
        minLength: 1
        maxLength: 200
    PageSize:
      name: pageSize
      in: query
      required: false
      description: Items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
    ProductUserId:
      name: id
      in: path
      required: true
      description: Product-user id, as your product supplied it. Max 100 characters.
      schema:
        type: string
        minLength: 1
        maxLength: 100
    ContactId:
      name: id
      in: path
      required: true
      description: Contact id.
      schema:
        type: string
    PageNumber:
      name: pageNumber
      in: query
      required: false
      description: 1-based page number.
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647
        default: 1
    OrganizationId:
      name: id
      in: path
      required: true
      description: Organization id, as your product supplied it. Max 100 characters.
      schema:
        type: string
        minLength: 1
        maxLength: 100
  schemas:
    ProductUserInput:
      type: object
      properties:
        userId:
          type: string
          description: Your own product-user id. Omit it and one is generated for you.
        email:
          type: string
          format: email
          description: Required. Lower-cased and trimmed before storage.
        orgIds:
          type: array
          items:
            type: string
          maxItems: 100
          description: Organizations to link the user to, each its own transaction item.
        properties:
          type: object
          additionalProperties: true
          description: Product-user properties, keyed in snake_case.
      required:
      - email
    ProductUserPatch:
      type: object
      properties:
        properties:
          type: object
          additionalProperties: true
          description: Properties to set, keyed in snake_case.
      required:
      - properties
    ErrorItem:
      type: object
      properties:
        errorCode:
          type: string
          examples:
          - NOT_FOUND
        message:
          type: string
        detail:
          type: string
      required:
      - errorCode
      - message
    ProductUserTransactionItem:
      type: object
      properties:
        userId:
          type: string
        orgId:
          type: string
          description: Present on a membership item, absent on the user itself.
        operation:
          type: string
          enum:
          - UPSERT_PRODUCT_USER
          - UPSERT_PRODUCT_USER_ORGANISATION_MAPPING
          - DELETE_PRODUCT_USER_ORGANISATION_MAPPING_SOURCE
        status:
          type: string
          enum:
          - CREATED
          - UPDATED
          - NO_CHANGE
          - DELETED
          - FAILED
        error:
          type: string
          description: Present only when this item failed.
    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
    ProductUserMembership:
      type: object
      description: One product user's membership of one organization.
      properties:
        id:
          type: string
          description: Product-user id.
        email:
          type: string
          description: The product user's own email address.
        orgId:
          type: string
          nullable: true
          description: Organization id, or `null` when the membership records no organization.
        personId:
          type: string
          nullable: true
          description: Id of the contact this product user resolved to.
        properties:
          type: object
          additionalProperties: true
          description: 'The login''s fields **and** this organization''s fields, keyed on

            column name. Where an organization field''s name collides with a

            login field''s, the organization one carries a `_pom` suffix, so both

            values are present and distinct.

            '
      required:
      - id
    ProductUserTransactionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProductUserTransaction'
        meta:
          $ref: '#/components/schemas/Meta'
    ProductUserMembershipListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProductUserMembership'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/Meta'
    ProductUserResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ProductUserMembership'
        meta:
          $ref: '#/components/schemas/Meta'
    ProductUserTransaction:
      type: object
      properties:
        transactionId:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - DONE
          - ERROR
          description: '`ERROR` means the write could not be queued and none of it was applied.

            '
        createdAt:
          type: string
          format: date-time
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProductUserTransactionItem'
          description: Present once the transaction is no longer pending.
      required:
      - transactionId
      - status
    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'
  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)