> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inboxapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search threads

> The threads that best match `q`, most relevant first, in one page. Use it to find a conversation by a person's name or username; to page through the best 1,000 matches in inbox order, use `q` on List threads.



## OpenAPI

````yaml /v2/openapi.json get /threads/search
openapi: 3.1.0
info:
  title: Inboxapp API
  version: 2.0.0
  description: >-
    The Inboxapp API gives you access to your team's conversations and the CRM
    state around them. Every platform uses the same resources, so your code asks
    what an account can do instead of which platform it is on.


    ## The data model


    ```txt

    Team

    ├── Members                people on your team

    ├── Account links          your accounts on each platform

    │   └── Threads            one conversation with one profile

    │       └── Messages

    ├── Contacts               your record of a person

    │   └── Profiles           their account on each platform

    ├── Tags                   labels on contacts

    └── Statuses               pipeline stages of contacts

    ```


    | Resource | What it is |

    | --- | --- |

    | **Platform** | A messaging platform available to your team, with what it
    supports |

    | **Account link** | One of your accounts on a platform. Messages are sent
    from one |

    | **Profile** | One person's account on one platform |

    | **Contact** | Your team's record of a person. Groups one or more of their
    profiles |

    | **Thread** | A conversation between one account link and one profile |

    | **Message** | A message in a thread, which you can send, edit, unsend and
    react to |

    | **Tag** | A label on a contact. A contact can have several |

    | **Status** | A pipeline stage. A contact has at most one |

    | **Member** | A person on your team, who can be assigned threads and
    contacts |


    ## Authentication


    Send your API token in the `Authorization` header: `Authorization: Bearer
    <token>`. The token decides the team, so no path or parameter names one.


    ## Member view


    Some state belongs to one member rather than the team: each member has their
    own read status for a thread. The API isn't a member, so it takes the team
    owner's view. A thread's `unread` is whether the owner has it unread, and
    setting it marks the thread read or unread for the owner.


    ## Profiles and contacts


    A **profile** holds what the platform says about a person: `username`,
    `displayName`, `bio`, follower counts. A **contact** holds what your team
    says about them: `statusId`, `tagIds`, `notes`, `valuation`, `assigneeId`. A
    contact groups one or more profiles.


    A thread is always with one profile, and its `contactId` points to the
    contact that profile belongs to.


    ```json

    {
      "id": "nq2r8v5ycx1t7m4hj6kd3wzb",
      "profiles": [
        {
          "id": "n7kxqm5d9iu2sgdf6jbw4h36",
          "platform": "twitter",
          "platformId": "1876543210987654321",
          "username": "sarahchen",
          "handle": "@sarahchen",
          "displayName": "Sarah Chen"
        }
      ],
      "statusId": "r3km7xj9wq5p2bvnhfdteoly",
      "tagIds": ["t9wq5p2bvnhfdteolyr3km7x"],
      "notes": "Asked for a demo of the reporting API.",
      "valuation": 12000,
      "assigneeId": null
    }

    ```


    Reads never create a contact. Someone your team has never talked to or
    imported has none: message them by sending to a `profile` target.


    ## IDs


    | Field | What it is | Use it for |

    | --- | --- | --- |

    | `id`, every `…Id` | An Inboxapp ID | Paths and references. Paths only take
    Inboxapp IDs |

    | `platformId` | The ID the platform gives the object: its user,
    conversation or message | Matching against your own data |


    A `platformId` always comes with a `platform`, and means nothing without it.
    To find a resource by its platform identity, filter its collection:


    ```txt

    GET /contacts?platform=twitter&platformId=1876543210987654321

    ```


    No match is an empty `data` array, never a `404`.


    ## Platforms and capabilities


    Platforms differ: one lets you edit a message, another doesn't. The API
    expresses that as **capabilities** instead of per-platform endpoints. `GET
    /platforms` lists the platforms available to your team, with their
    capabilities and limits.


    ```txt

    Platform capabilities              the most any account on the platform can
    do
      └── Account link capabilities    narrowed for this account
            └── Thread restrictions    disabled in this conversation
    ```


    Check both before you call:


    ```typescript

    function canEdit(accountLink: AccountLink, thread: Thread): boolean {
      return (
        accountLink.capabilities.includes("message:edit") &&
        !thread.restrictions.includes("message:edit")
      );
    }

    ```


    | Failure | Meaning |

    | --- | --- |

    | `422 capabilityNotSupported` | The account link can't do this |

    | `422 threadRestricted` | The platform disabled it in this conversation |

    | `422 mutationWindowClosed` | The platform's time window for it has passed
    |

    | `403 platformNotAvailable` | The resource is on a platform your team can't
    use |


    New platforms may be added within v2, so treat `platform` as an open string.
    Code that checks capabilities keeps working when they are. See [Platforms
    and capabilities](https://docs.inboxapp.com/v2/platforms) for what each
    platform supports.


    ## Platform data


    Fields every platform has are top-level. Fields only one platform has are in
    `platformData`, tagged by `_tag`:


    ```json

    {
      "platformData": { "_tag": "twitter", "encrypted": true }
    }

    ```


    Ignore tags you don't know.


    ## Responses


    Every documented field is present: a value that doesn't apply is `null`.
    Timestamps are ISO 8601 in UTC. Within v2, fields, enum values and error
    codes may be added, so ignore unknown fields and handle unknown enum values.


    ## Pagination


    Collections return `{ "data": [...], "nextCursor": "..." }`. Pass
    `nextCursor` back as `cursor`, with the same filters, to read the next page.
    It is `null` on the last page. `limit` defaults to 50, up to 100. See
    [Pagination](https://docs.inboxapp.com/v2/reference/pagination).


    ## Query parameters


    To pass several values, repeat the key:


    ```txt

    ?accountLinkId=a&accountLinkId=b

    ```


    Brackets (`ids[]=…`) and comma-separated values aren't accepted. See [Query
    parameters](https://docs.inboxapp.com/v2/reference/query-parameters).


    ## Expansion


    References are IDs by default. Use `expand` to embed the related resource
    next to its ID field, `contact` beside `contactId`, at most 4 per request:


    ```txt

    GET /threads?expand=contact&expand=profile

    ```


    ## Updates


    In `PATCH` bodies, omitted fields are left unchanged, and `null` clears a
    nullable field.


    ## Errors


    Every error has the same body:


    ```json

    {
      "code": "capabilityNotSupported",
      "message": "This account can't perform this operation.",
      "details": { "capability": "message:edit" },
      "requestId": "…"
    }

    ```


    Branch on `code`, the contract. `message` can be shown to a person and may
    change. `details` is `null` or the object documented for that code. Share
    `requestId`, also in the `X-Request-Id` header, when you contact support.
    See [Error codes](https://docs.inboxapp.com/v2/reference/errors).


    ## Sending safely


    `POST /messages` takes an optional `Idempotency-Key` header. Retrying with
    the same key never sends twice: a replay returns the original result.
    Without a key, a retry can send twice.


    ## Rate limits


    Each team can make 300 requests per minute, 10,000 per hour and 100,000 per
    day. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
    `X-RateLimit-Reset`. Past a limit, requests fail with `429 rateLimited` and
    a `Retry-After` header. See [Rate
    limits](https://docs.inboxapp.com/v2/reference/rate-limits).
  summary: Read and act on your team's conversations across messaging platforms.
servers:
  - url: https://inboxapp.com/api/v2
security: []
tags:
  - name: Platforms
    description: >-
      The messaging platforms available to the team, with what each one
      supports.
  - name: Team
    description: >-
      The team the API token belongs to, and its members: the Inboxapp users who
      work in it.
  - name: Account Links
    description: >-
      Platform accounts the team connected to Inboxapp. Every thread belongs to
      one, and messages are sent from one.
  - name: Contacts
    description: >-
      The team's record of a person, holding its CRM state: status, tags, notes,
      valuation and default assignee. A contact groups one or more profiles, a
      person's accounts on the platforms.
  - name: People
    description: >-
      People on the platforms, found through the team's account links whether or
      not Inboxapp knows them yet.
  - name: Threads
    description: Conversations between one of the team's account links and one profile.
  - name: Views
    description: >-
      The named sets of threads the team works from: system views and the views
      its members saved.
  - name: Messages
    description: >-
      Messages in a thread, and sending, editing, unsending and reacting to them
      on the platform.
  - name: Relationships
    description: >-
      How an account link stands with a profile on the platform, and requests
      that change it.
  - name: Tags
    description: Labels the team puts on contacts.
  - name: Statuses
    description: >-
      The pipeline stages a contact can be in, such as a deal stage. A contact
      has at most one.
  - name: Colors
    description: The colors of Inboxapp's palette, for tags and statuses.
  - name: Events
    description: >-
      Changes in the team, as delivered to v2 webhooks. Each event names the
      object that changed and carries only the values of the change; read the
      object for its current state. Events are kept for 7 days, up to 25,000 per
      team.
paths:
  /threads/search:
    get:
      tags:
        - Threads
      summary: Search threads
      description: >-
        The threads that best match `q`, most relevant first, in one page. Use
        it to find a conversation by a person's name or username; to page
        through the best 1,000 matches in inbox order, use `q` on List threads.
      operationId: threads.search
      parameters:
        - name: accountLinkId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Cuid2'
            description: >-
              Threads of these account links. Repeat the key to match any of
              several.
          required: false
        - name: platform
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Platform'
            description: Repeat the key to match any of several.
          required: false
        - name: contactId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Cuid2'
            description: >-
              Threads with these contacts. With `accountLinkId`, finds the
              thread between an account and a contact. Repeat the key to match
              any of several.
          required: false
        - name: view
          in: query
          schema:
            type: string
            minLength: 1
            description: >-
              A view's `id` from List views: lists the threads that view lists,
              in place of `folder`. Every other filter narrows it. A cursor
              issued for a saved view is `invalidCursor` once the view changes.
          required: false
        - name: folder
          in: query
          schema:
            type: string
            enum:
              - inbox
              - noReply
              - requests
              - archived
              - all
            description: >-
              Defaults to `inbox`, threads that are neither archived nor
              requests. `noReply` is the `inbox` threads whose latest activity
              is inbound. `requests` holds unarchived threads where `isRequest`
              is true. `archived` includes requests. `all` spans every folder.
              Every other filter narrows the folder. Each folder is also a view:
              `inbox`, `awaitingReply` for `noReply`, `requests`, `archived` and
              `all`.
          required: false
        - name: tag
          in: query
          schema:
            type: array
            items:
              type: string
              description: >-
                A tag, by ID or by name. Names match ignoring case and accents.
                When a value is one tag's ID and another's name, the ID wins.
            description: >-
              Threads whose contact has one of these tags. Repeat the key to
              match any of several.
          required: false
        - name: status
          in: query
          schema:
            type: array
            items:
              type: string
              description: >-
                A status, by ID or by name. Names match ignoring case and
                accents. When a value is one status's ID and another's name, the
                ID wins.
            description: >-
              Threads whose contact has one of these statuses. Repeat the key to
              match any of several.
          required: false
        - name: assigneeId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Cuid2'
            description: >-
              Threads whose `assigneeId`, the thread's own assignee or else its
              contact's, is one of these members. Repeat the key to match any of
              several.
          required: false
        - name: unassigned
          in: query
          schema:
            type: boolean
            description: >-
              `true` keeps threads with no assignee, including through their
              contact. Not combinable with `assigneeId`.
          required: false
        - name: campaignId
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Cuid2'
            description: >-
              Threads these campaigns sent a message in. Campaign sends archive
              the thread, so pair it with `folder=archived` or `all`. Repeat the
              key to match any of several.
          required: false
        - name: q
          in: query
          schema:
            type: string
            minLength: 1
            description: >-
              Matched with typo tolerance against profile display names and
              usernames, the contact's name and the activity preview.
          required: true
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            description: How many best matches to return, from 1 to 50. Defaults to 25.
          required: false
        - name: expand
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - profile
                - contact
                - accountLink
                - assignee
            description: >-
              Related resources to embed next to their ID field, one path per
              key, at most 4.
            maxItems: 4
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadSearchPage'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformNotAvailable'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewNotFound'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimited'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Internal'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchUnavailable'
      security:
        - bearerAuth: []
components:
  schemas:
    Cuid2:
      type: string
      pattern: ^[0-9a-z]+$
    Platform:
      type: string
      description: >-
        The platform. Every team can use twitter, linkedin, whatsapp; a team may
        have others enabled.
      examples:
        - twitter
        - linkedin
        - whatsapp
    ThreadSearchPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Thread'
        nextCursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass it back as `cursor`, with the same filters, to read the next
            page. Null on the last page.
      required:
        - data
        - nextCursor
      additionalProperties: false
      description: 'Most relevant first, in one page: `nextCursor` is always null.'
    InvalidRequest:
      type: object
      properties:
        code:
          type: string
          enum:
            - invalidRequest
        message:
          type: string
        details:
          type: object
          properties:
            issues:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      anyOf:
                        - type: string
                        - type: number
                        - type: string
                          enum:
                            - Infinity
                            - '-Infinity'
                            - NaN
                  message:
                    type: string
                required:
                  - path
                  - message
                additionalProperties: false
          required:
            - issues
          additionalProperties: false
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    Unauthorized:
      type: object
      properties:
        code:
          type: string
          enum:
            - unauthorized
        message:
          type: string
        details:
          type: 'null'
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    PlatformNotAvailable:
      type: object
      properties:
        code:
          type: string
          enum:
            - platformNotAvailable
        message:
          type: string
        details:
          type: object
          properties:
            platform:
              $ref: '#/components/schemas/Platform'
          required:
            - platform
          additionalProperties: false
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    ViewNotFound:
      type: object
      properties:
        code:
          type: string
          enum:
            - viewNotFound
        message:
          type: string
        details:
          type: 'null'
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    RateLimited:
      type: object
      properties:
        code:
          type: string
          enum:
            - rateLimited
        message:
          type: string
        details:
          type: object
          properties:
            window:
              type: string
              enum:
                - minute
                - hour
                - day
            limit:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            resetAt:
              type: string
              format: date-time
              examples:
                - '2026-09-14T10:32:00.000Z'
          required:
            - window
            - limit
            - resetAt
          additionalProperties: false
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    Internal:
      type: object
      properties:
        code:
          type: string
          enum:
            - internal
        message:
          type: string
        details:
          type: 'null'
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    SearchUnavailable:
      type: object
      properties:
        code:
          type: string
          enum:
            - searchUnavailable
        message:
          type: string
        details:
          type: 'null'
        requestId:
          type: string
      required:
        - code
        - message
        - details
        - requestId
      additionalProperties: false
    Thread:
      type: object
      properties:
        id:
          type: string
        platform:
          allOf:
            - $ref: '#/components/schemas/Platform'
            - description: Always the platform of the thread's account link and profile.
        platformId:
          anyOf:
            - type: string
              description: >-
                The ID the platform gives this object. Only meaningful next to
                its `platform`.
            - type: 'null'
          description: >-
            The conversation's ID on the platform. Null until the first message
            creates the conversation there.
        accountLinkId:
          type: string
          description: >-
            An account link: a platform account the team connected to Inboxapp,
            the team's side of a conversation.
        profileId:
          type: string
          description: 'A profile: one person''s account on one platform. Not a contact ID.'
        contactId:
          type: string
          description: >-
            A contact: the team's record of the person, with their status, tags,
            notes, valuation and default assignee.
        assigneeId:
          anyOf:
            - type: string
              description: 'A member: a person on the team.'
            - type: 'null'
          description: The thread's own assignee, else its contact's default.
        isRequest:
          type: boolean
          description: >-
            True while the conversation is an incoming request the account
            hasn't replied to or accepted. Requests are in the `requests`
            folder, not `inbox`.
        acceptanceState:
          type: string
          enum:
            - required
            - notRequired
            - unknown
          description: >-
            Whether the platform needs the account to accept the conversation
            before replying normally. `unknown` when the platform doesn't say.
            Independent of `isRequest`.
        archived:
          type: boolean
        unread:
          type: boolean
          description: >-
            Marked unread in Inboxapp for the team owner, whose view the API
            takes. A thread no one has opened yet is not unread.
        restrictions:
          type: array
          items:
            type: string
            enum:
              - message:send
              - message:edit
              - message:delete:self
              - message:unsend
              - message:react
              - message:reply
              - message:forward
              - message:answer
              - media:image
              - media:video
              - media:gif
              - media:file
              - media:audio
              - thread:typing:send
              - thread:typing:receive
              - thread:seen:receive
              - thread:seen:send
              - thread:message-requests
              - thread:delete:remote
              - directory:typeahead
              - thread:archive:observe
              - thread:archive:mutate
              - thread:read:observe
              - thread:read:mutate
              - thread:folders:import
              - profile:follow
              - profile:unfollow
              - profile:connect
              - profile:connect:note
              - profile:resolve:id
              - profile:resolve:username
          description: >-
            Capabilities the platform disables in this conversation, on top of
            the account link's `capabilities`. Using one fails with
            `threadRestricted`.
        syncing:
          type: boolean
          description: >-
            True while Inboxapp imports the conversation's older messages, so
            the message list may be incomplete.
        typingIndicators:
          type: string
          enum:
            - enabled
            - disabled
            - teamDefault
          description: >-
            Whether Inboxapp sends typing indicators to the platform while
            someone composes in this thread. `teamDefault` follows the team's
            setting.
        readReceipts:
          type: string
          enum:
            - onOpen
            - onReply
            - teamDefault
          description: >-
            When Inboxapp tells the contact you've read their messages in this
            thread. Replying always does; `onOpen` also does when a team member
            opens the thread, `onReply` waits for the reply. `teamDefault`
            follows the team's setting.
        lastMessage:
          anyOf:
            - $ref: '#/components/schemas/LastMessage'
            - type: 'null'
        activity:
          anyOf:
            - $ref: '#/components/schemas/ThreadActivity'
            - type: 'null'
        seen:
          anyOf:
            - $ref: '#/components/schemas/ThreadSeen'
            - type: 'null'
        delivered:
          anyOf:
            - $ref: '#/components/schemas/ThreadDelivered'
            - type: 'null'
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
        accountLink:
          $ref: '#/components/schemas/AccountLink'
        profile:
          $ref: '#/components/schemas/Profile'
        contact:
          $ref: '#/components/schemas/Contact'
        assignee:
          $ref: '#/components/schemas/Member'
      required:
        - id
        - platform
        - platformId
        - accountLinkId
        - profileId
        - contactId
        - assigneeId
        - isRequest
        - acceptanceState
        - archived
        - unread
        - restrictions
        - syncing
        - typingIndicators
        - readReceipts
        - lastMessage
        - activity
        - seen
        - delivered
        - createdAt
      additionalProperties: false
      description: A conversation between one of the team's account links and one profile.
    LastMessage:
      type: object
      properties:
        id:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: >-
            `inbound` was received from the other side. `outbound` was sent by
            the account link.
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - id
        - direction
        - createdAt
      additionalProperties: false
      description: The thread's latest message. Get it for its content.
    ThreadActivity:
      type: object
      properties:
        preview:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            One line as the inbox shows it, such as the message text or `You
            reacted with 👍`. Null when there is nothing to show.
        previewKind:
          anyOf:
            - type: string
              enum:
                - contact
                - location
                - poll
                - event
                - videoCall
                - voiceCall
                - disappearingTimer
            - type: 'null'
          description: >-
            What `preview` describes when the latest message is rich content,
            which the inbox shows as an icon beside it. Null for anything else,
            such as plain text or a reaction.
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: '`outbound` when the account link acted.'
        at:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - preview
        - previewKind
        - direction
        - at
      additionalProperties: false
      description: >-
        The thread's latest activity: a message, or a reaction since. `at` is
        when it happened, which is not always the thread's position in a list:
        see `order`.
    ThreadSeen:
      type: object
      properties:
        messageId:
          type: string
          description: >-
            The latest of the account link's messages the profile has seen.
            Every earlier message counts as seen too.
        at:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - messageId
        - at
      additionalProperties: false
      description: >-
        When the profile last read the account link's messages, on platforms
        with `thread:seen:receive`. Null until they have.
    ThreadDelivered:
      type: object
      properties:
        messageId:
          type: string
          description: >-
            The latest of the account link's messages known to have reached the
            profile's device. Every earlier message counts as delivered too, as
            does any message `seen` covers, even when this names an earlier one.
        at:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - messageId
        - at
      additionalProperties: false
      description: >-
        When the account link's messages last reached the profile's device, on
        platforms that report delivery. Null until they have, or when the
        platform doesn't report it.
    AccountLink:
      type: object
      properties:
        id:
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        platformId:
          type: string
          description: >-
            The ID the platform gives this object. Only meaningful next to its
            `platform`.
        username:
          anyOf:
            - type: string
              description: The platform username, without a display prefix such as `@`.
              examples:
                - jane
            - type: 'null'
        displayName:
          anyOf:
            - type: string
            - type: 'null'
        avatarUrl:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - active
            - offline
            - paused
          description: >-
            `active` sends and syncs. `paused` is stopped for the reasons in
            `pauseReasons`, and resumes once none remain. `offline` lost its
            connection to the platform and must be reconnected in Inboxapp.
        pauseReasons:
          type: array
          items:
            type: string
          description: Why the account link is paused. New reasons may be added.
          examples:
            - - billing
            - - no-xchat
        capabilities:
          type: array
          items:
            type: string
            enum:
              - message:send
              - message:edit
              - message:delete:self
              - message:unsend
              - message:react
              - message:reply
              - message:forward
              - message:answer
              - media:image
              - media:video
              - media:gif
              - media:file
              - media:audio
              - thread:typing:send
              - thread:typing:receive
              - thread:seen:receive
              - thread:seen:send
              - thread:message-requests
              - thread:delete:remote
              - directory:typeahead
              - thread:archive:observe
              - thread:archive:mutate
              - thread:read:observe
              - thread:read:mutate
              - thread:folders:import
              - profile:follow
              - profile:unfollow
              - profile:connect
              - profile:connect:note
              - profile:resolve:id
              - profile:resolve:username
          description: >-
            What this account can do: its platform's capabilities, narrowed for
            this account. An operation it lacks fails with
            `capabilityNotSupported`.
        syncedAt:
          anyOf:
            - type: string
              format: date-time
              examples:
                - '2026-09-14T10:32:00.000Z'
            - type: 'null'
          description: >-
            When Inboxapp finished importing the account's conversations. Null
            until then.
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - id
        - platform
        - platformId
        - username
        - displayName
        - avatarUrl
        - status
        - pauseReasons
        - capabilities
        - syncedAt
        - createdAt
      additionalProperties: false
      description: >-
        A platform account the team connected to Inboxapp. Every conversation
        and message goes through one.
    Profile:
      type: object
      properties:
        id:
          type: string
        platform:
          $ref: '#/components/schemas/Platform'
        platformId:
          type: string
          description: >-
            The ID the platform gives this object. Only meaningful next to its
            `platform`.
        username:
          type: string
          description: The platform username, without a display prefix such as `@`.
          examples:
            - jane
        handle:
          type: string
          description: >-
            The username as the platform displays it. Show this, and look up by
            `username`.
          examples:
            - '@jane'
        displayName:
          type: string
        avatarUrl:
          anyOf:
            - type: string
            - type: 'null'
        bio:
          anyOf:
            - type: string
            - type: 'null'
        location:
          anyOf:
            - type: string
            - type: 'null'
        websiteUrl:
          anyOf:
            - type: string
            - type: 'null'
        websiteDomain:
          anyOf:
            - type: string
            - type: 'null'
        verified:
          type: boolean
          description: >-
            The platform vouches for the account, such as with an X badge.
            Platform-specific badges are in `platformData`.
        isOrganization:
          type: boolean
          description: A company or page rather than a person.
        isProtected:
          type: boolean
          description: The account's posts are visible only to approved followers.
        followerCount:
          anyOf:
            - type: number
            - type: string
              enum:
                - Infinity
                - '-Infinity'
                - NaN
            - type: 'null'
        followingCount:
          anyOf:
            - type: number
            - type: string
              enum:
                - Infinity
                - '-Infinity'
                - NaN
            - type: 'null'
        postCount:
          anyOf:
            - type: number
            - type: string
              enum:
                - Infinity
                - '-Infinity'
                - NaN
            - type: 'null'
        engagementCount:
          anyOf:
            - type: number
            - type: string
              enum:
                - Infinity
                - '-Infinity'
                - NaN
            - type: 'null'
          description: On X, how many posts the user has liked.
        listedCount:
          anyOf:
            - type: number
            - type: string
              enum:
                - Infinity
                - '-Infinity'
                - NaN
            - type: 'null'
          description: On X, how many lists include the profile.
        accountStatus:
          type: string
          enum:
            - active
            - suspended
            - notFound
          description: >-
            `suspended` by the platform, or `notFound` when deleted or
            deactivated.
        platformCreatedAt:
          anyOf:
            - type: string
              format: date-time
              examples:
                - '2026-09-14T10:32:00.000Z'
            - type: 'null'
          description: When the account was created on the platform.
        profileUrl:
          anyOf:
            - type: string
            - type: 'null'
        updatedAt:
          type: string
          description: When Inboxapp last stored a change to this profile.
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
        platformData:
          $ref: '#/components/schemas/ProfilePlatformData'
        relationships:
          type: array
          items:
            $ref: '#/components/schemas/Relationship'
          description: >-
            One entry per team account link that has interacted with the
            profile.
      required:
        - id
        - platform
        - platformId
        - username
        - handle
        - displayName
        - avatarUrl
        - bio
        - location
        - websiteUrl
        - websiteDomain
        - verified
        - isOrganization
        - isProtected
        - followerCount
        - followingCount
        - postCount
        - engagementCount
        - listedCount
        - accountStatus
        - platformCreatedAt
        - profileUrl
        - updatedAt
        - platformData
        - relationships
      additionalProperties: false
      description: >-
        One person's account on one platform. Profile data is shared across
        teams; the team's own data about the person is on their contact.
    Contact:
      type: object
      properties:
        id:
          type: string
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
          description: >-
            The person's profiles, oldest link first. Profiles on platforms
            unavailable to the team are left out.
        statusId:
          anyOf:
            - type: string
              description: 'A status: a pipeline stage on the team''s board.'
            - type: 'null'
        tagIds:
          type: array
          items:
            type: string
            description: 'A tag: a label the team puts on contacts.'
        notes:
          anyOf:
            - type: string
            - type: 'null'
        valuation:
          anyOf:
            - type: number
            - type: string
              enum:
                - Infinity
                - '-Infinity'
                - NaN
            - type: 'null'
          description: What the person is worth to the team, in the team's `currency`.
        assigneeId:
          anyOf:
            - type: string
              description: 'A member: a person on the team.'
            - type: 'null'
          description: >-
            The default assignee of this contact's threads that have none of
            their own.
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
        updatedAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
        status:
          $ref: '#/components/schemas/Status'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        assignee:
          $ref: '#/components/schemas/Member'
      required:
        - id
        - profiles
        - statusId
        - tagIds
        - notes
        - valuation
        - assigneeId
        - createdAt
        - updatedAt
      additionalProperties: false
      description: >-
        The team's record of a person: their profiles, plus the team's CRM state
        about them.
    Member:
      type: object
      properties:
        id:
          type: string
          description: The member ID that `assigneeId` fields take.
        name:
          anyOf:
            - type: string
            - type: 'null'
        email:
          type: string
        imageUrl:
          anyOf:
            - type: string
            - type: 'null'
        role:
          type: string
          enum:
            - owner
            - admin
            - user
          description: >-
            `owner` and `admin` manage the team. A `user` can't change settings,
            billing or members.
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - id
        - name
        - email
        - imageUrl
        - role
        - createdAt
      additionalProperties: false
      description: A person on the team, who can be assigned threads and contacts.
    ProfilePlatformData:
      anyOf:
        - type: object
          properties:
            _tag:
              type: string
              enum:
                - twitter
            badge:
              anyOf:
                - type: string
                  enum:
                    - blue
                    - gold
                    - gray
                - type: 'null'
            profileType:
              type: string
              enum:
                - personal
                - business
                - government
            professionalCategory:
              anyOf:
                - type: string
                - type: 'null'
            urlEntities:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  expandedUrl:
                    type: string
                  displayUrl:
                    type: string
                  indices:
                    type: array
                    prefixItems:
                      - type: number
                      - type: number
                    maxItems: 2
                    minItems: 2
                required:
                  - url
                  - expandedUrl
                  - displayUrl
                  - indices
                additionalProperties: false
            bannerUrl:
              anyOf:
                - type: string
                - type: 'null'
            rawData:
              anyOf:
                - type: object
                - type: 'null'
          required:
            - _tag
            - badge
            - profileType
            - professionalCategory
            - urlEntities
            - bannerUrl
            - rawData
          additionalProperties: false
        - type: object
          properties:
            _tag:
              type: string
              enum:
                - linkedin
            profileUrn:
              anyOf:
                - type: string
                - type: 'null'
            kind:
              anyOf:
                - type: string
                  enum:
                    - member
                    - organization
                - type: 'null'
            memberBadge:
              anyOf:
                - type: string
                  enum:
                    - premium
                    - verified
                - type: 'null'
            bannerUrl:
              anyOf:
                - type: string
                - type: 'null'
            bannerSize:
              anyOf:
                - type: object
                  properties:
                    width:
                      type: number
                    height:
                      type: number
                  required:
                    - width
                    - height
                  additionalProperties: false
                - type: 'null'
            hydratedAt:
              anyOf:
                - type: string
                - type: 'null'
            imageAssetId:
              anyOf:
                - type: string
                - type: 'null'
            connectionsCount:
              anyOf:
                - type: number
                - type: 'null'
            currentRole:
              anyOf:
                - type: string
                - type: 'null'
            currentRoleStart:
              anyOf:
                - type: object
                  properties:
                    year:
                      type: number
                    month:
                      anyOf:
                        - type: number
                        - type: 'null'
                  required:
                    - year
                    - month
                  additionalProperties: false
                - type: 'null'
            currentCompanyName:
              anyOf:
                - type: string
                - type: 'null'
            currentCompanyUrn:
              anyOf:
                - type: string
                - type: 'null'
            topSchoolName:
              anyOf:
                - type: string
                - type: 'null'
            topSchoolUrn:
              anyOf:
                - type: string
                - type: 'null'
            topSchoolDegree:
              anyOf:
                - type: string
                - type: 'null'
            topSchoolPeriod:
              anyOf:
                - type: string
                - type: 'null'
            employeeCount:
              anyOf:
                - type: number
                - type: 'null'
            employeeCountRange:
              anyOf:
                - type: object
                  properties:
                    start:
                      type: number
                    end:
                      anyOf:
                        - type: number
                        - type: 'null'
                  required:
                    - start
                    - end
                  additionalProperties: false
                - type: 'null'
            industry:
              anyOf:
                - type: string
                - type: 'null'
            pageKind:
              anyOf:
                - type: string
                  enum:
                    - company
                    - school
                    - showcase
                - type: 'null'
            companyUrn:
              anyOf:
                - type: string
                - type: 'null'
            currentCompanyLogoUrl:
              anyOf:
                - type: string
                - type: 'null'
            topSchoolLogoUrl:
              anyOf:
                - type: string
                - type: 'null'
          required:
            - _tag
          additionalProperties: false
        - type: object
          properties:
            _tag:
              type: string
              enum:
                - whatsapp
            phoneNumber:
              anyOf:
                - type: string
                - type: 'null'
            verifiedName:
              anyOf:
                - type: string
                - type: 'null'
            business:
              anyOf:
                - type: boolean
                - type: 'null'
          required:
            - _tag
          additionalProperties: false
        - type: object
          properties:
            _tag:
              type: string
          required:
            - _tag
          description: >-
            A platform the team has enabled beyond those every team can use. Its
            fields are not listed here.
      description: >-
        Fields only one platform has, tagged by `_tag`. Ignore tags you don't
        know.
    Relationship:
      type: object
      properties:
        accountLinkId:
          type: string
        degree:
          anyOf:
            - type: string
              enum:
                - self
                - first
                - second
                - third
                - outOfNetwork
            - type: 'null'
          description: >-
            How close the profile is to the account link on the platform's
            network, as last observed. `null` when never observed.
        connectionRequest:
          anyOf:
            - type: object
              properties:
                sentAt:
                  type: string
                  format: date-time
                  examples:
                    - '2026-09-14T10:32:00.000Z'
              required:
                - sentAt
              additionalProperties: false
            - type: 'null'
          description: >-
            The account link's pending connection request. `null` once the
            profile is seen accepting it or the request is withdrawn, or when
            none was sent.
      required:
        - accountLinkId
        - degree
        - connectionRequest
      additionalProperties: false
      description: What one of the team's account links knows about a profile.
    Status:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Unique within the team, ignoring case and accents.
        color:
          anyOf:
            - type: string
              description: A lowercase hex color.
              examples:
                - '#3b82f6'
            - type: 'null'
          description: Null when the status has no color.
        createdAt:
          type: string
          format: date-time
          examples:
            - '2026-09-14T10:32:00.000Z'
      required:
        - id
        - name
        - color
        - createdAt
      additionalProperties: false
      description: A pipeline stage on the team's board. A contact has at most one status.
    Tag:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Unique within the team, ignoring case and accents.
        color:
          type: string
          description: A lowercase hex color.
          examples:
            - '#3b82f6'
      required:
        - id
        - name
        - color
      additionalProperties: false
      description: A label the team puts on contacts. A contact can have several.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.