{ "openapi": "3.0.3", "info": { "title": "Replypad API", "version": "1.0", "description": "REST API for Replypad — tickets, accounts, contacts, assets, billing and\nworkspace configuration resources.\n\n## Authentication\n\nEvery request must carry a Bearer token:\n\n```\nAuthorization: Bearer \n```\n\nTokens are 64-character hexadecimal strings, created and revoked in the\nReplypad web UI (there is no API endpoint that creates, rotates or revokes\na token, and the token value is shown only once at creation). Every token\nis scoped to a single workspace and can only read and write data in that\nworkspace; there is no cross-workspace token, so a client working with\nseveral workspaces needs one token per workspace. API tokens are also\nper-user: each token belongs to a single workspace user, acts on that \nuser's behalf and inherits that user's privileges and access rights live - \nif the user's privileges or access rights change, the token reflects that \nimmediately.\n\n`GET /v1/tokens/me` describes the calling token — its name, expiry,\nread-only flag, the user it acts as, and a per-resource permission\nsummary. It is the only token endpoint.\n\n## Permissions\n\nAccess to any resource is subject to the token's permissions. Requests for\nresources outside those permissions fail with 403. Use `GET /v1/tokens/me`\nto see the permissions granted to the current token.\n\nA token may additionally be flagged **read-only**; every write then fails\nwith 403 `read_only_token` while reads keep working. Insufficient\nprivileges yield 403 `forbidden`. Ticket access is enforced per row: a\nticket the token may not see is reported as 404, not 403.\n\n## Field visibility\n\nPrivileges also govern individual fields, not just whole endpoints. A field\nthe caller may not see is handled one of two ways, and the difference\nmatters to generated clients:\n\n* **Absent from the response** — `price` on an item and on a charge's\n embedded `item` object (needs price visibility); `duration_type`,\n `interval`, `start_date`, `end_date`, `description`, `custom_fields`,\n `web_url`, `created_on` and `updated_on` on a contract (needs full\n billing access rights); `phone1`..`phone5`, `address1`, `custom_fields`\n and `web_url` on a user (admin tokens only).\n* **Present but `null`** — a charge's `billable_flag`, `billed_flag`,\n `invoice_ref`, `price_rate` and `total_amount` (needs price visibility).\n Note the first three are also `null` for reasons unrelated to\n permissions — `billable_flag` and `billed_flag` are `null` on time\n entries, `invoice_ref` is `null` on any unbilled charge — so only\n `price_rate` and `total_amount` mean \"hidden from you\" unambiguously.\n\nWriting a field the token cannot see is refused rather than ignored:\nsending `billable_flag` or `price_rate` on a charge without price\nvisibility is 403, and so is filtering the charge list on `billed_flag` or\n`billable_flag`.\n\n## Array size limits\n\nArray-valued fields are capped per collection, and exceeding a cap is 422\n`validation_failed`: ticket `labels` 50, ticket `cc_recipients` and\n`followers` 20 each, contact `emails` 20, account `domains` 20, and any\n`custom_fields` map 50 entries.\n\nThe limit on the request body as a whole is per resource - see the\ndescription of each tag below.\n\n## Object IDs\n\nAll object IDs are opaque strings issued by Replypad. They start with a\ntype prefix, e.g. `tkt_1a2b3c4d5e6f7a8b`. Prefixes: `acc_` account,\n`per_` contact **and** user (shared namespace), `tkt_` ticket,\n`cmt_` comment, `ast_` asset, `itm_` item, `crg_` charge, `bct_` contract,\n`lbl_` label, `kba_` KB article, `kbc_` KB category, `mbx_` mailbox,\n`res_` saved response, `tea_` team. Stars are addressed by their\n`star_key` slug instead of an opaque ID. A syntactically invalid ID in a\npath yields 404 (or 400 `invalid_id_format` where noted); an invalid ID\ninside a request body yields 400/422.\n\n## Envelopes\n\n* Lists: `{\"data\": [...], \"has_more\": bool, \"next_cursor\": string|null}`.\n* Single objects: `{\"data\": {...}}`.\n* Unpaginated collections (sub-resources, custom-field definitions) return\n `{\"data\": [...]}` with no pagination fields.\n* Successful creation returns **201** with the created object in `data`;\n deletion returns **204** with no body.\n* Errors: `{\"error\": {\"code\": \"\", \"message\": \"\"}}`.\n\n## Pagination\n\nList endpoints use opaque, forward-only cursors. Page size is fixed per\nendpoint — 25 for tickets, 50 for ticket comments and every other\nlist — and is not client-adjustable. There is no `limit`, `page` or\n`page_size` parameter, so a cheap probe still costs a full page. Sort\norder is fixed per endpoint (documented on each operation) and is total \nand stable.\n\nWhen `has_more` is true, pass `next_cursor` back as `?cursor=`.\n`has_more` is exact rather than a guess, so `has_more: false` means the \nwalk is finished and `next_cursor` is null.\n\n### Cursor validity\n\nA cursor is a opaque string: do not parse, construct or edit cursors.\n\n**Use a cursor reasonably soon after receiving it.** Pauses between pages \nare safe; persisting one and resuming days later is not. A cursor marks a \nposition in a live list, not a saved query.\n\nA cursor records the endpoint's sort key, its page size, and the filters\nof the request that produced it. It is rejected with 400 `invalid_cursor`\nwhen it is corrupt or its signature does not verify, when it belongs to a\ndifferent endpoint, and when a filter sent alongside it disagrees with \nthe value it carries. Filters you *omit* on a paged request are not an \nerror — the values recorded in the cursor are used — but any filter you \n*do* send must match exactly. `expand` is not part of the cursor and may \ndiffer from page to page.\n\n### Concurrent writes during a walk\n\nPaging is keyset (\"seek\") based, not offset based: each page resumes\nimmediately after the last row of the previous page in the endpoint's\nsort order. No snapshot or transaction spans the walk, so each page\nreflects the data as of the moment it was read.\n\n* A row **inserted** ahead of the cursor position is returned on a later\n page; one inserted behind it is never seen, because pagination has\n already moved past that point. Nothing shifts, so an insert never\n duplicates or skips a neighbouring row.\n* A row **deleted** ahead of the cursor position is simply absent from\n the page it would have appeared on. Deletions do not shift the\n remaining rows into or out of a page.\n* A row **updated** so that its sort key changes moves with its new\n value. If it moves ahead of the cursor it is returned a second time;\n if it moves behind, it is not returned at all. This applies to the\n name-sorted lists — renaming an account, contact, item, label and so\n on. tickets are ordered by an immutable internal sequence and\n cannot be affected this way.\n\nA full walk therefore guarantees neither exactly-once delivery nor\ncomplete coverage while the data is being written to. Callers that need\neither should de-duplicate on `id` and treat a walk as eventually\nconsistent rather than a point-in-time snapshot.\n\n## The expand parameter\n\nList and detail endpoints accept `expand`, a comma-separated list of\nrelated objects or heavy fields to include. The allowed values differ per\nendpoint and are documented on each operation; an unknown value yields\n400. Fields that are only returned when expanded are marked in the schema\ndescriptions.\n\nThere is no fixed cap on the number of `expand` values in a single\nrequest: any combination is accepted as long as every value is valid for\nthat endpoint and appears only once. The cost, however, is not free. Each\nexpansion is resolved per object in the response, so on a list endpoint\nthe work multiplies by the page size — a full page with several\nexpansions is substantially more expensive than the same page without\nthem, both in response size and in latency, and is more likely to hit\nrequest timeouts.\n\n## Dates and times\n\nTimestamps (`created_on`, `updated_on`, `published_on`, `scheduled_for`,\ncomment `date`) are ISO-8601 UTC: `2026-03-10T14:32:45Z`. Date-only\nfields use `YYYY-MM-DD`. Time-of-day fields (charge times) use `HH:MM`.\n\n## Rate limits\n\nRequests are counted per token, per workspace and per client IP\nseparately (defaults per minute/hour/day: token 150/1500/7500, workspace\n250/2500/12500, IP 400/4000/20000). Write requests count double. Breaches\nyield 429 `rate_limited`. Repeated failing calls in a row temporarily\nblock the token with 429 `too_many_errors`; the counter resets on the\nnext successful call. Both carry a `Retry-After` header giving the whole\nseconds to wait. No `X-RateLimit-*` headers are sent.\n\n## Maintenance windows\n\nDuring a planned maintenance window every endpoint returns 503\n`service_unavailable` with a `Retry-After` header giving the whole seconds to\nwait. Retry after the header's delay; no request is lost or half-applied, \nbecause the call is refused before it reaches any data.\n" }, "servers": [ { "url": "https://api.replypad.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Tickets", "description": "Tickets, their comments, labels, CC recipients and followers. A request body may not exceed 128 KB; anything larger is refused with 413 `payload_too_large` before any validation runs.\n" }, { "name": "Accounts", "description": "Customer accounts (companies) and their email domains. A request body may not exceed 16 KB; anything larger is refused with 413 `payload_too_large` before any validation runs.\n" }, { "name": "Contacts", "description": "Customer contacts and their email addresses. A request body may not exceed 16 KB; anything larger is refused with 413 `payload_too_large` before any validation runs.\n" }, { "name": "Assets", "description": "Customer assets (hardware, software, ...). A request body may not exceed 16 KB; anything larger is refused with 413 `payload_too_large` before any validation runs.\n" }, { "name": "Items", "description": "Billable products and services. A request body may not exceed 16 KB; anything larger is refused with 413 `payload_too_large` before any validation runs.\n" }, { "name": "Charges", "description": "Billing charges and time entries. A request body may not exceed 16 KB; anything larger is refused with 413 `payload_too_large` before any validation runs.\n" }, { "name": "Contracts", "description": "Service contracts (read-only)." }, { "name": "Users", "description": "Workspace staff users (read-only)." }, { "name": "Tokens", "description": "Introspection of the calling API token (read-only)." }, { "name": "Teams", "description": "Staff teams (read-only)." }, { "name": "Labels", "description": "Ticket labels (read-only collection)." }, { "name": "Stars", "description": "Ticket star markers (read-only)." }, { "name": "Mailboxes", "description": "Shared mailboxes (read-only)." }, { "name": "KB Categories", "description": "Knowledge-base categories (read-only)." }, { "name": "KB Articles", "description": "Knowledge-base articles (read-only)." }, { "name": "Saved Responses", "description": "Saved (canned) responses (read-only)." }, { "name": "Metadata", "description": "Custom-field definitions per resource type." } ], "paths": { "/v1/tickets": { "get": { "tags": [ "Tickets" ], "operationId": "listTickets", "summary": "List tickets", "description": "Returns tickets sorted by internal sequence, most recent first, 25 per\npage. Without a `status` filter, tickets of every status except\n`archived` are returned; a customer's unsubmitted draft is never\nreturned. `archived` cannot be combined with other statuses.\n", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `notes`, `comments`, `cc_recipients`, `followers`, `labels`, `custom_fields`, `account`, `contact`, `asset`.\n" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `draft`, `open`, `closed`, `archived`. Omitted, every status except `archived` is returned. `archived` must be used alone.\n" }, { "name": "account_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the tickets by the `account_id` provided." }, { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the tickets by the `contact_id` provided." }, { "name": "asset_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the tickets by the `asset_id` provided." }, { "name": "assignee_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the tickets by the `assignee_id` provided." }, { "name": "team_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the tickets by the `team_id` provided." }, { "name": "mailbox_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the tickets by the `mailbox_id` provided." }, { "name": "number", "in": "query", "schema": { "type": "integer" }, "description": "Filter by the ticket number." }, { "name": "priority_flag", "in": "query", "schema": { "type": "boolean" }, "description": "Allowed values: `true`, `false`. Only one value is accepted. Filter the tickets by the `priority_flag` provided.\n" }, { "name": "star_key", "in": "query", "schema": { "$ref": "#/components/schemas/StarKey" }, "description": "Filter the tickets by the `star_key` provided." } ], "responses": { "200": { "description": "A page of tickets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketList" }, "example": { "data": [ { "id": "tkt_d44ee8a0fdabaec8", "subject": "VPN connection failing for remote employees", "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "asset_id": null, "assignee_id": "per_83771a454a075181", "assignee": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "team_id": "tea_1f29804c7ad271bc", "team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "mailbox_id": "mbx_b5c73d081a013a4b", "mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "received_on_mailbox_id": null, "received_on_mailbox": null, "priority_flag": true, "star_key": null, "due_date": null, "scheduled_for": null, "published_on": null, "status": "draft", "web_url": "https://example.replypad.com/conversations/view/id/tkt_d44ee8a0fdabaec8", "created_on": "2026-03-02T09:13:02Z", "updated_on": "2026-03-02T10:17:44Z" }, { "id": "tkt_0f63bdcc4364400d", "subject": "Problems with the new printer", "number": 4023, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "asset_id": null, "assignee_id": "per_83771a454a075181", "assignee": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "team_id": "tea_1f29804c7ad271bc", "team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "mailbox_id": "mbx_b5c73d081a013a4b", "mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "received_on_mailbox_id": "mbx_b5c73d081a013a4b", "received_on_mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "priority_flag": false, "star_key": "highlight", "due_date": null, "scheduled_for": null, "published_on": "2026-03-02T11:28:02Z", "status": "open", "web_url": "https://example.replypad.com/conversations/view/id/tkt_0f63bdcc4364400d", "created_on": "2026-03-02T11:28:02Z", "updated_on": "2026-03-02T13:36:11Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0Ijoib3BlbiJ9LCJzIjoidGt0X3NiX2NyX2QiLCJwcyI6MjUsInN2Ijp7InN2MiI6InRrdF8xYTJiM2M0ZDVlNmY3YThiIn19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Tickets" ], "operationId": "createTicket", "summary": "Create a ticket", "description": "Requires `subject` and/or exactly one comment in `comments`. The\ncontact can be given as `contact_id` or created inline via `contact`;\nsame for `account`. When `status` is `draft` the ticket is created as\na draft (no `number` assigned yet).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCreate" }, "example": { "subject": "VPN connection failing for remote employees", "comments": [ { "body": "Several employees reported that they cannot establish a VPN connection when working remotely. The connection attempt fails with an authentication timeout error.", "type": "user_public_comment" } ], "contact_id": "per_7ca565d07cf38178", "account_id": "acc_fc8e252962bdf56a", "assignee_id": "per_da82708cc65f2b1e", "team_id": "tea_1f29804c7ad271bc", "priority_flag": true, "status": "draft", "custom_fields": { "extra_note": "Happened second time" } } } } }, "responses": { "201": { "description": "The created ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" }, "example": { "data": { "id": "tkt_d44ee8a0fdabaec8", "subject": "VPN connection failing for remote employees", "comments": [ { "comment_id": "cmt_9da8a50b6eb8204f", "body": "Several employees reported that they cannot establish a VPN connection when working remotely. The connection attempt fails with an authentication timeout error.", "status": "published", "type": "user_public_comment", "source": "api", "from_id": "per_83771a454a075181", "from": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "date": "2026-03-02T09:13:02Z", "resolution_flag": false, "scheduled_for": null } ], "notes": null, "contact_id": "per_7ca565d07cf38178", "contact": { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_7ca565d07cf38178" }, "cc_recipients": null, "followers": null, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "asset_id": null, "assignee_id": "per_da82708cc65f2b1e", "assignee": { "id": "per_da82708cc65f2b1e", "first_name": "Jane", "last_name": "Doe", "nickname": "@jane", "primary_email": "jane@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_da82708cc65f2b1e" }, "team_id": "tea_1f29804c7ad271bc", "team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "mailbox_id": "mbx_b5c73d081a013a4b", "mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "received_on_mailbox_id": null, "received_on_mailbox": null, "labels": null, "priority_flag": true, "star_key": null, "due_date": null, "scheduled_for": null, "published_on": null, "status": "draft", "custom_fields": { "severity_level": null, "extra_note": "Happened second time" }, "web_url": "https://example.replypad.com/conversations/addnew/draftid/tkt_d44ee8a0fdabaec8", "created_on": "2026-03-02T09:13:02Z", "updated_on": "2026-03-02T09:13:02Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" } ], "get": { "tags": [ "Tickets" ], "operationId": "getTicket", "summary": "Retrieve a ticket", "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `account`, `contact`, `asset`." } ], "responses": { "200": { "description": "The ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" }, "example": { "data": { "id": "tkt_d44ee8a0fdabaec8", "subject": "VPN connection failing for remote employees", "comments": [ { "comment_id": "cmt_9da8a50b6eb8204f", "body": "Several employees reported that they cannot establish a VPN connection when working remotely. The connection attempt fails with an authentication timeout error.", "status": "published", "type": "user_public_comment", "source": "web_portal", "from_id": "per_c6bd4ce63a05e29a", "from": { "id": "per_c6bd4ce63a05e29a", "first_name": "Jane", "last_name": "Doe", "primary_email": "jane@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_c6bd4ce63a05e29a" }, "date": "2026-01-08T14:13:41Z", "resolution_flag": false, "scheduled_for": null } ], "notes": null, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "cc_recipients": [ { "id": "per_5309071edb068029", "first_name": "John", "last_name": "Doe", "email_address": "john@example.com" } ], "followers": [ { "id": "per_65c3c7acb221c0d9", "first_name": "Jane", "last_name": "Doe", "nickname": "@jane", "email_address": "jane@acme.org" } ], "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "asset_id": null, "assignee_id": "per_83771a454a075181", "assignee": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "team_id": "tea_1f29804c7ad271bc", "team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "mailbox_id": "mbx_b5c73d081a013a4b", "mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "received_on_mailbox_id": null, "received_on_mailbox": null, "labels": [ { "id": "lbl_9fa361758f05fa48", "name": "VIP" } ], "priority_flag": true, "star_key": null, "due_date": null, "scheduled_for": null, "published_on": null, "status": "draft", "custom_fields": { "severity_level": null, "extra_note": null }, "web_url": "https://example.replypad.com/conversations/view/id/tkt_d44ee8a0fdabaec8", "created_on": "2026-03-02T09:13:02Z", "updated_on": "2026-03-02T10:17:44Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Tickets" ], "operationId": "updateTicket", "summary": "Update a ticket", "description": "Partial update. `status`, `comments`, `labels`, `cc_recipients` and\n`followers` cannot be changed here — use their dedicated\nsub-resource endpoints (422 `wrong_endpoint`). A draft ticket that is\nscheduled for publishing (`scheduled_for` set) cannot be updated at all\n(403 `forbidden`).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketUpdate" }, "example": { "star_key": "red_star" } } } }, "responses": { "200": { "description": "The updated ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" }, "example": { "data": { "id": "tkt_d44ee8a0fdabaec8", "subject": "VPN connection failing for remote employees", "comments": [ { "comment_id": "cmt_9da8a50b6eb8204f", "body": "Several employees reported that they cannot establish a VPN connection when working remotely. The connection attempt fails with an authentication timeout error.", "status": "published", "type": "user_public_comment", "source": "web_portal", "from_id": "per_c6bd4ce63a05e29a", "from": { "id": "per_c6bd4ce63a05e29a", "first_name": "Jane", "last_name": "Doe", "primary_email": "jane@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_c6bd4ce63a05e29a" }, "date": "2026-01-08T14:13:41Z", "resolution_flag": false, "scheduled_for": null } ], "notes": null, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "cc_recipients": null, "followers": null, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "asset_id": null, "assignee_id": "per_83771a454a075181", "assignee": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "team_id": "tea_1f29804c7ad271bc", "team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "mailbox_id": "mbx_b5c73d081a013a4b", "mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "received_on_mailbox_id": null, "received_on_mailbox": null, "labels": null, "priority_flag": true, "star_key": "red_star", "due_date": null, "scheduled_for": null, "published_on": null, "status": "draft", "custom_fields": { "severity_level": null, "extra_note": null }, "web_url": "https://example.replypad.com/conversations/view/id/tkt_d44ee8a0fdabaec8", "created_on": "2026-03-02T09:13:02Z", "updated_on": "2026-03-02T10:17:44Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Tickets" ], "operationId": "deleteTicket", "summary": "Delete a ticket", "description": "Moves the ticket to the trash. A draft ticket that is scheduled for publishing (`scheduled_for` set) cannot be deleted (403 `forbidden`).\n", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/status": { "parameters": [ { "$ref": "#/components/parameters/ticketId" } ], "put": { "tags": [ "Tickets" ], "operationId": "setTicketStatus", "summary": "Change ticket status", "description": "Transitions a ticket to `open` or `closed`. Publishing a draft this\nway uses the content already stored on the draft. Transitions to\n`draft` (422 `invalid_state`) or `archived` (422 `not_supported`) are\nrejected, and so is trying to transition a draft that is already \nscheduled for publishing — 403 `forbidden`, `Ticket is scheduled for \npublishing.` Wait for the scheduled time or cancel the schedule in the\nweb app. Idempotent: setting the current status again succeeds.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "closed" ] } } }, "example": { "status": "open" } } } }, "responses": { "200": { "description": "The updated ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" }, "example": { "data": { "id": "tkt_d44ee8a0fdabaec8", "subject": "VPN connection failing for remote employees", "comments": [ { "comment_id": "cmt_9da8a50b6eb8204f", "body": "Several employees reported that they cannot establish a VPN connection when working remotely. The connection attempt fails with an authentication timeout error.", "status": "published", "type": "user_public_comment", "source": "web_portal", "from_id": "per_c6bd4ce63a05e29a", "from": { "id": "per_c6bd4ce63a05e29a", "first_name": "Jane", "last_name": "Doe", "primary_email": "jane@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_c6bd4ce63a05e29a" }, "date": "2026-01-08T14:13:41Z", "resolution_flag": false, "scheduled_for": null } ], "notes": null, "number": 4022, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "cc_recipients": null, "followers": null, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "asset_id": null, "assignee_id": "per_83771a454a075181", "assignee": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "team_id": "tea_1f29804c7ad271bc", "team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "mailbox_id": "mbx_b5c73d081a013a4b", "mailbox": { "id": "mbx_b5c73d081a013a4b", "name": "Support" }, "received_on_mailbox_id": null, "received_on_mailbox": null, "labels": null, "priority_flag": true, "star_key": "red_star", "due_date": null, "scheduled_for": null, "published_on": "2026-03-02T10:17:44Z", "status": "open", "custom_fields": { "severity_level": null, "extra_note": null }, "web_url": "https://example.replypad.com/conversations/view/id/tkt_d44ee8a0fdabaec8", "created_on": "2026-03-02T09:13:02Z", "updated_on": "2026-03-02T10:17:44Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/comments": { "parameters": [ { "$ref": "#/components/parameters/ticketId" } ], "get": { "tags": [ "Tickets" ], "operationId": "listTicketComments", "summary": "List ticket comments", "description": "50 per page. Without a `status` filter both `published` and `draft` comments are returned.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `published`, `draft`. Omitted, both are returned." }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `user_public_comment`, `customer_comment`, `user_internal_note`. If omitted, returns comments of all types.\n" } ], "responses": { "200": { "description": "A page of comments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentList" }, "example": { "data": [ { "comment_id": "cmt_eec2d7ed83c0bcdd", "body": "I'm experiencing an issue logging into my account; could you assist me?", "status": "published", "type": "customer_comment", "source": "email", "from_id": "per_ba32319beb775040", "from": { "id": "per_ba32319beb775040", "first_name": "Dave", "last_name": "Johnson", "primary_email": "djohson@gmail.com", "web_url": "https://example.replypad.com/people/view/id/per_ba32319beb775040" }, "date": "2026-01-08T09:30:00Z", "resolution_flag": false, "scheduled_for": null }, { "comment_id": "cmt_99d88d369db3d6b7", "body": "Hi there, it seems like", "status": "draft", "type": "user_public_comment", "source": "web_portal", "from_id": "per_83771a454a075181", "from": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "date": "2026-01-08T10:12:10Z", "resolution_flag": false, "scheduled_for": null } ], "has_more": true, "next_cursor": "eyJmIjp7InRrIjoidGt0XzFhMmIzYzRkNWU2ZjdhOGIiLCJzdCI6InB1Ymxpc2hlZCJ9LCJzIjoiY210X3NiX2R0X2EiLCJwcyI6NTAsInN2Ijp7InN2MSI6IjIwMjYtMDMtMTAgMTQ6MzI6NDUiLCJzdjIiOiJjbXRfOWQ0ZTFmMGE3YjZjMjM1OCJ9fQ:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Tickets" ], "operationId": "createTicketComment", "summary": "Add a comment", "description": "Adds a comment to the ticket. `type` may be `user_public_comment` or\n`user_internal_note`; the comment is published as the token's user.\n\nNot available on a draft (unpublished) ticket — 422 `wrong_endpoint`. A\ndraft ticket already carries its body as its only comment; publish it\nwith `PUT /v1/tickets/{ticket_id}/status` before adding to the thread.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreate" }, "example": { "body": "Hi there, it seems like", "status": "draft", "type": "user_public_comment" } } } }, "responses": { "201": { "description": "The created comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentEnvelope" }, "example": { "data": { "comment_id": "cmt_99d88d369db3d6b7", "body": "Hi there, it seems like", "status": "draft", "type": "user_public_comment", "source": "api", "from_id": "per_83771a454a075181", "from": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "date": "2026-01-08T10:12:10Z", "resolution_flag": false, "scheduled_for": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/comments/{comment_id}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "$ref": "#/components/parameters/commentId" } ], "get": { "tags": [ "Tickets" ], "operationId": "getTicketComment", "summary": "Retrieve a comment", "responses": { "200": { "description": "The comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentEnvelope" }, "example": { "data": { "comment_id": "cmt_eec2d7ed83c0bcdd", "body": "Could you please provide more details on the error message you're receiving?", "status": "published", "type": "user_public_comment", "source": "email", "from_id": "per_83771a454a075181", "from": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "date": "2026-01-08T09:30:00Z", "resolution_flag": false, "scheduled_for": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Tickets" ], "operationId": "updateTicketComment", "summary": "Update a draft comment", "description": "Only comments still in `draft` status can be updated (422\n`invalid_state` otherwise), and a draft that is scheduled for publishing\ncannot be updated either (403 `forbidden`).\n\nThis is also how the body of a **draft (unpublished) ticket** is edited:\nthat body is the ticket's only draft comment, and `PATCH\n/v1/tickets/{ticket_id}` has no `body` field. On a draft ticket only\n`body` and `from_id` may be changed — sending `type` is 422\n`invalid_state` — and if the ticket itself is scheduled for publishing\nthe call is 403 `forbidden`, `Ticket is scheduled for publishing.`\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdate" }, "example": { "body": "Hi there, it seems like there was a problem with the network." } } } }, "responses": { "200": { "description": "The updated comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentEnvelope" }, "example": { "data": { "comment_id": "cmt_99d88d369db3d6b7", "body": "Hi there, it seems like there was a problem with the network.", "status": "draft", "type": "user_public_comment", "source": "api", "from_id": "per_83771a454a075181", "from": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "date": "2026-01-08T10:12:10Z", "resolution_flag": false, "scheduled_for": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Tickets" ], "operationId": "deleteTicketComment", "summary": "Discard a draft comment", "description": "Only comments still in `draft` status can be deleted, and a draft\nthat is scheduled for publishing cannot be discarded (403 `forbidden`).\n\nNot available on a draft (unpublished) ticket — 422 `wrong_endpoint`,\nsince that comment is the ticket's body. Discard the whole draft ticket\nwith `DELETE /v1/tickets/{ticket_id}` instead.\n", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/comments/{comment_id}/publish": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "$ref": "#/components/parameters/commentId" } ], "put": { "tags": [ "Tickets" ], "operationId": "publishTicketComment", "summary": "Publish a draft comment", "description": "Publishes a draft comment. No request body. **Publishing assigns a new\n`comment_id`** — use the ID from the response from then on. A draft\nalready scheduled for publishing cannot be published this way — 403\n`forbidden`, `Comment is scheduled for publishing.`\n\nNot available on a draft (unpublished) ticket — 422 `wrong_endpoint`.\nPublishing that comment would mean publishing the ticket, which is\n`PUT /v1/tickets/{ticket_id}/status`.\n", "responses": { "200": { "description": "The published comment (with its new `comment_id`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentEnvelope" }, "example": { "data": { "comment_id": "cmt_5a3c0d8f2b41e7aa", "body": "Hi there, it seems like you're experiencing an issue with your router.", "status": "published", "type": "user_public_comment", "source": "api", "from_id": "per_83771a454a075181", "from": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "date": "2026-01-08T14:13:41Z", "resolution_flag": false, "scheduled_for": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/labels": { "parameters": [ { "$ref": "#/components/parameters/ticketId" } ], "get": { "tags": [ "Tickets" ], "operationId": "listTicketLabels", "summary": "List a ticket's labels", "responses": { "200": { "description": "The ticket's labels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketLabelsEnvelope" }, "example": { "data": [ { "id": "lbl_9fa361758f05fa48", "name": "VIP" }, { "id": "lbl_33f52594685b793e", "name": "Follow Up" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Tickets" ], "operationId": "addTicketLabels", "summary": "Add labels to a ticket", "description": "The body is a JSON **array** of label references. Each item references\nan existing label, either by its `id` or by the `name` of an existing\nactive label. An unknown name is rejected, not created.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LabelInput" } }, "example": [ { "name": "VIP" }, { "id": "lbl_33f52594685b793e" } ] } } }, "responses": { "200": { "description": "The ticket's labels after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketLabelsEnvelope" }, "example": { "data": [ { "id": "lbl_9fa361758f05fa48", "name": "VIP" }, { "id": "lbl_33f52594685b793e", "name": "Follow Up" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "tags": [ "Tickets" ], "operationId": "replaceTicketLabels", "summary": "Replace a ticket's labels", "description": "Replaces the full label set with the given JSON array (an empty array clears all labels).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LabelInput" } }, "example": [ { "id": "lbl_9fa361758f05fa48" }, { "id": "lbl_33f52594685b793e" } ] } } }, "responses": { "200": { "description": "The ticket's labels after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketLabelsEnvelope" }, "example": { "data": [ { "id": "lbl_9fa361758f05fa48", "name": "VIP" }, { "id": "lbl_33f52594685b793e", "name": "Follow Up" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/labels/{label_id}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "$ref": "#/components/parameters/labelId" } ], "delete": { "tags": [ "Tickets" ], "operationId": "removeTicketLabel", "summary": "Remove a label from a ticket", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/cc-recipients": { "parameters": [ { "$ref": "#/components/parameters/ticketId" } ], "get": { "tags": [ "Tickets" ], "operationId": "listTicketCcRecipients", "summary": "List a ticket's CC recipients", "responses": { "200": { "description": "The ticket's CC recipients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCcRecipientsEnvelope" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "email_address": "john@acme.org" }, { "id": "per_fcb862e8856489cf", "first_name": "Bob", "last_name": "Smith", "email_address": "bob@acme.org" }, { "id": "per_648fcb862e8859cf", "first_name": "Tom", "last_name": null, "email_address": "tom@acme.org" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Tickets" ], "operationId": "addTicketCcRecipients", "summary": "Add CC recipients", "description": "The body is a JSON **array**. Each item references an existing\ncontact/user by `id`, or gives an `email_address` (optionally with\n`first_name`/`last_name`) to add an external recipient.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CcRecipientInput" } }, "example": [ { "id": "per_fcb862e8856489cf" }, { "email_address": "bob@acme.org" }, { "email_address": "tom@acme.org", "first_name": "Tom" } ] } } }, "responses": { "200": { "description": "The ticket's CC recipients after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCcRecipientsEnvelope" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "email_address": "john@acme.org" }, { "id": "per_fcb862e8856489cf", "first_name": "Bob", "last_name": "Smith", "email_address": "bob@acme.org" }, { "id": "per_648fcb862e8859cf", "first_name": "Tom", "last_name": null, "email_address": "tom@acme.org" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "tags": [ "Tickets" ], "operationId": "replaceTicketCcRecipients", "summary": "Replace the CC recipient list", "description": "Replaces the full CC recipient list with the given JSON array (an empty array clears all CC recipients).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CcRecipientInput" } }, "example": [ { "id": "per_7ca565d07cf38178" }, { "id": "per_fcb862e8856489cf" }, { "email_address": "tom@acme.org", "first_name": "Tom" } ] } } }, "responses": { "200": { "description": "The ticket's CC recipients after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketCcRecipientsEnvelope" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "email_address": "john@acme.org" }, { "id": "per_fcb862e8856489cf", "first_name": "Bob", "last_name": "Smith", "email_address": "bob@acme.org" }, { "id": "per_648fcb862e8859cf", "first_name": "Tom", "last_name": null, "email_address": "tom@acme.org" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/cc-recipients/id/{recipient_id}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "name": "recipient_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact/user ID of the recipient (starts with `per_`)." } ], "delete": { "tags": [ "Tickets" ], "operationId": "removeTicketCcRecipientById", "summary": "Remove a CC recipient by ID", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/cc-recipients/email/{email_address}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "name": "email_address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address of the recipient." } ], "delete": { "tags": [ "Tickets" ], "operationId": "removeTicketCcRecipientByEmail", "summary": "Remove a CC recipient by email address", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/followers": { "parameters": [ { "$ref": "#/components/parameters/ticketId" } ], "get": { "tags": [ "Tickets" ], "operationId": "listTicketFollowers", "summary": "List a ticket's followers", "responses": { "200": { "description": "The ticket's followers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketFollowersEnvelope" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "nickname": "@john", "email_address": "john@acme.org" }, { "id": "per_d194ffa58c07d31c", "first_name": "Jane", "last_name": "Doe", "nickname": "@jane", "email_address": "jane@acme.org" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Tickets" ], "operationId": "addTicketFollowers", "summary": "Add followers", "description": "The body is a JSON **array**. Each item references a user by `id` or\nby `email_address`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FollowerInput" } }, "example": [ { "id": "per_d194ffa58c07d31c" }, { "email_address": "jane@acme.org" } ] } } }, "responses": { "200": { "description": "The ticket's followers after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketFollowersEnvelope" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "nickname": "@john", "email_address": "john@acme.org" }, { "id": "per_d194ffa58c07d31c", "first_name": "Jane", "last_name": "Doe", "nickname": "@jane", "email_address": "jane@acme.org" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "tags": [ "Tickets" ], "operationId": "replaceTicketFollowers", "summary": "Replace the follower list", "description": "Replaces the full follower list with the given JSON array (an empty array clears all followers).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FollowerInput" } }, "example": [ { "id": "per_d194ffa58c07d31c" }, { "email_address": "jane@acme.org" } ] } } }, "responses": { "200": { "description": "The ticket's followers after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketFollowersEnvelope" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "nickname": "@john", "email_address": "john@acme.org" }, { "id": "per_d194ffa58c07d31c", "first_name": "Jane", "last_name": "Doe", "nickname": "@jane", "email_address": "jane@acme.org" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/followers/user/{user_id}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID of the follower (starts with `per_`)." } ], "delete": { "tags": [ "Tickets" ], "operationId": "removeTicketFollowerByUser", "summary": "Remove a follower by user ID", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tickets/{ticket_id}/followers/email/{email_address}": { "parameters": [ { "$ref": "#/components/parameters/ticketId" }, { "name": "email_address", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded email address of the follower." } ], "delete": { "tags": [ "Tickets" ], "operationId": "removeTicketFollowerByEmail", "summary": "Remove a follower by email address", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/accounts": { "get": { "tags": [ "Accounts" ], "operationId": "listAccounts", "summary": "List accounts", "description": "Sorted by name ascending, 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `domains`, `banner`, `phones_address`, `custom_fields`." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter accounts to ones that match the search string. Ignored if the `name` parameter is provided.\n" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Exact match filter by account name." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `active`, `inactive`. Ignored if the `name` parameter is provided.\n" } ], "responses": { "200": { "description": "A page of accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountList" }, "example": { "data": [ { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "contact_access_rights": "restricted", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" }, { "id": "acc_0358be460f618d8b", "name": "Example Inc", "status": "active", "contact_access_rights": "all", "created_on": "2026-01-09T10:29:03Z", "updated_on": "2026-02-13T16:06:17Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJhY2Nfc2Jfbl9hIiwicHMiOjUwLCJzdiI6eyJzdjEiOiJBY21lIENvcnAiLCJpZCI6ImFjY19mYzhlMjUyOTYyYmRmNTZhIn19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Accounts" ], "operationId": "createAccount", "summary": "Create an account", "description": "Account names are unique per workspace (409 `already_exists` on duplicates).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreate" }, "example": { "name": "Example Inc", "domains": [ { "domain_name": "example.com" } ], "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "industry": "Tech" } } } } }, "responses": { "201": { "description": "The created account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelope" }, "example": { "data": { "id": "acc_fc8e252962bdf56a", "name": "Example Inc", "status": "active", "contact_access_rights": "restricted", "domains": [ { "domain_name": "example.com" } ], "banner": null, "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "industry": "Tech", "legal_structure": null }, "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2025-11-21T14:07:12Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/accounts/{account_id}": { "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "get": { "tags": [ "Accounts" ], "operationId": "getAccount", "summary": "Retrieve an account", "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `contacts`." } ], "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelope" }, "example": { "data": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "contact_access_rights": "restricted", "domains": [ { "domain_name": "acme.org" } ], "banner": { "notice": "The payment for last month was received two weeks later than expected.", "level": "red" }, "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "industry": null, "legal_structure": null }, "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Accounts" ], "operationId": "updateAccount", "summary": "Update an account", "description": "Partial update. `domains` cannot be changed here — use the\n`/domains` sub-resource endpoints (422).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdate" }, "example": { "status": "inactive" } } } }, "responses": { "200": { "description": "The updated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelope" }, "example": { "data": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "inactive", "contact_access_rights": "restricted", "domains": null, "banner": null, "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "industry": null, "legal_structure": null }, "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-03-12T10:12:04Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Accounts" ], "operationId": "deleteAccount", "summary": "Delete an account", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/accounts/{account_id}/domains": { "parameters": [ { "$ref": "#/components/parameters/accountId" } ], "get": { "tags": [ "Accounts" ], "operationId": "listAccountDomains", "summary": "List an account's email domains", "responses": { "200": { "description": "The account's domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDomainsEnvelope" }, "example": { "data": [ { "domain_name": "acme.org" }, { "domain_name": "acme.com" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Accounts" ], "operationId": "addAccountDomain", "summary": "Add an email domain", "description": "The body is a single domain object.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainInput" }, "example": { "domain_name": "acme.org" } } } }, "responses": { "200": { "description": "The account's domains after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDomainsEnvelope" }, "example": { "data": [ { "domain_name": "acme.org" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "tags": [ "Accounts" ], "operationId": "replaceAccountDomains", "summary": "Replace the domain list", "description": "The body is a JSON array of domain objects (an empty array clears the list).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DomainInput" } }, "example": [ { "domain_name": "acme.org" }, { "domain_name": "acme.com" } ] } } }, "responses": { "200": { "description": "The account's domains after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDomainsEnvelope" }, "example": { "data": [ { "domain_name": "acme.org" }, { "domain_name": "acme.com" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/accounts/{account_id}/domains/{domain}": { "parameters": [ { "$ref": "#/components/parameters/accountId" }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded domain name." } ], "delete": { "tags": [ "Accounts" ], "operationId": "deleteAccountDomain", "summary": "Remove an email domain", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "description": "Sorted by first name, last name, then primary email; 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `emails`, `phones_address`, `custom_fields`, `account`." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter contacts to ones that match the search string." }, { "name": "account_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the contacts by the `account_id` provided." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `active`, `inactive`." } ], "responses": { "200": { "description": "A page of contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" }, "example": { "data": [ { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "active", "contact_access_rights": "restricted", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "id": "per_d194ffa58c07d31c", "first_name": "Jane", "last_name": "Smith", "primary_email": null, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "active", "contact_access_rights": "restricted", "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJjbnRfc2JfZm5fbG5fYSIsInBzIjo1MCwic3YiOnsic3YxIjoiSm9obiIsInN2MiI6IkRvZSIsImlkIjoicGVyXzdjYTU2NWQwN2NmMzgxNzgifX0:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Contacts" ], "operationId": "createContact", "summary": "Create a contact", "description": "At least one of `first_name`, `last_name` or `emails` is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" }, "example": { "first_name": "Dave", "last_name": "Johnson", "emails": [ { "email_address": "dave@example.com", "primary_flag": true } ], "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "custom_fields": { "gender": "F" } } } } }, "responses": { "201": { "description": "The created contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" }, "example": { "data": { "id": "per_ba32319beb775040", "first_name": "Dave", "last_name": "Johnson", "primary_email": "dave@example.com", "emails": [ { "email_address": "dave@example.com", "primary_flag": true } ], "account_id": null, "account": null, "status": "active", "contact_access_rights": "by_account", "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": null, "custom_fields": { "gender": "F" }, "web_url": "https://example.replypad.com/people/view/id/per_ba32319beb775040", "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:19:02Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/contacts/{contact_id}": { "parameters": [ { "$ref": "#/components/parameters/contactId" } ], "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Retrieve a contact", "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `account` (returns the full account object instead of the summary)." } ], "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" }, "example": { "data": { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "emails": [ { "email_address": "john@acme.org", "primary_flag": true }, { "email_address": "john@example.com", "primary_flag": false } ], "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "active", "contact_access_rights": "restricted", "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "gender": null }, "web_url": "https://example.replypad.com/people/view/id/per_7ca565d07cf38178", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Update a contact", "description": "Partial update. `emails` cannot be changed here — use the `/emails`\nsub-resource endpoints (422).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" }, "example": { "status": "inactive" } } } }, "responses": { "200": { "description": "The updated contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" }, "example": { "data": { "id": "per_7ca565d07cf38178", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "emails": [ { "email_address": "john@acme.org", "primary_flag": true } ], "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "inactive", "contact_access_rights": "restricted", "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "gender": null }, "web_url": "https://example.replypad.com/people/view/id/per_7ca565d07cf38178", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Contacts" ], "operationId": "deleteContact", "summary": "Delete a contact", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/contacts/{contact_id}/emails": { "parameters": [ { "$ref": "#/components/parameters/contactId" } ], "get": { "tags": [ "Contacts" ], "operationId": "listContactEmails", "summary": "List a contact's email addresses", "responses": { "200": { "description": "The contact's email addresses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailsEnvelope" }, "example": { "data": [ { "email_address": "john@acme.org", "primary_flag": true }, { "email_address": "john@acme.com", "primary_flag": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Contacts" ], "operationId": "addContactEmail", "summary": "Add an email address", "description": "The body is a single email object. The address is added as secondary\nunless it is the contact's first email.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email_address" ], "properties": { "email_address": { "type": "string", "format": "email" } } }, "example": { "email_address": "johndoe@gmail.com" } } } }, "responses": { "200": { "description": "The contact's email addresses after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailsEnvelope" }, "example": { "data": [ { "email_address": "john@acme.org", "primary_flag": true }, { "email_address": "john@acme.com", "primary_flag": false }, { "email_address": "johndoe@gmail.com", "primary_flag": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "tags": [ "Contacts" ], "operationId": "replaceContactEmails", "summary": "Replace the email address list", "description": "The body is a JSON array of email objects, replacing any existing\nemails. The list must be non-empty, and exactly one entry must\ncarry `primary_flag: true`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEmail" } }, "example": [ { "email_address": "john@acme.org", "primary_flag": true }, { "email_address": "john@acme.com", "primary_flag": false } ] } } }, "responses": { "200": { "description": "The contact's email addresses after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEmailsEnvelope" }, "example": { "data": [ { "email_address": "john@acme.org", "primary_flag": true }, { "email_address": "john@acme.com", "primary_flag": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/contacts/{contact_id}/emails/{email}": { "parameters": [ { "$ref": "#/components/parameters/contactId" }, { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" }, "description": "URL-encoded email address." } ], "delete": { "tags": [ "Contacts" ], "operationId": "deleteContactEmail", "summary": "Remove an email address", "description": "The last remaining email address of a contact cannot be removed (409 `in_use`).", "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/assets": { "get": { "tags": [ "Assets" ], "operationId": "listAssets", "summary": "List assets", "description": "Sorted by name ascending, 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `custom_fields`, `desc_notes`." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter assets to ones that match the search string." }, { "name": "account_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the assets by the `account_id` provided." }, { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the assets by the `contact_id` provided." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `active`, `inactive`." } ], "responses": { "200": { "description": "A page of assets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetList" }, "example": { "data": [ { "id": "ast_e7b7bbe8aee71135", "name": "HP 250 G10 – 725G5EA", "status": "active", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "contract_id": "bct_10f10dd4d8487f06", "type": "laptop", "warranty_exp_date": "2027-11-19", "purchased_date": "2025-11-20", "installation_date": "2025-11-21", "location": null, "serial_no": null, "model": null, "web_url": "https://example.replypad.com/assets/view/id/ast_e7b7bbe8aee71135", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" }, { "id": "ast_ff1b3414277441d0", "name": "HP LaserJet Pro 4003dw", "status": "active", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "contract_id": null, "type": "printer", "warranty_exp_date": null, "purchased_date": null, "installation_date": null, "location": null, "serial_no": null, "model": null, "web_url": "https://example.replypad.com/assets/view/id/ast_ff1b3414277441d0", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJhc3Rfc2Jfbm1fYSIsInBzIjo1MCwic3YiOnsic3YxIjoiSFAgMjUwIEcxMCIsInN2MiI6ImFzdF9lN2I3YmJlOGFlZTcxMTM1In19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Assets" ], "operationId": "createAsset", "summary": "Create an asset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetWrite" }, "example": { "name": "HP 250 G10 – 725G5EA", "status": "active", "account_id": "acc_fc8e252962bdf56a", "contact_id": "per_83771a454a075181", "contract_id": "bct_10f10dd4d8487f06", "type": "laptop", "custom_fields": { "brand": "HP" } } } } }, "responses": { "201": { "description": "The created asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetEnvelope" }, "example": { "data": { "id": "ast_e7b7bbe8aee71135", "name": "HP 250 G10 – 725G5EA", "status": "active", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "contract_id": "bct_10f10dd4d8487f06", "type": "laptop", "warranty_exp_date": null, "purchased_date": null, "installation_date": null, "location": null, "serial_no": null, "model": null, "custom_fields": { "brand": "HP", "user_manual_link": null }, "description": null, "notes": null, "web_url": "https://example.replypad.com/assets/view/id/ast_e7b7bbe8aee71135", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2025-11-21T14:07:12Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/assets/{asset_id}": { "parameters": [ { "$ref": "#/components/parameters/assetId" } ], "get": { "tags": [ "Assets" ], "operationId": "getAsset", "summary": "Retrieve an asset", "responses": { "200": { "description": "The asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetEnvelope" }, "example": { "data": { "id": "ast_e7b7bbe8aee71135", "name": "HP 250 G10 – 725G5EA", "status": "active", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "contract_id": "bct_10f10dd4d8487f06", "type": "laptop", "warranty_exp_date": "2027-11-19", "purchased_date": "2025-11-20", "installation_date": "2025-11-21", "location": null, "serial_no": null, "model": null, "custom_fields": { "brand": null, "user_manual_link": null }, "description": null, "notes": null, "web_url": "https://example.replypad.com/assets/view/id/ast_e7b7bbe8aee71135", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Assets" ], "operationId": "updateAsset", "summary": "Update an asset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetWrite" }, "example": { "status": "inactive" } } } }, "responses": { "200": { "description": "The updated asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetEnvelope" }, "example": { "data": { "id": "ast_ff1b3414277441d0", "name": "HP LaserJet Pro 4003dw", "status": "inactive", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "contact_id": "per_83771a454a075181", "contact": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "primary_email": "john@acme.org", "status": "active", "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181" }, "contract_id": null, "type": "printer", "warranty_exp_date": null, "purchased_date": null, "installation_date": null, "location": null, "serial_no": null, "model": null, "custom_fields": { "brand": null, "user_manual_link": null }, "description": null, "notes": null, "web_url": "https://example.replypad.com/assets/view/id/ast_ff1b3414277441d0", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Assets" ], "operationId": "deleteAsset", "summary": "Delete an asset", "description": "An asset referenced by other objects cannot be deleted (409 `in_use`).", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/items": { "get": { "tags": [ "Items" ], "operationId": "listItems", "summary": "List items", "description": "Sorted by name ascending, 50 per page. Without price visibility the `price` key is omitted from every item in the page.\n", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Allowed values: `product`, `service`. Supports multiple values as a comma-separated list. If omitted, returns items of all types.\n" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Allowed values: `active`, `inactive`." } ], "responses": { "200": { "description": "A page of items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemList" }, "example": { "data": [ { "id": "itm_ef905679180d36e2", "name": "Server installation", "type": "service", "priced_by": "hourly_rate", "price": "45.00", "status": "active", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" }, { "id": "itm_d2c87af1aa36ca8f", "name": "Hard disk replacement", "type": "service", "priced_by": "hourly_rate", "price": "45.00", "status": "active", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJpdG1fc2Jfbm1fYSIsInBzIjo1MCwic3YiOnsic3YxIjoiT24tc2l0ZSBob3VyIiwic3YyIjoiaXRtXzNiOTBjMWQ2NGFmMmU1MDcifX0:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Items" ], "operationId": "createItem", "summary": "Create an item", "description": "Item names are unique per workspace (409 `already_exists` on duplicates).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemWrite" }, "example": { "name": "Hard disk replacement", "type": "service", "priced_by": "hourly_rate", "price": "45" } } } }, "responses": { "201": { "description": "The created item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEnvelope" }, "example": { "data": { "id": "itm_d2c87af1aa36ca8f", "name": "Hard disk replacement", "type": "service", "priced_by": "hourly_rate", "price": "45.00", "status": "active", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/items/{item_id}": { "parameters": [ { "$ref": "#/components/parameters/itemId" } ], "get": { "tags": [ "Items" ], "operationId": "getItem", "summary": "Retrieve an item", "responses": { "200": { "description": "The item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEnvelope" }, "example": { "data": { "id": "itm_ef905679180d36e2", "name": "Server installation", "type": "service", "priced_by": "hourly_rate", "price": "45.00", "status": "active", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Items" ], "operationId": "updateItem", "summary": "Update an item", "description": "`type` is immutable and rejected on update.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemWrite" }, "example": { "status": "inactive" } } } }, "responses": { "200": { "description": "The updated item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemEnvelope" }, "example": { "data": { "id": "itm_d2c87af1aa36ca8f", "name": "Hard disk replacement", "type": "service", "priced_by": "hourly_rate", "price": "45.00", "status": "inactive", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Items" ], "operationId": "deleteItem", "summary": "Delete an item", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/charges": { "get": { "tags": [ "Charges" ], "operationId": "listCharges", "summary": "List charges", "description": "Sorted by charge date descending, 50 per page. Requires billing\naccess; without price visibility the money fields (`billable_flag`,\n`billed_flag`, `invoice_ref`, `price_rate`, `total_amount`) are\nreturned as `null`, and the embedded `item` object drops its `price`\nkey altogether.\n\nA caller who cannot see all charges is limited to their own rows,\nunless they pass a `ticket_id` they have access to. A caller who may\nlog time entries but not product or service charges sees only\n`time_entry` rows in the unfiltered list.\n", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `account`, `ticket`." }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `product_charge`, `service_charge`, `time_entry`." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "`YYYY-MM-DD`. Must be supplied together with `date_to`." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "`YYYY-MM-DD`. Must be supplied together with `date_from`." }, { "name": "account_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the charges by the `account_id` provided." }, { "name": "ticket_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the charges by the `ticket_id` provided." }, { "name": "user_id", "in": "query", "schema": { "type": "string" }, "description": "Filter charges by `user_id` — only charges belonging to that user are returned. When omitted, returns all charges the caller is authorized to access.\n" }, { "name": "billed_flag", "in": "query", "schema": { "type": "boolean" }, "description": "Allowed values: `true`, `false`. Only one value is accepted; any other value is 400. `true` selects billed charges (including those marked as billed), `false` the unbilled ones. Time entries have no billed state and match neither. Requires price visibility — without it the parameter is refused with 403, so that a field the caller cannot read cannot be probed a value at a time.\n" }, { "name": "billable_flag", "in": "query", "schema": { "type": "boolean" }, "description": "Allowed values: `true`, `false`. Only one value is accepted; any other value is 400. Time entries have no billable state and match neither. Requires price visibility, same as `billed_flag`.\n" } ], "responses": { "200": { "description": "A page of charges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeList" }, "example": { "data": [ { "id": "crg_1a1f5e5e4d80fc47", "type": "product_charge", "item_id": "itm_cffe9c5cab54949d", "item": { "id": "itm_cffe9c5cab54949d", "name": "Western Digital WD3200BEKT 320.0GB", "type": "product", "priced_by": "fixed_price", "price": "42.00" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "ticket_id": null, "ticket": null, "billable_flag": true, "billed_flag": false, "invoice_ref": null, "date": "2026-03-17", "user_id": null, "time": null, "quantity": "1.00", "price_rate": "42.00", "total_amount": "42.00", "contract_id": null, "description": null, "created_on": "2026-03-17T14:07:12Z", "updated_on": "2026-03-17T14:07:12Z" }, { "id": "crg_dc8faf9ddcbfcdc4", "type": "service_charge", "item_id": "itm_d2c87af1aa36ca8f", "item": { "id": "itm_d2c87af1aa36ca8f", "name": "Hard disk replacement", "type": "service", "priced_by": "hourly_rate", "price": "60.00" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "ticket_id": null, "ticket": null, "billable_flag": true, "billed_flag": false, "invoice_ref": null, "date": "2026-03-17", "user_id": "per_83771a454a075181", "time": { "start_time": "10:23", "end_time": "11:23", "hours_worked": "01:00" }, "quantity": "1.00", "price_rate": "60.00", "total_amount": "60.00", "contract_id": "bct_2f3a5a65fbb0cc95", "description": null, "created_on": "2026-03-17T14:07:12Z", "updated_on": "2026-03-17T14:07:12Z" } ], "has_more": true, "next_cursor": "eyJmIjpbXSwicyI6ImNoZ19zYl9kdF9kIiwicHMiOjUwLCJzdiI6eyJzdjEiOiIyMDI2LTAzLTEwIiwic3YzIjoiMjAyNi0wMy0xMCAxNDozMjo0NSIsInN2MiI6ImNyZ181OGFkMGUyYzlmMTRiNjczIn19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Charges" ], "operationId": "createCharge", "summary": "Create a charge", "description": "`type`, `item_id` and `date` are required. `type` is immutable after\ncreation. By default the charge is logged for the token's user; a\ntoken whose user has sufficient privileges may set `user_id` to log\nthe charge for another user.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeWrite" }, "example": { "type": "product_charge", "item_id": "itm_ab54949cffe9c5cd", "account_id": "acc_fc8e252962bdf56a", "billable_flag": true, "date": "2026-03-17", "quantity": 2, "price_rate": 20 } } } }, "responses": { "201": { "description": "The created charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeEnvelope" }, "example": { "data": { "id": "crg_dc8faf9ddcbfcdc4", "type": "product_charge", "item_id": "itm_ab54949cffe9c5cd", "item": { "id": "itm_ab54949cffe9c5cd", "name": "Wireless Mouse", "type": "product", "priced_by": "fixed_price", "price": "9.99" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "ticket_id": null, "ticket": null, "billable_flag": true, "billed_flag": false, "invoice_ref": null, "date": "2026-03-17", "user_id": null, "time": null, "quantity": "2.00", "price_rate": "20.00", "total_amount": "40.00", "contract_id": null, "description": null, "created_on": "2026-03-17T14:07:12Z", "updated_on": "2026-03-17T14:07:12Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/charges/{charge_id}": { "parameters": [ { "$ref": "#/components/parameters/chargeId" } ], "get": { "tags": [ "Charges" ], "operationId": "getCharge", "summary": "Retrieve a charge", "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `account`, `ticket`." } ], "responses": { "200": { "description": "The charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeEnvelope" }, "example": { "data": { "id": "crg_1a1f5e5e4d80fc47", "type": "product_charge", "item_id": "itm_ab54949cffe9c5cd", "item": { "id": "itm_ab54949cffe9c5cd", "name": "Wireless Mouse", "type": "product", "priced_by": "fixed_price", "price": "9.99" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "ticket_id": null, "ticket": null, "billable_flag": true, "billed_flag": false, "invoice_ref": null, "date": "2026-03-17", "user_id": null, "time": null, "quantity": "2.00", "price_rate": "9.99", "total_amount": "19.98", "contract_id": null, "description": null, "created_on": "2026-03-17T14:07:12Z", "updated_on": "2026-03-17T14:07:12Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Charges" ], "operationId": "updateCharge", "summary": "Update a charge", "description": "Partial update. A charge with `billed_flag: true` is read-only except\nfor the dedicated un-billing flow: a body containing only\n`billed_flag` (and optionally `invoice_ref`) toggles the billed\nstate.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeWrite" }, "example": { "billed_flag": true, "invoice_ref": "INV-2026-03-0352" } } } }, "responses": { "200": { "description": "The updated charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeEnvelope" }, "example": { "data": { "id": "crg_dc8faf9ddcbfcdc4", "type": "product_charge", "item_id": "itm_ab54949cffe9c5cd", "item": { "id": "itm_ab54949cffe9c5cd", "name": "Wireless Mouse", "type": "product", "priced_by": "fixed_price", "price": "9.99" }, "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "ticket_id": null, "ticket": null, "billable_flag": true, "billed_flag": true, "invoice_ref": "INV-2026-03-0352", "date": "2026-03-17", "user_id": null, "time": null, "quantity": "2.00", "price_rate": "9.99", "total_amount": "19.98", "contract_id": null, "description": null, "created_on": "2026-03-17T14:07:12Z", "updated_on": "2026-04-02T09:13:59Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "tags": [ "Charges" ], "operationId": "deleteCharge", "summary": "Delete a charge", "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/contracts": { "get": { "tags": [ "Contracts" ], "operationId": "listContracts", "summary": "List contracts", "description": "Sorted by name ascending, 50 per page. Requires the right to log charges.\n\nWithout **full billing access rights** the caller gets the reduced contract object described in the `Contract` schema, may expand only `account`, and **must** pass `account_id` — listing every contract in the workspace is refused with 403 `account_id_required`. That check also applies to paged requests, where `account_id` travels inside the cursor.\n", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `account`, `description`, `custom_fields` — reduced to `account` alone without full billing access rights.\n" }, { "name": "account_id", "in": "query", "schema": { "type": "string" }, "description": "Filter the contracts by the `account_id` provided. Mandatory without full billing access rights.\n" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `draft`, `active`, `completed`, `canceled`." } ], "responses": { "200": { "description": "A page of contracts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractList" }, "example": { "data": [ { "id": "bct_2f3a5a65fbb0cc95", "name": "Contract with Acme - 2025/27", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "active", "duration_type": "recurring", "interval": { "unit": "yearly", "total_intervals": 3 }, "start_date": "2025-01-01", "end_date": "2027-12-31", "web_url": "https://example.replypad.com/contracts/view/id/bct_2f3a5a65fbb0cc95", "created_on": "2024-12-21T13:48:01Z", "updated_on": "2024-12-21T16:07:35Z" }, { "id": "bct_236b863b5578b29e", "name": "Contract with Acme - 2022/24", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "completed", "duration_type": "single_term", "interval": null, "start_date": "2022-01-01", "end_date": "2024-12-31", "web_url": "https://example.replypad.com/contracts/view/id/bct_236b863b5578b29e", "created_on": "2024-12-21T13:48:01Z", "updated_on": "2024-12-21T16:07:35Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIiwiYWkiOiJhY2NfZmM4ZTI1Mjk2MmJkZjU2YSJ9LCJzIjoiYmN0X3NiX25tX2EiLCJwcyI6NTAsInN2Ijp7InN2MSI6IkdvbGQgc3VwcG9ydCIsInN2MiI6ImJjdF8yZjZlODRiMWNkMDdhOTM1In19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/contracts/{contract_id}": { "parameters": [ { "$ref": "#/components/parameters/contractId" } ], "get": { "tags": [ "Contracts" ], "operationId": "getContract", "summary": "Retrieve a contract", "description": "Requires the right to log charges. Without full billing access rights the reduced contract object described in the `Contract` schema is returned.\n", "parameters": [ { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `account`." } ], "responses": { "200": { "description": "The contract.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractEnvelope" }, "example": { "data": { "id": "bct_2f3a5a65fbb0cc95", "name": "Contract with Acme - 2025/27", "account_id": "acc_fc8e252962bdf56a", "account": { "id": "acc_fc8e252962bdf56a", "name": "ACME Organization", "status": "active", "web_url": "https://example.replypad.com/accounts/view/id/acc_fc8e252962bdf56a" }, "status": "active", "duration_type": "recurring", "interval": { "unit": "yearly", "total_intervals": 3 }, "start_date": "2025-01-01", "end_date": "2027-12-31", "description": "This contract is recurring ...", "custom_fields": { "service_scope": "Maintenance" }, "web_url": "https://example.replypad.com/contracts/view/id/bct_2f3a5a65fbb0cc95", "created_on": "2024-12-21T13:48:01Z", "updated_on": "2024-12-21T16:07:35Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/users": { "get": { "tags": [ "Users" ], "operationId": "listUsers", "summary": "List users", "description": "Sorted by first name, last name; 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `active`, `inactive`." } ], "responses": { "200": { "description": "A page of users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" }, "example": { "data": [ { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "emails": [ { "email_address": "john@acme.org", "primary_flag": true } ], "status": "active", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "id": "per_65c3c7acb221c0d9", "first_name": "Jane", "last_name": "Smith", "nickname": "@smith", "primary_email": "jane@acme.org", "emails": [ { "email_address": "jane@acme.org", "primary_flag": true } ], "status": "active", "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJ1c3Jfc2JfZm5fbG5fYSIsInBzIjo1MCwic3YiOnsic3YxIjoiSmFuZSIsInN2MiI6IlJvZSIsImlkIjoicGVyXzQxYzhiN2Q1OTBlYTZmMjMifX0:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/users/{user_id}": { "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User ID (starts with `per_`)." } ], "get": { "tags": [ "Users" ], "operationId": "getUser", "summary": "Retrieve a user", "description": "When the token's user has admin rights the response additionally\ncarries `phone1`..`phone5`, `address1`, `custom_fields` and\n`web_url`.\n", "responses": { "200": { "description": "The user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEnvelope" }, "example": { "data": { "id": "per_83771a454a075181", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "john@acme.org", "emails": [ { "email_address": "john@acme.org", "primary_flag": true } ], "status": "active", "phone1": { "number": "(555) 123-4567", "description": "Work phone" }, "phone2": null, "phone3": null, "phone4": null, "phone5": null, "address1": { "addressline1": "123 Main St", "addressline2": "Apt 4B", "addressline3": null, "city": "Springfield", "state": "IL", "zip": "62704", "country": "United States" }, "custom_fields": { "hire_date": "2025-11-29" }, "web_url": "https://example.replypad.com/people/view/id/per_83771a454a075181", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/teams": { "get": { "tags": [ "Teams" ], "operationId": "listTeams", "summary": "List teams", "description": "Sorted by name ascending, 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `active`, `inactive`." } ], "responses": { "200": { "description": "A page of teams.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" }, "example": { "data": [ { "id": "tea_1f29804c7ad271bc", "name": "Support", "default_flag": true, "status": "active", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "id": "tea_554c121065744a34", "name": "Sales", "default_flag": false, "status": "active", "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJ0ZWFfc2Jfbl9hIiwicHMiOjUwLCJzdiI6eyJzdjEiOiJTdXBwb3J0IiwiaWQiOiJ0ZWFfNmQwMmY5MTM0YmU3Yzg1YSJ9fQ:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/teams/{team_id}": { "parameters": [ { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID (starts with `tea_`)." } ], "get": { "tags": [ "Teams" ], "operationId": "getTeam", "summary": "Retrieve a team", "responses": { "200": { "description": "The team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamEnvelope" }, "example": { "data": { "id": "tea_1f29804c7ad271bc", "name": "Support", "default_flag": true, "status": "active", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/labels": { "get": { "tags": [ "Labels" ], "operationId": "listLabels", "summary": "List labels", "description": "Sorted by name ascending, 50 per page. Deleted labels are not returned.", "parameters": [ { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of labels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelList" }, "example": { "data": [ { "id": "lbl_ea922675d120bc3e", "name": "VIP", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "id": "lbl_32b9523f82fb0500", "name": "Follow Up", "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjpbXSwicyI6ImxibF9zYl9uX2EiLCJwcyI6NTAsInN2Ijp7InN2MSI6IkVzY2FsYXRlZCIsImlkIjoibGJsXzBjN2E1ZTM4ZDFiNjlmNDIifX0:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/labels/{label_id}": { "parameters": [ { "$ref": "#/components/parameters/labelId" } ], "get": { "tags": [ "Labels" ], "operationId": "getLabel", "summary": "Retrieve a label", "responses": { "200": { "description": "The label.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelEnvelope" }, "example": { "data": { "id": "lbl_ea922675d120bc3e", "name": "VIP", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/stars": { "get": { "tags": [ "Stars" ], "operationId": "listStars", "summary": "List stars", "description": "Sorted by name ascending, 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `active`, `inactive`." } ], "responses": { "200": { "description": "A page of stars.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarList" }, "example": { "data": [ { "star_key": "red_star", "system_name": "Red star", "name": "Red star", "status": "active", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "star_key": "green_star", "system_name": "Green star", "name": "Green star", "status": "active", "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoiYWN0aXZlIn0sInMiOiJzdHJfc2Jfbl9hIiwicHMiOjUwLCJzdiI6eyJzdjEiOiJNeSBvcGVuIHRpY2tldHMiLCJzdjIiOiJteV9vcGVuX3RpY2tldHMifX0:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/stars/{star_key}": { "parameters": [ { "name": "star_key", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StarKey" }, "description": "The star's key slug (not an opaque ID)." } ], "get": { "tags": [ "Stars" ], "operationId": "getStar", "summary": "Retrieve a star", "responses": { "200": { "description": "The star.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StarEnvelope" }, "example": { "data": { "star_key": "red_star", "system_name": "Red star", "name": "Red star", "status": "active", "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/mailboxes": { "get": { "tags": [ "Mailboxes" ], "operationId": "listMailboxes", "summary": "List mailboxes", "description": "Sorted by name ascending, 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of mailboxes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxList" }, "example": { "data": [ { "id": "mbx_b5c73d081a013a4b", "name": "Support", "email_address": "support@acme.org", "aliases": null, "default_flag": true, "personalized_reply_enabled": true, "personalized_avatars_enabled": true, "default_team_id": "tea_1f29804c7ad271bc", "default_team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "autoresponse_enabled": true, "autoresponse_custom_enabled": false, "autoresponse_custom_text": null, "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "id": "mbx_d2b47af420f66e17", "name": "Sales", "email_address": "sales@acme.org", "aliases": null, "default_flag": false, "personalized_reply_enabled": false, "personalized_avatars_enabled": false, "default_team_id": "tea_554c121065744a34", "default_team": { "id": "tea_554c121065744a34", "name": "Sales" }, "autoresponse_enabled": false, "autoresponse_custom_enabled": false, "autoresponse_custom_text": null, "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjpbXSwicyI6Im1ieF9zYl9uX2EiLCJwcyI6NTAsInN2Ijp7InN2MSI6IlN1cHBvcnQgaW5ib3giLCJpZCI6Im1ieF85ZTEzYzc0MGFiNTJkNjhmIn19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/mailboxes/{mailbox_id}": { "parameters": [ { "name": "mailbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Mailbox ID (starts with `mbx_`)." } ], "get": { "tags": [ "Mailboxes" ], "operationId": "getMailbox", "summary": "Retrieve a mailbox", "responses": { "200": { "description": "The mailbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxEnvelope" }, "example": { "data": { "id": "mbx_b5c73d081a013a4b", "name": "Support", "email_address": "support@acme.org", "aliases": null, "default_flag": true, "personalized_reply_enabled": true, "personalized_avatars_enabled": true, "default_team_id": "tea_1f29804c7ad271bc", "default_team": { "id": "tea_1f29804c7ad271bc", "name": "Support" }, "autoresponse_enabled": true, "autoresponse_custom_enabled": false, "autoresponse_custom_text": null, "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/kb-categories": { "get": { "tags": [ "KB Categories" ], "operationId": "listKbCategories", "summary": "List knowledge-base categories", "description": "50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "A page of KB categories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategoryList" }, "example": { "data": [ { "id": "kbc_669d7fd3f95a483f", "name": "General", "default_flag": true, "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" }, { "id": "kbc_043f52e21a9a3d1c", "name": "Apps & Tools", "default_flag": false, "created_on": "2026-02-21T15:19:02Z", "updated_on": "2026-02-21T15:23:24Z" } ], "has_more": true, "next_cursor": "eyJmIjpbXSwicyI6ImtiY19zYl9uX2EiLCJwcyI6NTAsInN2Ijp7InN2MSI6Ik5ldHdvcmtpbmciLCJpZCI6ImtiY183NGIxZTBhOWMzZDI1ZjY4In19:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/kb-categories/{category_id}": { "parameters": [ { "name": "category_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "KB category ID (starts with `kbc_`)." } ], "get": { "tags": [ "KB Categories" ], "operationId": "getKbCategory", "summary": "Retrieve a knowledge-base category", "responses": { "200": { "description": "The KB category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbCategoryEnvelope" }, "example": { "data": { "id": "kbc_669d7fd3f95a483f", "name": "General", "default_flag": true, "created_on": "2026-02-21T14:07:12Z", "updated_on": "2026-02-21T14:07:12Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/kb-articles": { "get": { "tags": [ "KB Articles" ], "operationId": "listKbArticles", "summary": "List knowledge-base articles", "description": "Sorted by title ascending, 50 per page. Without a `status` filter\narticles of every status are returned.\n", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `content` (adds `description` and `body`)." }, { "name": "kb_category_id", "in": "query", "schema": { "type": "string" }, "description": "Filters the articles by category." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of `draft`, `published`, `archived`. Omitted, every status is returned." } ], "responses": { "200": { "description": "A page of KB articles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticleList" }, "example": { "data": [ { "id": "kba_bf74044c3b65ad94", "title": "Installing Windows 11", "kb_category_id": "kbc_a48669d7fd3f953f", "kb_category": { "id": "kbc_a48669d7fd3f953f", "name": "Windows" }, "status": "published", "public_flag": false, "web_url": "https://example.replypad.com/articles/view/id/kba_bf74044c3b65ad94", "created_on": "2026-03-18T13:48:01Z", "updated_on": "2026-03-18T16:07:35Z" }, { "id": "kba_d58edf1878d40d00", "title": "Installing Ubuntu Linux", "kb_category_id": "kbc_669d7fd3fa48953f", "kb_category": { "id": "kbc_669d7fd3fa48953f", "name": "Linux" }, "status": "published", "public_flag": false, "web_url": "https://example.replypad.com/articles/view/id/kba_d58edf1878d40d00", "created_on": "2026-03-17T10:12:01Z", "updated_on": "2026-03-17T10:57:35Z" } ], "has_more": true, "next_cursor": "eyJmIjp7InN0IjoicHVibGlzaGVkIn0sInMiOiJrYmFfc2JfdGlfYSIsInBzIjo1MCwic3YiOnsic3YxIjoiUmVzZXR0aW5nIGEgcGFzc3dvcmQiLCJzdjIiOiJrYmFfMWY1YzkzZTdhMjA4ZDRiNiJ9fQ:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/kb-articles/{article_id}": { "parameters": [ { "name": "article_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "KB article ID (starts with `kba_`)." } ], "get": { "tags": [ "KB Articles" ], "operationId": "getKbArticle", "summary": "Retrieve a knowledge-base article", "responses": { "200": { "description": "The article (always including `description` and `body`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KbArticleEnvelope" }, "example": { "data": { "id": "kba_bf74044c3b65ad94", "title": "Installing Windows 11", "kb_category_id": "kbc_669d7fd3f95a483f", "kb_category": { "id": "kbc_669d7fd3f95a483f", "name": "General" }, "status": "published", "public_flag": false, "public_level": null, "public_selected_accounts": null, "description": "How to install Windows 11", "body": "Follow this procedure...", "web_url": "https://example.replypad.com/articles/view/id/kba_bf74044c3b65ad94", "created_on": "2026-03-18T13:48:01Z", "updated_on": "2026-03-18T16:07:35Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/saved-responses": { "get": { "tags": [ "Saved Responses" ], "operationId": "listSavedResponses", "summary": "List saved responses", "description": "Sorted by name ascending, 50 per page.", "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "name": "expand", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated. Allowed: `content` (adds `body`)." } ], "responses": { "200": { "description": "A page of saved responses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedResponseList" }, "example": { "data": [ { "id": "res_5c5585fc630d2d8b", "name": "Install procedure", "magic_keyword": "install", "teams_filter_enabled": false, "teams_filter": null, "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" }, { "id": "res_940acdd00d2a9da7", "name": "Configure DNS", "magic_keyword": "configure_dns", "teams_filter_enabled": true, "teams_filter": [ { "id": "tea_554c121065744a34", "name": "Sales" } ], "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } ], "has_more": true, "next_cursor": "eyJmIjpbXSwicyI6InJlc19zYl9ubV9hIiwicHMiOjUwLCJzdiI6eyJzdjEiOiJXZWxjb21lIHJlcGx5Iiwic3YyIjoicmVzXzhhMjRkMGM2ZjMxYjk1ZTcifX0:6f1d3b9c0a4e7d2b8c5a" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/saved-responses/{response_id}": { "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Saved response ID (starts with `res_`)." } ], "get": { "tags": [ "Saved Responses" ], "operationId": "getSavedResponse", "summary": "Retrieve a saved response", "responses": { "200": { "description": "The saved response (always including `body`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedResponseEnvelope" }, "example": { "data": { "id": "res_5c5585fc630d2d8b", "name": "Install procedure", "magic_keyword": "install", "body": "Install Procedure\nPrepare to install the server...", "teams_filter_enabled": false, "teams_filter": null, "status": "active", "created_on": "2025-11-21T14:07:12Z", "updated_on": "2026-01-08T09:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/tokens/me": { "get": { "tags": [ "Tokens" ], "operationId": "getCurrentToken", "summary": "Retrieve the current token", "description": "Describes the calling token: its name, expiry, read-only flag, the user it acts as, and what it may read and write per resource. Takes no parameters.\n\nThis is the whole Tokens API — tokens are created, renamed and revoked in the Replypad web UI only, and the token value itself is never returned.\n", "responses": { "200": { "description": "The calling token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenEnvelope" }, "example": { "data": { "principal_type": "user", "name": "Impersonate John Doe", "read_only_token": false, "expires_on": null, "user": { "id": "per_dfba3ff87fc19c96", "first_name": "John", "last_name": "Doe", "nickname": "@john", "primary_email": "johndoe@example.com" }, "permissions": { "privilege_group": "limited", "accounts_read": true, "accounts_write": false, "contacts_read": true, "contacts_write": false, "assets_read": true, "assets_write": false, "charges_read": true, "charges_write": true, "time_entries_read": true, "time_entries_write": true, "contracts_read": true, "contracts_write": false, "items_read": true, "items_write": false, "tickets_read": true, "tickets_write": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "The token is a workspace-level \"generic\" token, which acts as no user and is not part of this API. Code: `not_supported`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_supported", "message": "Generic workspace tokens are not supported by this API." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/metadata/custom-fields/tickets": { "get": { "tags": [ "Metadata" ], "operationId": "getTicketCustomFieldDefinitions", "summary": "Ticket custom-field definitions", "responses": { "200": { "description": "The workspace's custom-field definitions for tickets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsEnvelope" }, "example": { "data": [ { "key": "severity_level", "label": "Severity Level", "type": "string", "created_on": "2026-02-02T13:48:01Z", "updated_on": "2026-02-02T13:48:01Z" }, { "key": "extra_note", "label": "Extra Note", "type": "string", "created_on": "2026-02-11T13:48:01Z", "updated_on": "2026-02-11T13:48:01Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/metadata/custom-fields/accounts": { "get": { "tags": [ "Metadata" ], "operationId": "getAccountCustomFieldDefinitions", "summary": "Account custom-field definitions", "responses": { "200": { "description": "The workspace's custom-field definitions for accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsEnvelope" }, "example": { "data": [ { "key": "industry", "label": "Industry", "type": "string", "created_on": "2026-02-02T13:48:01Z", "updated_on": "2026-02-02T13:48:01Z" }, { "key": "legal_structure", "label": "Legal Structure", "type": "string", "created_on": "2026-02-08T09:22:01Z", "updated_on": "2026-02-08T09:22:01Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/metadata/custom-fields/contacts": { "get": { "tags": [ "Metadata" ], "operationId": "getContactCustomFieldDefinitions", "summary": "Contact custom-field definitions", "responses": { "200": { "description": "The workspace's custom-field definitions for contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsEnvelope" }, "example": { "data": [ { "key": "gender", "label": "Gender", "type": "string", "created_on": "2026-02-02T13:48:01Z", "updated_on": "2026-02-02T13:48:01Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/metadata/custom-fields/assets": { "get": { "tags": [ "Metadata" ], "operationId": "getAssetCustomFieldDefinitions", "summary": "Asset custom-field definitions", "responses": { "200": { "description": "The workspace's custom-field definitions for assets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsEnvelope" }, "example": { "data": [ { "key": "user_manual_link", "label": "User Manual Link", "type": "url", "created_on": "2026-02-02T13:48:01Z", "updated_on": "2026-02-02T13:48:01Z" }, { "key": "brand", "label": "Brand", "type": "string", "created_on": "2026-02-02T13:50:19Z", "updated_on": "2026-02-02T13:50:19Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/metadata/custom-fields/contracts": { "get": { "tags": [ "Metadata" ], "operationId": "getContractCustomFieldDefinitions", "summary": "Contract custom-field definitions", "description": "Requires full billing access rights — the same right that gates the `custom_fields` values on the contract itself.\n", "responses": { "200": { "description": "The workspace's custom-field definitions for contracts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsEnvelope" }, "example": { "data": [ { "key": "service_scope", "label": "Service Scope", "type": "string", "created_on": "2026-02-02T13:48:01Z", "updated_on": "2026-02-02T13:48:01Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/metadata/custom-fields/users": { "get": { "tags": [ "Metadata" ], "operationId": "getUserCustomFieldDefinitions", "summary": "User custom-field definitions", "description": "Admin tokens only — user `custom_fields` values are admin-only on the user object itself, so their definitions are too.\n", "responses": { "200": { "description": "The workspace's custom-field definitions for users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldDefinitionsEnvelope" }, "example": { "data": [ { "key": "hire_date", "label": "Hire Date", "type": "date", "created_on": "2026-02-02T13:48:01Z", "updated_on": "2026-02-02T13:48:01Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Per-user API token: a 64-character hexadecimal string created in the Replypad web UI. Sent as `Authorization: Bearer `. Access to any resource is subject to the token's permissions — see **Permissions** in the API description.\n" } }, "parameters": { "cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from a previous response's `next_cursor`. Never expires. Any filter sent alongside it must match the request that produced it; omitted filters fall back to the cursor's values. See **Pagination** in the API description for the full rules.\n" }, "ticketId": { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ticket ID (starts with `tkt_`)." }, "commentId": { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Comment ID (starts with `cmt_`)." }, "accountId": { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account ID (starts with `acc_`)." }, "contactId": { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact ID (starts with `per_`)." }, "assetId": { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Asset ID (starts with `ast_`)." }, "itemId": { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Item ID (starts with `itm_`)." }, "chargeId": { "name": "charge_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Charge ID (starts with `crg_`)." }, "contractId": { "name": "contract_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contract ID (starts with `bct_`)." }, "labelId": { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Label ID (starts with `lbl_`)." } }, "responses": { "BadRequest": { "description": "The request could not be processed. Codes: `invalid_request` (malformed JSON body or query parameters), `invalid_cursor`, `invalid_id_format`, `missing_required_field`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Request body is not valid JSON." } } } } }, "PayloadTooLarge": { "description": "The request body is larger than the resource accepts - 128 KB for tickets and their sub-resources, 16 KB elsewhere. The body is refused before any validation runs, so no field-level errors are reported. Code: `payload_too_large`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds the maximum size allowed in bytes." } } } } }, "Unauthorized": { "description": "The credentials have to be fixed before retrying. Codes: `token_missing`, `token_invalid`, `token_revoked`, `token_expired`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "token_missing", "message": "Missing or invalid Authorization header." } } } } }, "Forbidden": { "description": "The token is valid but may not perform this call. Codes: `forbidden` (not enough privileges, or the ticket or comment is scheduled for publishing and is owned by the scheduler until it goes out), `read_only_token`, `account_id_required` (this token may only list the resource one account at a time).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Insufficient privileges for this operation." } } } } }, "NotFound": { "description": "The addressed object does not exist — or the token has no access to it (access denials on row-level resources are reported as 404 to avoid leaking existence). Code: `not_found`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Ticket not found." } } } } }, "Conflict": { "description": "A collision the caller has to resolve. Codes: `conflict`, `already_exists` (unique value taken), `in_use` (referenced by other objects).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "already_exists", "message": "An account with this name already exists." } } } } }, "ValidationError": { "description": "The request is well formed but its data is not acceptable. Codes: `validation_failed`, `missing_required_field`, `unknown_field`, `reference_not_found` (an ID inside the body does not resolve), `invalid_state`, `wrong_endpoint`, `not_supported`, `locked`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "Ticket subject exceeds the maximum length of 255 characters." } } } } }, "RateLimited": { "description": "Back off and retry. Codes: `rate_limited` (over the call limits), `too_many_errors` (token temporarily blocked after repeated failing calls). The `Retry-After` header gives the seconds to wait.\n", "headers": { "Retry-After": { "description": "Whole seconds to wait before retrying - until the breached rate window rolls over, or until the block lifts.\n", "schema": { "type": "integer", "minimum": 1 }, "example": 42 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "API rate limit exceeded. Please try again later." } } } } }, "InternalError": { "description": "Unexpected server error. Code: `internal_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal server error." } } } } }, "ServiceUnavailable": { "description": "The API is closed for a planned maintenance window. Every endpoint answers this way while the window is open. Retry after the delay in `Retry-After`. Code: `service_unavailable`.\n", "headers": { "Retry-After": { "description": "Whole seconds to wait before retrying - the expected remaining length of the maintenance window.\n", "schema": { "type": "integer", "minimum": 1 }, "example": 300 } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "service_unavailable", "message": "The API is temporarily unavailable for maintenance. Try again shortly." } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "description": "Every error, from every endpoint, has this body. Branch on `code`, never on `message`: the set of `code` values is fixed by this spec, while `message` is human-readable prose that differs between endpoints for the same code and may change without notice. The messages in the examples are realistic but illustrative, not a contract.\n", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "Human-readable explanation." } } } } }, "ErrorCode": { "type": "string", "description": "Machine-readable error code, grouped by what the caller should do next.", "enum": [ "token_missing", "token_invalid", "token_revoked", "token_expired", "forbidden", "read_only_token", "account_id_required", "invalid_request", "invalid_cursor", "invalid_id_format", "payload_too_large", "validation_failed", "missing_required_field", "unknown_field", "reference_not_found", "invalid_state", "wrong_endpoint", "not_supported", "locked", "not_found", "method_not_allowed", "conflict", "already_exists", "in_use", "rate_limited", "too_many_errors", "internal_error", "service_unavailable" ] }, "StarKey": { "type": "string", "description": "Star marker key.", "enum": [ "red_star", "green_star", "blue_star", "orange_star", "orchid_star", "gray_star", "question_mark", "truck", "cloud", "lightning_bolt", "phone", "tool", "flight", "pause", "circle", "arch", "do_not_disturb", "highlight", "all_inclusive", "light", "victory_flag", "square", "triangle" ] }, "TicketCustomFields": { "type": "object", "nullable": true, "description": "Map of custom-field key to value for tickets. Keys are the workspace-defined field keys, maximum 40 characters (definitions at `/v1/metadata/custom-fields/tickets`); values are strings formatted per the field type (`string`, `date` as YYYY-MM-DD, `url`). For example, `\"extra_note\": \"Happened again\"` and `\"severity_level\": \"5\"`, where `extra_note` is the custom field key with the value \"Happened again\" and `severity_level` is another custom field key with the value \"5\". `null` when the ticket has no custom-field values.\n", "additionalProperties": { "type": "string" }, "example": { "severity_level": "5", "extra_note": "Happened again" } }, "AccountCustomFields": { "type": "object", "nullable": true, "description": "Map of custom-field key to value for accounts. Keys are the workspace-defined field keys, maximum 40 characters (definitions at `/v1/metadata/custom-fields/accounts`); values are strings formatted per the field type (`string`, `date` as YYYY-MM-DD, `url`). For example, `\"industry\": \"Tech\"` and `\"legal_structure\": \"Corporation\"`, where `industry` is the custom field key with the value \"Tech\" and `legal_structure` is another custom field key with the value \"Corporation\". `null` when the account has no custom-field values.\n", "additionalProperties": { "type": "string" }, "example": { "industry": "Tech", "legal_structure": "Corporation" } }, "ContactCustomFields": { "type": "object", "nullable": true, "description": "Map of custom-field key to value for contacts. Keys are the workspace-defined field keys, maximum 40 characters (definitions at `/v1/metadata/custom-fields/contacts`); values are strings formatted per the field type (`string`, `date` as YYYY-MM-DD, `url`). For example, `\"vip_status\": \"platinum\"` and `\"vip_plan_level\": \"3\"`, where `vip_status` is the custom field key with the value \"platinum\" and `vip_plan_level` is another custom field key with the value \"3\". `null` when the contact has no custom-field values.\n", "additionalProperties": { "type": "string" }, "example": { "vip_status": "platinum", "vip_plan_level": "3" } }, "AssetCustomFields": { "type": "object", "nullable": true, "description": "Map of custom-field key to value for assets. Keys are the workspace-defined field keys, maximum 40 characters (definitions at `/v1/metadata/custom-fields/assets`); values are strings formatted per the field type (`string`, `date` as YYYY-MM-DD, `url`). For example, `\"brand\": \"HP\"` and `\"user_manual_link\": \"https://hp.com/.../hp_250_g10.pdf\"`, where `brand` is the custom field key with the value \"HP\" and `user_manual_link` is another custom field key holding a URL. `null` when the asset has no custom-field values.\n", "additionalProperties": { "type": "string" }, "example": { "brand": "HP", "user_manual_link": "https://hp.com/.../hp_250_g10.pdf" } }, "ContractCustomFields": { "type": "object", "nullable": true, "description": "Map of custom-field key to value for contracts. Keys are the workspace-defined field keys, maximum 40 characters (definitions at `/v1/metadata/custom-fields/contracts`); values are strings formatted per the field type (`string`, `date` as YYYY-MM-DD, `url`). For example, `\"service_scope\": \"Maintenance\"`, where `service_scope` is the custom field key with the value \"Maintenance\". `null` when the contract has no custom-field values.\n", "additionalProperties": { "type": "string" }, "example": { "service_scope": "Maintenance" } }, "UserCustomFields": { "type": "object", "nullable": true, "description": "Map of custom-field key to value for users. Keys are the workspace-defined field keys, maximum 40 characters; values are strings formatted per the field type (`string`, `date` as YYYY-MM-DD, `url`). For example, `\"hire_date\": \"2026-03-19\"` and `\"gender\": \"M\"`, where `hire_date` is the custom field key with the value \"2026-03-19\" and `gender` is another custom field key with the value \"M\". `null` when the user has no custom-field values.\n", "additionalProperties": { "type": "string" }, "example": { "hire_date": "2026-03-19", "gender": "M" } }, "Phone": { "type": "object", "nullable": true, "properties": { "number": { "type": "string", "maxLength": 25 }, "description": { "type": "string", "maxLength": 50, "nullable": true } } }, "Address": { "type": "object", "nullable": true, "properties": { "addressline1": { "type": "string", "maxLength": 100, "nullable": true }, "addressline2": { "type": "string", "maxLength": 100, "nullable": true }, "addressline3": { "type": "string", "maxLength": 100, "nullable": true }, "city": { "type": "string", "maxLength": 50, "nullable": true }, "state": { "type": "string", "maxLength": 50, "nullable": true }, "zip": { "type": "string", "maxLength": 25, "nullable": true }, "country": { "type": "string", "maxLength": 50, "nullable": true } } }, "AccountSummary": { "type": "object", "nullable": true, "description": "Inline account summary. Read-only — must never be included in requests to the server. Expanding `account` replaces it with the full Account object.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 150 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this account in the web application." } } }, "ContactSummary": { "type": "object", "nullable": true, "description": "Inline contact summary. Read-only — must never be included in requests to the server. Expanding `contact` replaces it with the full Contact object.\n", "properties": { "id": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "primary_email": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this contact in the web application." } } }, "AssetSummary": { "type": "object", "nullable": true, "description": "Inline asset summary, present only when `asset` is expanded. Read-only — must never be included in requests to the server.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this asset in the web application." } } }, "AssigneeSummary": { "type": "object", "nullable": true, "description": "The user assigned to the ticket. Read-only — must never be included in requests to the server.\n", "properties": { "id": { "type": "string", "description": "The `user_id` of the assigned user." }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "primary_email": { "type": "string", "nullable": true }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this user in the web application." } } }, "TeamRef": { "type": "object", "nullable": true, "description": "Read-only team reference — must never be included in requests to the server.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "MailboxRef": { "type": "object", "nullable": true, "description": "Read-only mailbox reference — must never be included in requests to the server.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "KbCategoryRef": { "type": "object", "nullable": true, "description": "Read-only knowledge-base category reference.", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "LabelRef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "CcRecipient": { "type": "object", "description": "A contact or user CC'd on all messages sent for the ticket (read-only representation).\n", "properties": { "id": { "type": "string", "description": "The ID of the associated contact or user." }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "email_address": { "type": "string" } } }, "Follower": { "type": "object", "description": "A user involved in the ticket without being the assigned user (read-only representation).\n", "properties": { "id": { "type": "string", "description": "The ID of the associated user." }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "email_address": { "type": "string" } } }, "ContactEmail": { "type": "object", "required": [ "email_address" ], "properties": { "email_address": { "type": "string", "format": "email", "maxLength": 254, "description": "A valid email address (RFC 5321/5322, RFC 1123 for the domain). Must be unique across all contacts and users.\n" }, "primary_flag": { "type": "boolean", "description": "Whether this is the contact's primary email address. Only one email can be primary.\n" } } }, "Domain": { "type": "object", "properties": { "domain_name": { "type": "string", "maxLength": 254, "description": "A valid domain name as defined by RFC 1034 and RFC 1035, and updated by RFC 1123.\n" } } }, "CustomFieldDefinition": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 40, "description": "The key of the custom field, as configured by the admins in the Replypad workspace.\n" }, "label": { "type": "string", "maxLength": 100, "description": "The display name for the field, as seen in the Replypad workspace.\n" }, "type": { "type": "string", "enum": [ "string", "date", "url" ], "description": "Values of `string`-typed custom fields are limited to 255 characters.\n" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "Ticket": { "type": "object", "description": "In list responses the expand-only fields (`notes`, `labels`, `cc_recipients`, `followers`, `comments`, `custom_fields`, `asset`) are omitted unless requested via `expand`; in detail responses they are always present (except `asset`, which still requires expanding).\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the ticket, generated automatically at creation.\n" }, "subject": { "type": "string", "maxLength": 255, "nullable": true, "description": "The subject of the ticket. When creating a new ticket, at least one of `subject` or `comments` is required.\n" }, "number": { "type": "integer", "description": "A unique ticket number, automatically generated by the system. Read-only. Omitted for drafts (not assigned yet).\n" }, "status": { "type": "string", "enum": [ "draft", "open", "closed", "archived" ], "description": "Default on creation is `open`. `archived` cannot be set, only retrieved — archiving is handled automatically by the system. For existing tickets the status is changed only through the `/status` endpoint.\n" }, "contact_id": { "type": "string", "nullable": true, "description": "The identifier of the ticket's primary contact (the \"To\" recipient). On create and update, if both `contact_id` and the `contact` object are passed, the call is rejected.\n" }, "contact": { "$ref": "#/components/schemas/ContactSummary" }, "account_id": { "type": "string", "nullable": true, "description": "The identifier of the account associated with the ticket. On create and update, if both `account_id` and the `account` object are passed, the call is rejected.\n" }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "asset_id": { "type": "string", "nullable": true, "description": "The identifier of the asset associated with the ticket." }, "asset": { "$ref": "#/components/schemas/AssetSummary" }, "assignee_id": { "type": "string", "nullable": true, "description": "The identifier of the user assigned to the ticket. References a User object.\n" }, "assignee": { "$ref": "#/components/schemas/AssigneeSummary" }, "team_id": { "type": "string", "nullable": true, "description": "The identifier of the team associated with the ticket. If not set, the default team is set.\n" }, "team": { "$ref": "#/components/schemas/TeamRef" }, "mailbox_id": { "type": "string", "nullable": true, "description": "Mailbox replies are sent from. If not provided, the default mailbox is set automatically.\n" }, "mailbox": { "$ref": "#/components/schemas/MailboxRef" }, "received_on_mailbox_id": { "type": "string", "nullable": true, "description": "The id of the mailbox this ticket was initially received on, if any (read-only).\n" }, "received_on_mailbox": { "$ref": "#/components/schemas/MailboxRef" }, "priority_flag": { "type": "boolean", "description": "Whether it is a priority ticket." }, "star_key": { "type": "string", "nullable": true, "description": "One of the StarKey values, or empty when unset." }, "due_date": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 UTC timestamp, e.g. `2026-03-10T14:32:45Z`. Returned as a full timestamp even when it was set from a date-only value. `null` when no due date is set.\n" }, "scheduled_for": { "type": "string", "format": "date-time", "nullable": true, "description": "The timestamp at which the draft ticket is scheduled to be published, i.e. when its status will be changed to `open` or `closed` — e.g. `2026-03-10T14:32:45Z` (read-only). `null` for any ticket that is not a scheduled draft. A scheduled draft belongs to the scheduler: it cannot be published, updated or deleted through the API (403 `forbidden`).\n" }, "published_on": { "type": "string", "format": "date-time", "nullable": true, "description": "The timestamp when the ticket was published (read-only). Always `null` for draft tickets.\n" }, "notes": { "type": "string", "nullable": true, "description": "Notes of the ticket. Maximum length 4,000 characters." }, "labels": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LabelRef" }, "description": "Labels associated with the ticket. Can be provided during creation; for existing tickets, manage them via the `/tickets/{ticket_id}/labels` endpoints.\n" }, "cc_recipients": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/CcRecipient" }, "description": "Contacts or users CC'd on all messages sent for this ticket. Can be provided during creation; for existing tickets, manage them via the `/tickets/{ticket_id}/cc-recipients` endpoints.\n" }, "followers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Follower" }, "description": "Users following the ticket. Can be provided during creation; for existing tickets, manage them via the `/tickets/{ticket_id}/followers` endpoints.\n" }, "comments": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Comment" }, "description": "The ticket's comments. On create, a single comment object may be passed within the array.\n" }, "custom_fields": { "$ref": "#/components/schemas/TicketCustomFields" }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this ticket in the web application (read-only)." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "Comment": { "type": "object", "properties": { "comment_id": { "type": "string", "description": "Unique, opaque identifier for the comment, generated automatically at creation. Important: if a comment was initially created as a draft, its `comment_id` changes once the comment is published.\n" }, "body": { "type": "string", "description": "The plain-text body of the comment. Maximum length for create and update is 32,767 characters; retrieved values may exceed this limit. Currently only plain text is provided — inline images and attachments are not supported.\n" }, "status": { "type": "string", "enum": [ "published", "draft" ], "description": "Default on creation is `published`. Once published, a comment cannot be further updated.\n" }, "type": { "type": "string", "enum": [ "user_public_comment", "customer_comment", "user_internal_note" ], "description": "The kind of comment. Via the API only `user_public_comment` and `user_internal_note` can be created; `customer_comment` entries originate from customers (portal or email).\n" }, "source": { "type": "string", "nullable": true, "enum": [ "web_portal", "email", "trigger", "api" ], "description": "How the comment entered the system (read-only)." }, "from_id": { "type": "string", "nullable": true, "description": "The author of the comment (a contact or user ID)." }, "from": { "type": "object", "nullable": true, "description": "The comment's author — a Contact or User object.", "properties": { "id": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "primary_email": { "type": "string", "nullable": true }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this contact or user in the web application." } } }, "date": { "type": "string", "format": "date-time", "description": "Read-only. For draft comments, the last time the comment was updated; for published comments, the time when it was published.\n" }, "resolution_flag": { "type": "boolean", "readOnly": true, "description": "Whether the comment is marked as a resolution." }, "scheduled_for": { "type": "string", "format": "date-time", "nullable": true, "description": "The timestamp at which the draft comment is scheduled to be published — e.g. `2026-03-10T14:32:45Z` (read-only). Always `null` for published comments, and `null` for a draft that is not scheduled. A scheduled draft comment cannot be updated, published or discarded through the API (403 `forbidden`).\n" } } }, "TicketCreate": { "type": "object", "description": "`subject` and/or exactly one entry in `comments` is required. Unknown fields are rejected with 422 `unknown_field`.\n", "properties": { "subject": { "type": "string", "maxLength": 255, "description": "The subject of the ticket. At least one of `subject` or `comments` is required.\n" }, "comments": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/CommentCreate" }, "description": "Pass a single comment object within the array; if more than one object is passed, the ticket creation fails. At least one of `subject` or `comments` is required. Currently only plain text is supported — inline images and attachments are not.\n" }, "contact_id": { "type": "string", "description": "The identifier of the ticket's primary contact (the \"To\" recipient). If both `contact_id` and the `contact` object are passed, the call is rejected.\n" }, "contact": { "type": "object", "description": "The primary contact for the ticket (the \"To\" recipient). Can be used only if `contact_id` is not passed. Associates the ticket with an existing contact identified by `contact.primary_email`; if no contact with this email address is found, a new contact is created (populated with `contact.first_name` and `contact.last_name`, if provided) and then associated with the ticket.\n", "properties": { "primary_email": { "type": "string", "format": "email", "description": "Used to look up an existing contact and, if none is found, becomes the primary email of the newly created contact. You can safely pass an email address of a User, as users are also valid contacts.\n" }, "first_name": { "type": "string", "maxLength": 50, "description": "Set on the contact only if a new contact is created." }, "last_name": { "type": "string", "maxLength": 50, "description": "Set on the contact only if a new contact is created." } } }, "account_id": { "type": "string", "description": "The identifier of the account associated with the ticket. If both `account_id` and the `account` object are passed, the call is rejected.\n" }, "account": { "type": "object", "description": "The account to associate with the ticket. Can be used only if `account_id` is not passed. Either associates the ticket to an existing account whose name matches `account.name`, or — when no such account exists — creates a new account with that name and sets it on the ticket.\n", "properties": { "name": { "type": "string", "maxLength": 150, "description": "Used to look up an existing account and, if none is found, becomes the name of a newly created account.\n" } } }, "asset_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "open", "closed" ], "default": "open", "description": "`archived` is not accepted. After creation, status changes go through the `/tickets/{ticket_id}/status` endpoint.\n" }, "assignee_id": { "type": "string", "description": "Defaults to the token's user when omitted. `null` is rejected.\n" }, "team_id": { "type": "string", "description": "If not set, the default team is set." }, "mailbox_id": { "type": "string", "description": "If not provided, the default mailbox is set automatically." }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/LabelInput" } }, "cc_recipients": { "type": "array", "items": { "$ref": "#/components/schemas/CcRecipientInput" } }, "followers": { "type": "array", "items": { "$ref": "#/components/schemas/FollowerInput" } }, "priority_flag": { "type": "boolean", "description": "Whether it is a priority ticket. Default is `false`. Must be a JSON boolean — `1` or `\"true\"` is rejected with 422.\n" }, "star_key": { "$ref": "#/components/schemas/StarKey" }, "notes": { "type": "string", "maxLength": 4000 }, "due_date": { "type": "string", "description": "ISO-8601 date (`2026-12-31`) or timestamp (`2026-12-31T17:00:00Z`); must be before 2038. A date-only value is taken as midnight UTC. `null` is ignored on create.\n" }, "custom_fields": { "$ref": "#/components/schemas/TicketCustomFields" } } }, "TicketUpdate": { "type": "object", "description": "Partial update; only the given fields change. `status`, `comments`, `labels`, `cc_recipients` and `followers` are managed through their own endpoints and rejected here.\n", "properties": { "subject": { "type": "string", "maxLength": 255 }, "contact_id": { "type": "string", "description": "The identifier of the ticket's primary contact (the \"To\" recipient). If both `contact_id` and the `contact` object are passed, the call is rejected.\n" }, "contact": { "type": "object", "description": "Can be used only if `contact_id` is not passed, and only if the ticket does not have a contact set already. Associates the ticket with an existing contact identified by `contact.primary_email`; if no contact with this email address is found, a new contact is created (populated with `contact.first_name` and `contact.last_name`, if provided) and then associated with the ticket.\n", "properties": { "primary_email": { "type": "string", "format": "email", "description": "Used to look up an existing contact and, if none is found, becomes the primary email of the newly created contact. You can safely pass an email address of a User, as users are also valid contacts.\n" }, "first_name": { "type": "string", "maxLength": 50, "description": "Set on the contact only if a new contact is created." }, "last_name": { "type": "string", "maxLength": 50, "description": "Set on the contact only if a new contact is created." } } }, "account_id": { "type": "string", "description": "The identifier of the account associated with the ticket. If both `account_id` and the `account` object are passed, the call is rejected.\n" }, "account": { "type": "object", "description": "Can be used only if `account_id` is not passed, and only if the ticket does not have an account set already. Either associates the ticket to an existing account whose name matches `account.name`, or — when no such account exists — creates a new account with that name and sets it on the ticket.\n", "properties": { "name": { "type": "string", "maxLength": 150, "description": "Used to look up an existing account and, if none is found, becomes the name of a newly created account.\n" } } }, "asset_id": { "type": "string", "nullable": true }, "assignee_id": { "type": "string", "nullable": false, "description": "Cannot be cleared: `null` is rejected.\n" }, "team_id": { "type": "string", "nullable": true }, "mailbox_id": { "type": "string", "nullable": true }, "priority_flag": { "type": "boolean", "description": "Must be a JSON boolean — `1` or `\"true\"` is rejected with 422.\n" }, "star_key": { "$ref": "#/components/schemas/StarKey" }, "notes": { "type": "string", "maxLength": 4000, "nullable": true }, "due_date": { "type": "string", "nullable": true, "description": "ISO-8601 date or timestamp; must be before 2038. `null` clears the due date.\n" }, "custom_fields": { "$ref": "#/components/schemas/TicketCustomFields" } } }, "CommentCreate": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 32767, "description": "The plain-text body of the comment. Currently only plain text is supported — inline images and attachments are not.\n" }, "status": { "type": "string", "enum": [ "published", "draft" ], "default": "published" }, "type": { "type": "string", "enum": [ "user_public_comment", "user_internal_note" ], "default": "user_public_comment", "description": "The kind of comment to create. The comment is always published as the token's user.\n" } } }, "CommentUpdate": { "type": "object", "description": "Only draft comments can be updated. `status` is not accepted here (422 `wrong_endpoint`) — a draft is published with `PUT /v1/tickets/{ticket_id}/comments/{comment_id}/publish`.\n", "properties": { "body": { "type": "string" }, "type": { "type": "string", "enum": [ "user_public_comment", "user_internal_note" ] } } }, "LabelInput": { "type": "object", "description": "Reference an existing label by `id`, or by the `name` of an existing active label. Only one of `id` and `name` should be provided. An unknown name is rejected, not created.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 255 } } }, "CcRecipientInput": { "type": "object", "description": "Each item must have exactly one of `id` or `email_address` set. If `id` is set (a contact or user ID both work), the primary email address of that contact/user is added as the recipient; `first_name` and `last_name`, if provided, are ignored and the existing contact's names are used. If `email_address` is passed and a contact with that address exists, that contact is set as a recipient (names ignored); if no such contact exists, a new contact is created with the email address — and with `first_name` and `last_name`, if provided — and set as a recipient. You can safely pass a user's ID or email address wherever a contact's is accepted.\n", "properties": { "id": { "type": "string", "description": "The ID of an existing contact or user." }, "email_address": { "type": "string", "format": "email", "description": "Looks up an existing contact or user; creates a new contact when there is no match.\n" }, "first_name": { "type": "string", "maxLength": 50, "description": "Set only when a new contact is created." }, "last_name": { "type": "string", "maxLength": 50, "description": "Set only when a new contact is created." } } }, "FollowerInput": { "type": "object", "description": "Each item must have exactly one of `id` or `email_address` set. If `id` is set, the primary email address of that user is used. If `email_address` is passed, it must match an existing active staff member (user); otherwise the call is rejected with 422 `reference_not_found`.\n", "properties": { "id": { "type": "string", "description": "The ID of an existing user." }, "email_address": { "type": "string", "format": "email", "description": "An email address of an existing active user." } } }, "TicketEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ticket" } } }, "TicketList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "CommentEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Comment" } } }, "CommentList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "TicketLabelsEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LabelRef" } } } }, "TicketCcRecipientsEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CcRecipient" } } } }, "TicketFollowersEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Follower" } } } }, "Account": { "type": "object", "description": "Accounts hold the organizations or companies you service. Each account may have contacts linked to it — the people you interact with in the organization.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the account, generated automatically at creation.\n" }, "name": { "type": "string", "maxLength": 150, "description": "The name of the account. The name has to be unique among all accounts.\n" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Default on creation is `active`." }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all" ], "description": "What the account's contacts may see. `restricted` — only tickets where the contact appears as the main contact are accessible; `all` — all tickets of this account are accessible to the contact. Default is `restricted`.\n" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" }, "description": "Email domains associated with the account; email arriving from such a domain is automatically assigned to this account. Can be provided during creation; for existing accounts, manage them via the `/accounts/{account_id}/domains` endpoints.\n" }, "banner": { "type": "object", "nullable": true, "description": "An account-level note highlighting important information, visible across the app wherever the account appears.\n", "properties": { "notice": { "type": "string", "maxLength": 4000, "description": "The banner's text content." }, "level": { "type": "string", "enum": [ "red", "orange", "green", "light_gray", "dark_gray" ] } } }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" }, "contacts": { "type": "array", "nullable": true, "description": "Read-only array of contacts belonging to the account. Present only when `contacts` is expanded (detail endpoint).\n", "items": { "$ref": "#/components/schemas/ContactSummary" } }, "custom_fields": { "$ref": "#/components/schemas/AccountCustomFields" }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this account in the web application (read-only)." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "AccountListItem": { "type": "object", "description": "Short form returned by the list endpoint. `domains`, `banner`, `phone1`..`phone5`/`address1` (via `phones_address`) and `custom_fields` are added only when expanded.\n", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all" ] }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "banner": { "type": "object", "nullable": true, "properties": { "notice": { "type": "string" }, "level": { "type": "string", "enum": [ "red", "orange", "green", "light_gray", "dark_gray" ] } } }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" }, "custom_fields": { "$ref": "#/components/schemas/AccountCustomFields" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "AccountCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 150, "description": "Unique per workspace." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all" ] }, "custom_fields": { "$ref": "#/components/schemas/AccountCustomFields" }, "banner": { "type": "object", "description": "An account-level note highlighting important information, visible across the app wherever the account appears.\n", "properties": { "notice": { "type": "string", "maxLength": 4000, "description": "The banner's text content." }, "level": { "type": "string", "enum": [ "red", "orange", "green", "light_gray", "dark_gray" ] } } }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/DomainInput" }, "description": "Email domains to associate with the account, so email arriving from these domains is automatically assigned to it. Accepted only on creation; for existing accounts use the `/accounts/{account_id}/domains` endpoints.\n" } } }, "AccountUpdate": { "type": "object", "description": "Partial update. `domains` is managed through the `/domains` endpoints and rejected here.\n", "properties": { "name": { "type": "string", "maxLength": 150 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all" ] }, "custom_fields": { "$ref": "#/components/schemas/AccountCustomFields" }, "banner": { "type": "object", "nullable": true, "description": "An account-level note highlighting important information, visible across the app wherever the account appears.\n", "properties": { "notice": { "type": "string", "maxLength": 4000, "description": "The banner's text content." }, "level": { "type": "string", "enum": [ "red", "orange", "green", "light_gray", "dark_gray" ] } } }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" } } }, "DomainInput": { "type": "object", "required": [ "domain_name" ], "properties": { "domain_name": { "type": "string", "maxLength": 254, "description": "A valid domain name as defined by RFC 1034 and RFC 1035, and updated by RFC 1123.\n" } } }, "AccountEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } }, "AccountList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountListItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "AccountDomainsEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } }, "Contact": { "type": "object", "description": "Contacts are the people that you service — the ones that send you emails and create tickets.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the contact, generated automatically at creation.\n" }, "first_name": { "type": "string", "maxLength": 50, "nullable": true, "description": "The first name of the contact." }, "last_name": { "type": "string", "maxLength": 50, "nullable": true, "description": "The last name of the contact." }, "primary_email": { "type": "string", "nullable": true, "description": "Primary email address of the contact. Read-only; derived from the primary entry in `emails`.\n" }, "account_id": { "type": "string", "nullable": true, "description": "The ID of the account this contact belongs to, if any." }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Default on creation is `active`. The status of a contact associated with an inactive account is always `inactive`.\n" }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all", "by_account" ], "description": "`restricted` — only tickets where the contact appears as the main contact are accessible; `all` — all tickets of the account are accessible to the contact; `by_account` — use the account's access rights settings. Default is `by_account`.\n" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEmail" }, "description": "Email addresses associated with the contact. Can be provided during creation (exactly one entry marked primary); for existing contacts, manage them via the `/contacts/{contact_id}/emails` endpoints.\n" }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" }, "custom_fields": { "$ref": "#/components/schemas/ContactCustomFields" }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this contact in the web application (read-only)." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "ContactListItem": { "type": "object", "description": "Short form returned by the list endpoint. `emails`, `phone1`..`phone5`/`address1` (via `phones_address`) and `custom_fields` are added only when expanded; expanding `account` replaces the summary with the full account object.\n", "properties": { "id": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "primary_email": { "type": "string", "nullable": true }, "account_id": { "type": "string", "nullable": true }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all", "by_account" ] }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEmail" } }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" }, "custom_fields": { "$ref": "#/components/schemas/ContactCustomFields" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "ContactCreate": { "type": "object", "description": "At least one of `first_name`, `last_name` or `emails` is required.", "properties": { "first_name": { "type": "string", "maxLength": 50 }, "last_name": { "type": "string", "maxLength": 50 }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEmail" }, "description": "Accepted only on creation; for existing contacts use the `/contacts/{contact_id}/emails` endpoints. If passed, exactly one email must be marked primary.\n" }, "account_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all", "by_account" ], "default": "by_account" }, "custom_fields": { "$ref": "#/components/schemas/ContactCustomFields" }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" } } }, "ContactUpdate": { "type": "object", "description": "Partial update. `emails` is managed through the `/emails` endpoints and rejected here.\n", "properties": { "first_name": { "type": "string", "maxLength": 50 }, "last_name": { "type": "string", "maxLength": 50 }, "account_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "contact_access_rights": { "type": "string", "enum": [ "restricted", "all", "by_account" ] }, "custom_fields": { "$ref": "#/components/schemas/ContactCustomFields" }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" } } }, "ContactEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "ContactList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactListItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "ContactEmailsEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEmail" } } } }, "Asset": { "type": "object", "description": "Assets lets you easily track and manage customer equipment, software licenses, software subscriptions, and related infrastructure components.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the asset, generated automatically at creation.\n" }, "name": { "type": "string", "maxLength": 100, "description": "The name of the asset." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Default on creation is `active`." }, "account_id": { "type": "string", "nullable": true, "description": "The account this asset is associated with." }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "contact_id": { "type": "string", "nullable": true, "description": "The contact this asset is associated with. It is perfectly valid to pass a `user_id` value inside the `contact_id` field.\n" }, "contact": { "$ref": "#/components/schemas/ContactSummary" }, "contract_id": { "type": "string", "nullable": true, "description": "The contract this asset is associated with. It can only be set when `account_id` is set, and the contract must belong to that account and be active.\n" }, "type": { "type": "string", "nullable": true, "enum": [ "antivirus", "backup_device", "computer", "hardware", "laptop", "mobile_device", "monitor", "network_equipment", "other", "printer", "router", "scanner", "server", "software", "storage_device", "switch", "tablet", "ups", "web_hosting" ] }, "warranty_exp_date": { "type": "string", "format": "date", "nullable": true, "description": "Date when the warranty expires (ISO 8601 date, `YYYY-MM-DD`)." }, "purchased_date": { "type": "string", "format": "date", "nullable": true, "description": "Date of the purchase (ISO 8601 date, `YYYY-MM-DD`)." }, "installation_date": { "type": "string", "format": "date", "nullable": true, "description": "Date of the installation (ISO 8601 date, `YYYY-MM-DD`)." }, "location": { "type": "string", "maxLength": 100, "nullable": true, "description": "The specific location where the asset is placed or installed." }, "serial_no": { "type": "string", "maxLength": 30, "nullable": true }, "model": { "type": "string", "maxLength": 50, "nullable": true }, "custom_fields": { "$ref": "#/components/schemas/AssetCustomFields" }, "description": { "type": "string", "maxLength": 4000, "nullable": true, "description": "The main description and core details of the asset." }, "notes": { "type": "string", "maxLength": 4000, "nullable": true, "description": "Additional notes and extra details about the asset." }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this asset in the web application (read-only)." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "AssetListItem": { "type": "object", "description": "Short form returned by the list endpoint. `custom_fields` (expand `custom_fields`) and `description`/`notes` (expand `desc_notes`) are omitted unless requested.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the asset, generated automatically at creation.\n" }, "name": { "type": "string", "maxLength": 100, "description": "The name of the asset." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Default on creation is `active`." }, "account_id": { "type": "string", "nullable": true, "description": "The account this asset is associated with." }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "contact_id": { "type": "string", "nullable": true, "description": "The contact this asset is associated with. It is perfectly valid to pass a `user_id` value inside the `contact_id` field.\n" }, "contact": { "$ref": "#/components/schemas/ContactSummary" }, "contract_id": { "type": "string", "nullable": true, "description": "The contract this asset is associated with. It can only be set when `account_id` is set, and the contract must belong to that account and be active.\n" }, "type": { "type": "string", "nullable": true, "enum": [ "antivirus", "backup_device", "computer", "hardware", "laptop", "mobile_device", "monitor", "network_equipment", "other", "printer", "router", "scanner", "server", "software", "storage_device", "switch", "tablet", "ups", "web_hosting" ] }, "warranty_exp_date": { "type": "string", "format": "date", "nullable": true, "description": "Date when the warranty expires (ISO 8601 date, `YYYY-MM-DD`)." }, "purchased_date": { "type": "string", "format": "date", "nullable": true, "description": "Date of the purchase (ISO 8601 date, `YYYY-MM-DD`)." }, "installation_date": { "type": "string", "format": "date", "nullable": true, "description": "Date of the installation (ISO 8601 date, `YYYY-MM-DD`)." }, "location": { "type": "string", "maxLength": 100, "nullable": true, "description": "The specific location where the asset is placed or installed." }, "serial_no": { "type": "string", "maxLength": 30, "nullable": true }, "model": { "type": "string", "maxLength": 50, "nullable": true }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this asset in the web application (read-only)." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "AssetWrite": { "type": "object", "description": "For creation `name` is required; updates are partial.", "properties": { "name": { "type": "string", "maxLength": 100 }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "type": { "type": "string", "enum": [ "antivirus", "backup_device", "computer", "hardware", "laptop", "mobile_device", "monitor", "network_equipment", "other", "printer", "router", "scanner", "server", "software", "storage_device", "switch", "tablet", "ups", "web_hosting" ] }, "account_id": { "type": "string", "nullable": true }, "contact_id": { "type": "string", "nullable": true, "description": "A contact or user ID." }, "contract_id": { "type": "string", "nullable": true, "description": "Requires `account_id` to be set on the asset, and the contract must belong to that account and be active. Pass `null` to clear it. Changing or clearing `account_id` clears the contract too, unless the same request sets a `contract_id` belonging to the new account. Writing this field requires full billing access rights.\n" }, "warranty_exp_date": { "type": "string", "format": "date", "nullable": true }, "purchased_date": { "type": "string", "format": "date", "nullable": true }, "installation_date": { "type": "string", "format": "date", "nullable": true }, "location": { "type": "string", "nullable": true }, "serial_no": { "type": "string", "maxLength": 30, "nullable": true }, "model": { "type": "string", "maxLength": 50, "nullable": true }, "custom_fields": { "$ref": "#/components/schemas/AssetCustomFields" }, "description": { "type": "string", "maxLength": 4000, "nullable": true }, "notes": { "type": "string", "maxLength": 4000, "nullable": true } } }, "AssetEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Asset" } } }, "AssetList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetListItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "Item": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the item, generated automatically at creation.\n" }, "name": { "type": "string", "maxLength": 100, "description": "The name of the product or service. Unique among all items (unique per workspace).\n" }, "description": { "type": "string", "maxLength": 4000, "nullable": true, "description": "Description of the item." }, "type": { "type": "string", "enum": [ "product", "service" ], "description": "The type cannot be changed once set." }, "priced_by": { "type": "string", "enum": [ "fixed_price", "hourly_rate", "hourly_user_rate" ], "description": "For product items it is always `fixed_price`. For service items it can be any of the three supported values.\n" }, "price": { "type": "string", "description": "Decimal as a string, e.g. \"150.00\". Holds the product or service price when `priced_by` is `fixed_price`, the service hourly rate when `priced_by` is `hourly_rate`, and is always 0 if `priced_by` is `hourly_user_rate`. The value can be negative.\n\nRequires price visibility: without it the key is **absent from the response entirely** — it is never returned as `null`. Creating or updating an item needs a stronger right than reading prices does, so the object echoed back from a `POST`/`PATCH` always carries it.\n" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Default on creation is `active`." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "ItemWrite": { "type": "object", "description": "For creation `name`, `type`, `priced_by` and `price` are required; updates are partial. `type` is immutable and rejected on update.\n", "properties": { "name": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "product", "service" ] }, "priced_by": { "type": "string", "enum": [ "fixed_price", "hourly_rate", "hourly_user_rate" ] }, "price": { "type": "number", "description": "Also accepted as a numeric string." }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "description": { "type": "string", "maxLength": 4000, "nullable": true } } }, "ItemEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Item" } } }, "ItemList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "ChargeTime": { "type": "object", "nullable": true, "description": "Time details; `null` for product charges.", "properties": { "start_time": { "type": "string", "nullable": true, "example": "09:00" }, "end_time": { "type": "string", "nullable": true, "example": "10:30" }, "hours_worked": { "type": "string", "example": "01:30" } } }, "ChargeItemRef": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service" ] }, "priced_by": { "type": "string", "enum": [ "fixed_price", "hourly_rate", "hourly_user_rate" ] }, "price": { "type": "string", "description": "Requires price visibility. Without it the key is **absent** rather than `null` — unlike the charge's own money fields.\n" } } }, "ChargeTicketRef": { "type": "object", "nullable": true, "description": "Present only when `ticket` is expanded.", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "subject": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "open", "closed", "archived" ] }, "web_url": { "type": "string", "format": "uri" } } }, "Charge": { "type": "object", "description": "Without price visibility (billing access rights) `billable_flag`, `billed_flag`, `invoice_ref`, `price_rate` and `total_amount` are returned as `null` — the keys stay present. The embedded `item` object behaves differently: it drops its `price` key entirely.\n\n`billable_flag`, `billed_flag` and `invoice_ref` are also `null` for reasons that have nothing to do with permissions (see each field), so only `price_rate` and `total_amount` identify a hidden value reliably.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the charge, generated automatically at creation.\n" }, "type": { "type": "string", "enum": [ "product_charge", "service_charge", "time_entry" ], "description": "The type cannot be changed once set." }, "item_id": { "type": "string", "nullable": true, "description": "The item associated with the charge. If the type is `product_charge`, the item must be a product; if the type is `service_charge` or `time_entry`, the item must be a service.\n" }, "item": { "$ref": "#/components/schemas/ChargeItemRef" }, "account_id": { "type": "string", "nullable": true, "description": "The identifier of the account associated with the charge or time entry. Required for product and service charges; optional for time entries. On create, if omitted and `ticket_id` is passed for a ticket linked to an account, the ticket's account is used.\n" }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "ticket_id": { "type": "string", "nullable": true, "description": "The identifier of the ticket associated with the charge or time entry. On create/update it must reference an active ticket (not draft or archived); responses may reference archived tickets, as tickets are archived automatically over time.\n" }, "ticket": { "$ref": "#/components/schemas/ChargeTicketRef" }, "billable_flag": { "type": "boolean", "nullable": true, "description": "Whether the charge is billable. Default is `true`. Not applicable to time entries. Requires billing access rights.\n" }, "billed_flag": { "type": "boolean", "nullable": true, "description": "Whether the charge is billed. Default is `false`. Not applicable to time entries. Setting it to `true` makes the charge read-only; setting it back to `false` makes it writable again (see the dedicated update flow). Requires billing access rights.\n" }, "invoice_ref": { "type": "string", "maxLength": 20, "nullable": true, "description": "Invoice number, if any. Relevant only if `billed_flag` is `true`. Not applicable to time entries. Requires billing access rights.\n" }, "date": { "type": "string", "format": "date", "description": "ISO 8601 calendar date (`YYYY-MM-DD`), without timezone — represents a date only, not a specific moment in time.\n" }, "user_id": { "type": "string", "nullable": true, "description": "The user associated with the service charge or time entry; `null` for product charges.\n" }, "time": { "$ref": "#/components/schemas/ChargeTime" }, "quantity": { "type": "string", "description": "Decimal as a string; \"0.00\" for time entries. The number of units of a product or fixed-price service being charged, or the number of hours for an hourly-based service charge. Can be negative.\n" }, "price_rate": { "type": "string", "nullable": true, "description": "Price/rate per quantity or hour. Defaults to the item's price or, for hourly services, the user's rate, subject to contract pricing. Can be negative. Requires billing access rights.\n" }, "total_amount": { "type": "string", "nullable": true, "description": "The total amount of this charge, after calculating all discounts. Calculated automatically; read-only. Requires billing access rights.\n" }, "contract_id": { "type": "string", "nullable": true, "description": "The identifier of the contract associated with the charge. Not applicable to time entries. The contract must belong to the charge account, be active, and permit the specified charge type.\n" }, "description": { "type": "string", "maxLength": 4000, "nullable": true, "description": "Description of the charge. If not provided and the item has a description, it is inherited from the item.\n" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "ChargeWrite": { "type": "object", "description": "For creation `type`, `item_id` and `date` are required; updates are partial and `type` is immutable. A billed charge only accepts the dedicated `{billed_flag, invoice_ref}` body.\n", "properties": { "type": { "type": "string", "enum": [ "product_charge", "service_charge", "time_entry" ] }, "item_id": { "type": "string", "description": "For `product_charge` the item must be a product; for `service_charge` and `time_entry` it must be a service.\n" }, "account_id": { "type": "string", "description": "Required for product and service charges; optional for time entries. On create, if omitted and `ticket_id` is passed for a ticket linked to an account, the ticket's account is used; otherwise a charge is rejected and a time entry is created with no account. If passed, the value is used as-is, even when it differs from the ticket's account; an explicit `null` counts as a value (no fallback). On update, the account is never derived from the ticket — changing `ticket_id` does not change `account_id`; send `account_id` explicitly to change it. It cannot be cleared on a charge, only on a time entry. Users without access to accounts cannot set or update `account_id` directly: the account must come from a `ticket_id` linked to an account, and any `account_id` they pass must match that ticket's account.\n" }, "ticket_id": { "type": "string", "nullable": true, "description": "Must reference an active ticket (not in a draft or archived state).\n" }, "contract_id": { "type": "string", "nullable": true, "description": "Not applicable to time entries. The contract must belong to the charge account, be active, and permit the specified charge type. Pass `null` to clear it. When a charge is created without a `contract_id`, the account's contract is selected automatically if exactly one active, current contract permits the charge type; otherwise the charge is left without one. On update, changing `account_id` without passing a `contract_id` re-runs that selection against the new account, so the previous account's contract is never carried over.\n" }, "date": { "type": "string", "format": "date" }, "user_id": { "type": "string", "description": "User to log the charge for. Required for service charges and time entries; not applicable to product charges. Defaults to the token's user; setting it to another user requires sufficient privileges.\n" }, "time": { "type": "object", "description": "Required for time entries, optional for service charges, not accepted for product charges. Either pass `start_time` and `end_time` (then `hours_worked` is auto-calculated) or pass only `hours_worked`. On update, passing only `hours_worked` clears `start_time`/`end_time` if set.\n", "properties": { "start_time": { "type": "string", "example": "09:00", "description": "The time the work started (`HH:MM`). If provided, must be earlier than `end_time`.\n" }, "end_time": { "type": "string", "example": "10:30", "description": "The time the work ended (`HH:MM`). If provided, must be later than `start_time`.\n" }, "hours_worked": { "type": "string", "example": "01:30", "description": "The number of hours worked (`HH:MM`)." } } }, "quantity": { "type": "number" }, "billable_flag": { "type": "boolean" }, "billed_flag": { "type": "boolean", "description": "Rejected on create. On update, only accepted through the dedicated flow: a body containing only `billed_flag` (and optionally `invoice_ref`) and no other fields.\n" }, "invoice_ref": { "type": "string", "maxLength": 20, "nullable": true, "description": "Rejected on create. On update, only accepted together with `billed_flag` in the dedicated flow.\n" }, "price_rate": { "type": "number" }, "description": { "type": "string", "maxLength": 4000, "nullable": true } } }, "ChargeEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Charge" } } }, "ChargeList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "Contract": { "type": "object", "description": "In list responses `account`, `description` and `custom_fields` are omitted unless expanded; in detail responses `description` and `custom_fields` are always present and `account` still requires expanding.\n\nReading contracts needs only the right to log charges — whoever logs a charge has to be able to name the contract it points at. Without **full billing access rights** a contract is reduced to the fields that identify it, `id`, `name`, `account_id` and `status` (plus `account` when expanded); `duration_type`, `interval`, `start_date`, `end_date`, `description`, `custom_fields`, `web_url`, `created_on` and `updated_on` are **absent from the response**, not `null`.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the contract, generated automatically at creation.\n" }, "name": { "type": "string", "maxLength": 100, "description": "The name of the contract." }, "account_id": { "type": "string", "nullable": true }, "account": { "$ref": "#/components/schemas/AccountSummary" }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "canceled" ] }, "duration_type": { "type": "string", "enum": [ "single_term", "recurring" ], "description": "Defines whether the contract runs once or repeats over time." }, "interval": { "type": "object", "nullable": true, "description": "Applicable only to contracts with `duration_type` of `recurring`; `null` for single-term contracts.\n", "properties": { "unit": { "type": "string", "enum": [ "monthly", "yearly" ], "description": "The recurrence unit for a recurring contract." }, "total_intervals": { "type": "integer", "description": "How many times the interval repeats." } } }, "start_date": { "type": "string", "format": "date", "nullable": true, "description": "The date the contract starts (`YYYY-MM-DD`)." }, "end_date": { "type": "string", "format": "date", "nullable": true, "description": "The date the contract ends (`YYYY-MM-DD`). Required for single-term contracts.\n" }, "description": { "type": "string", "maxLength": 4000, "nullable": true }, "custom_fields": { "$ref": "#/components/schemas/ContractCustomFields" }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this contract in the web application." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "ContractEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contract" } } }, "ContractList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "Label": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 255 }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "Star": { "type": "object", "properties": { "star_key": { "$ref": "#/components/schemas/StarKey" }, "system_name": { "type": "string", "maxLength": 50, "description": "The predefined (built-in) name of the star." }, "name": { "type": "string", "maxLength": 50, "description": "The current name of the star — either the `system_name` value or a custom name set to the star in the system.\n" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "Team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "maxLength": 50 }, "default_flag": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "User": { "type": "object", "description": "Users are team members who can be assigned to tickets — the ones who communicate with customers (contacts) and manage customer information in the workspace. The admin-only fields (`phone1`..`phone5`, `address1`, `custom_fields`, `web_url`) appear on the detail endpoint only when the token's user has admin rights.\n", "properties": { "id": { "type": "string", "description": "Unique, opaque identifier for the user, generated automatically at creation.\n" }, "first_name": { "type": "string", "maxLength": 50, "nullable": true }, "last_name": { "type": "string", "maxLength": 50, "nullable": true }, "nickname": { "type": "string", "maxLength": 15, "nullable": true, "description": "No more than 15 characters long; begins and ends with a letter or number and may contain underscores.\n" }, "primary_email": { "type": "string", "nullable": true, "description": "Primary email address of the user." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEmail" } }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "phone1": { "$ref": "#/components/schemas/Phone" }, "phone2": { "$ref": "#/components/schemas/Phone" }, "phone3": { "$ref": "#/components/schemas/Phone" }, "phone4": { "$ref": "#/components/schemas/Phone" }, "phone5": { "$ref": "#/components/schemas/Phone" }, "address1": { "$ref": "#/components/schemas/Address" }, "custom_fields": { "$ref": "#/components/schemas/UserCustomFields" }, "web_url": { "type": "string", "format": "uri" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "Mailbox": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email_address": { "type": "string", "format": "email" }, "aliases": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" } }, "default_flag": { "type": "boolean" }, "personalized_reply_enabled": { "type": "boolean" }, "personalized_avatars_enabled": { "type": "boolean" }, "default_team_id": { "type": "string", "nullable": true, "description": "The team automatically set for tickets created under this mailbox, unless another team is specifically set when the ticket is created.\n" }, "default_team": { "$ref": "#/components/schemas/TeamRef" }, "autoresponse_enabled": { "type": "boolean", "description": "Whether an autoresponse is configured for the mailbox. If `true`, the mailbox sends an autoresponse when it receives a message that creates a new ticket.\n" }, "autoresponse_custom_enabled": { "type": "boolean", "description": "Whether the custom autoresponse text is used." }, "autoresponse_custom_text": { "type": "string", "maxLength": 65535, "nullable": true, "description": "Custom autoresponse text the mailbox sends when it receives a message that creates a new ticket.\n" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "KbCategory": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "default_flag": { "type": "boolean" }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "KbArticle": { "type": "object", "description": "In list responses `description` and `body` are included only with `expand=content`; the detail endpoint always includes them.\n", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "kb_category_id": { "type": "string", "nullable": true }, "kb_category": { "$ref": "#/components/schemas/KbCategoryRef" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "public_flag": { "type": "boolean", "description": "Whether the article is available in the customer portal." }, "public_level": { "type": "string", "nullable": true, "enum": [ "everyone", "selected_accounts_only" ], "description": "Relevant only if `public_flag` is `true`." }, "public_selected_accounts": { "type": "array", "nullable": true, "description": "The accounts for which the article is available. Relevant only if `public_flag` is `true` and `public_level` is `selected_accounts_only`.\n", "items": { "$ref": "#/components/schemas/AccountSummary" } }, "description": { "type": "string", "maxLength": 65535, "nullable": true, "description": "Plain text describing the problem, symptom, issue or question addressed by the article. Currently only plain text is provided — inline images and attachments are not supported.\n" }, "body": { "type": "string", "nullable": true, "description": "Plain text content of the article: detailed instructions, troubleshooting and resolution steps, procedures and explanations. Currently only plain text is provided — inline images and attachments are not supported.\n" }, "web_url": { "type": "string", "format": "uri", "description": "URL to view this article in the web application." }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "SavedResponse": { "type": "object", "description": "In list responses `body` is included only with `expand=content`; the detail endpoint always includes it (plus `status`).\n", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "magic_keyword": { "type": "string", "maxLength": 20, "nullable": true }, "teams_filter_enabled": { "type": "boolean", "description": "When `false`, the saved response is available in all tickets; when `true`, only for tickets belonging to the teams in `teams_filter`.\n" }, "teams_filter": { "type": "array", "nullable": true, "description": "The teams for which the saved response is available. Relevant only when `teams_filter_enabled` is `true`; `null` when the response is available to all teams.\n", "items": { "$ref": "#/components/schemas/TeamRef" } }, "body": { "type": "string", "description": "The plain text content of the saved response. Currently only plain text is provided — inline images and attachments are not supported.\n" }, "status": { "type": "string", "enum": [ "active" ] }, "created_on": { "type": "string", "format": "date-time" }, "updated_on": { "type": "string", "format": "date-time" } } }, "LabelEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Label" } } }, "LabelList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "StarEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Star" } } }, "StarList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Star" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "TeamEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Team" } } }, "TeamList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "UserEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/User" } } }, "TokenEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Token" } } }, "Token": { "type": "object", "description": "The calling API token, as returned by `GET /v1/tokens/me`.", "required": [ "principal_type", "name", "read_only_token", "expires_on", "user", "permissions" ], "properties": { "principal_type": { "type": "string", "enum": [ "user" ], "description": "The only supported value is `user`. Workspace-level \"generic\" tokens are not served by this endpoint.\n" }, "name": { "type": "string", "nullable": true, "description": "Human-readable name assigned when the token was created. Not unique.\n" }, "read_only_token": { "type": "boolean", "description": "When true, only GET requests are permitted; writes are rejected with 403 `read_only_token`. Every `*_write` permission below is then `false` as well.\n" }, "expires_on": { "type": "string", "format": "date", "nullable": true, "description": "The day the token expires, `YYYY-MM-DD`. `null` means it never expires. There is no refresh flow — a human extends or reissues the token in the web UI.\n" }, "user": { "$ref": "#/components/schemas/TokenUser" }, "permissions": { "$ref": "#/components/schemas/TokenPermissions" } } }, "TokenUser": { "type": "object", "nullable": true, "description": "The user this token acts as.", "required": [ "id", "first_name", "last_name", "nickname", "primary_email" ], "properties": { "id": { "type": "string", "description": "User ID (starts with `per_`)." }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "nickname": { "type": "string", "nullable": true }, "primary_email": { "type": "string", "nullable": true } } }, "TokenPermissions": { "type": "object", "description": "A summary of what this token may read and write, per resource. Unrestricted resources are not listed.\n\nEach `*_read` reflects the user's privileges alone. Each `*_write` reflects the *effective* ability: it is false whenever the token is read-only, even if the user's privileges would allow the write.\n\nCharges and time entries are reported separately because the backend gates them separately — a user restricted to logging time may have `time_entries_write: true` alongside `charges_write: false`.\n", "required": [ "privilege_group", "accounts_read", "accounts_write", "contacts_read", "contacts_write", "assets_read", "assets_write", "charges_read", "charges_write", "time_entries_read", "time_entries_write", "contracts_read", "contracts_write", "items_read", "items_write", "tickets_read", "tickets_write" ], "properties": { "privilege_group": { "type": "string", "enum": [ "admin", "power_user", "standard", "limited" ], "description": "The privileges group of the user the token acts as." }, "accounts_read": { "type": "boolean", "description": "Whether this token can read or retrieve account data." }, "accounts_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify account data.\n" }, "contacts_read": { "type": "boolean", "description": "Whether this token can read or retrieve contact data." }, "contacts_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify contact data.\n" }, "assets_read": { "type": "boolean", "description": "Whether this token can read or retrieve asset data." }, "assets_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify asset data.\n" }, "charges_read": { "type": "boolean", "description": "Whether this token can read or retrieve charge data — product and service charges, as opposed to time entries. This is the general-case answer; a caller who has it as `false` can still see product and service charges on a specific ticket they may access.\n" }, "charges_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify charge data.\n" }, "time_entries_read": { "type": "boolean", "description": "Whether this token can read or retrieve time entry data." }, "time_entries_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify time entry data.\n" }, "contracts_read": { "type": "boolean", "description": "Whether this token can read or retrieve contract data." }, "contracts_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify contract data. Contracts are read-only through the API, so this reports the underlying right rather than a reachable operation.\n" }, "items_read": { "type": "boolean", "description": "Whether this token can read or retrieve item data." }, "items_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify item data.\n" }, "tickets_read": { "type": "boolean", "description": "Whether this token can read or retrieve ticket data. Tickets have no read privilege — access is decided per row — so this is always true.\n" }, "tickets_write": { "type": "boolean", "description": "Whether this token can create, update, delete, or otherwise modify ticket data.\n" } } }, "UserList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "MailboxEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Mailbox" } } }, "MailboxList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "KbCategoryEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KbCategory" } } }, "KbCategoryList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbCategory" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "KbArticleEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/KbArticle" } } }, "KbArticleList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KbArticle" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "SavedResponseEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SavedResponse" } } }, "SavedResponseList": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "CustomFieldDefinitionsEnvelope": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDefinition" } } } } } } }