> ## 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. # Send connection request > Invites a profile to connect with the account link. Needs `profile:connect`. ## OpenAPI ````yaml /v2/openapi.json post /connection-requests 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 `. 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: Threads description: Conversations between one of the team's account links and one profile. - 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: /connection-requests: post: tags: - Relationships summary: Send connection request description: >- Invites a profile to connect with the account link. Needs `profile:connect`. operationId: relationships.connect parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ConnectionRequestCreate' required: true responses: '201': description: Success content: application/json: schema: $ref: '#/components/schemas/ConnectionRequest' '400': description: InvalidRequest content: application/json: schema: $ref: '#/components/schemas/InvalidRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' '403': description: PlatformNotAvailable | PlanRequired | WorkspaceLocked content: application/json: schema: anyOf: - $ref: '#/components/schemas/PlatformNotAvailable' - $ref: '#/components/schemas/PlanRequired' - $ref: '#/components/schemas/WorkspaceLocked' '404': description: ThreadNotFound | ContactNotFound | AccountLinkNotFound content: application/json: schema: anyOf: - $ref: '#/components/schemas/ThreadNotFound' - $ref: '#/components/schemas/ContactNotFound' - $ref: '#/components/schemas/AccountLinkNotFound' '409': description: AccountLinkDisconnected | IntegrationSetupRequired content: application/json: schema: anyOf: - $ref: '#/components/schemas/AccountLinkDisconnected' - $ref: '#/components/schemas/IntegrationSetupRequired' '422': description: >- RecipientUnavailable | PlatformNotSupported | ProfileAmbiguous | ConnectionRefused | CapabilityNotSupported content: application/json: schema: anyOf: - $ref: '#/components/schemas/RecipientUnavailable' - $ref: '#/components/schemas/PlatformNotSupported' - $ref: '#/components/schemas/ProfileAmbiguous' - $ref: '#/components/schemas/ConnectionRefused' - $ref: '#/components/schemas/CapabilityNotSupported' '429': description: PlatformRateLimited | RateLimited content: application/json: schema: anyOf: - $ref: '#/components/schemas/PlatformRateLimited' - $ref: '#/components/schemas/RateLimited' '500': description: Internal content: application/json: schema: $ref: '#/components/schemas/Internal' '502': description: PlatformError content: application/json: schema: $ref: '#/components/schemas/PlatformError' '503': description: PlatformUnavailable content: application/json: schema: $ref: '#/components/schemas/PlatformUnavailable' security: - bearerAuth: [] components: schemas: ConnectionRequestCreate: type: object properties: target: anyOf: - type: object properties: type: type: string enum: - thread threadId: $ref: '#/components/schemas/Cuid2' required: - type - threadId additionalProperties: false description: >- The profile of an existing one-to-one thread, from the thread's account link. - type: object properties: type: type: string enum: - contact accountLinkId: allOf: - $ref: '#/components/schemas/Cuid2' - description: The account link to send the request from. contactId: $ref: '#/components/schemas/Cuid2' required: - type - accountLinkId - contactId additionalProperties: false description: >- The contact's profile on the account link's platform. Fails with `recipientUnavailable` when the contact has none there, and `profileAmbiguous` when it has several. - type: object properties: type: type: string enum: - profile accountLinkId: allOf: - $ref: '#/components/schemas/Cuid2' - description: The account link to send the request from. platform: allOf: - $ref: '#/components/schemas/Platform' - description: Must be the account link's platform. platformId: type: string description: >- The ID the platform gives this object. Only meaningful next to its `platform`. minLength: 1 required: - type - accountLinkId - platform - platformId additionalProperties: false description: >- A platform user. Without the Advanced API add-on, the profile must already belong to one of the team's contacts. note: type: string minLength: 1 allOf: - description: >- Up to the platform's `limits.connectNoteCharacters`. Needs `profile:connect:note`, and fails with `connectionRefused` once the account has no notes left. required: - target additionalProperties: false ConnectionRequest: type: object properties: accountLinkId: type: string profileId: type: string note: anyOf: - type: string - type: 'null' required: - accountLinkId - profileId - note additionalProperties: false description: A connection request the platform accepted for delivery. 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 - anyOf: - 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 PlanRequired: type: object properties: code: type: string enum: - planRequired message: type: string details: type: object properties: feature: type: string required: - feature additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false WorkspaceLocked: type: object properties: code: type: string enum: - workspaceLocked message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false ThreadNotFound: type: object properties: code: type: string enum: - threadNotFound message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false ContactNotFound: type: object properties: code: type: string enum: - contactNotFound message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false AccountLinkNotFound: type: object properties: code: type: string enum: - accountLinkNotFound message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false AccountLinkDisconnected: type: object properties: code: type: string enum: - accountLinkDisconnected message: type: string details: type: object properties: accountLinkId: type: string 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. required: - accountLinkId - status additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false IntegrationSetupRequired: type: object properties: code: type: string enum: - integrationSetupRequired message: type: string details: type: object properties: accountLinkId: type: string required: - accountLinkId additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false RecipientUnavailable: type: object properties: code: type: string enum: - recipientUnavailable message: type: string details: type: object properties: reason: type: string required: - reason additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false PlatformNotSupported: type: object properties: code: type: string enum: - platformNotSupported message: type: string details: type: object properties: platform: $ref: '#/components/schemas/Platform' supported: type: array items: $ref: '#/components/schemas/Platform' required: - platform - supported additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false ProfileAmbiguous: type: object properties: code: type: string enum: - profileAmbiguous message: type: string details: type: object properties: contactId: type: string platform: $ref: '#/components/schemas/Platform' required: - contactId - platform additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false ConnectionRefused: type: object properties: code: type: string enum: - connectionRefused message: type: string details: type: object properties: reason: type: string enum: - notAllowed - noteTooLong - noteAllowanceSpent description: >- `notAllowed` when the profile can't be invited right now, such as when already connected or invited. `noteAllowanceSpent` when the account has no notes left; send without one. required: - reason additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false CapabilityNotSupported: type: object properties: code: type: string enum: - capabilityNotSupported message: type: string details: type: object properties: capability: type: string enum: - message:send - message:edit - message:delete:self - message:unsend - message:react - message:reply - message:forward - media:image - media:video - media:gif - media:file - media:audio - thread:typing:send - thread:typing:receive - thread:message-requests - thread:delete:remote - directory:typeahead - thread:archive:observe - thread:archive:mutate - thread:read:observe - thread:read:mutate - profile:follow - profile:unfollow - profile:connect - profile:connect:note required: - capability additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false PlatformRateLimited: type: object properties: code: type: string enum: - platformRateLimited message: type: string details: type: object properties: retryAfterSeconds: anyOf: - type: integer - type: 'null' required: - retryAfterSeconds additionalProperties: false 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 resetAt: type: string examples: - '2026-09-14T10:32:00.000Z' format: date-time 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 PlatformError: type: object properties: code: type: string enum: - platformError message: type: string details: type: 'null' requestId: type: string required: - code - message - details - requestId additionalProperties: false PlatformUnavailable: type: object properties: code: type: string enum: - platformUnavailable message: type: string details: type: object properties: retryAfterSeconds: anyOf: - type: integer - type: 'null' required: - retryAfterSeconds additionalProperties: false requestId: type: string required: - code - message - details - requestId additionalProperties: false Cuid2: type: string pattern: ^[0-9a-z]+$ Platform: type: string description: >- The platform. Every team can use twitter; a team may have others enabled. examples: - twitter securitySchemes: bearerAuth: type: http scheme: Bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.