{ "openapi": "3.0.3", "info": { "title": "Tidela API", "version": "v1", "description": "Workspace-scoped REST API. Authenticate with `Authorization: Bearer `. Webhook events: account.archived, account.created, account.merged, account.updated, activity.completed, comment.created, contact.archived, contact.created, contact.merged, contact.updated, custom_record.created, custom_record.updated, deal.archived, deal.created, deal.stage_changed, deal.updated, partner.applied, project.created, project.stage_changed, project.updated, quote.accepted." }, "servers": [ { "url": "https://app.tidela.ai/api/v1" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "paths": { "/ping/": { "get": { "summary": "Verify a key: returns workspace, mode and scopes.", "tags": [ "Basics" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } } }, "/accounts/": { "get": { "summary": "List accounts.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated field names to return (lean responses).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 \u2014 incremental sync mode: returns records changed since then, oldest first, INCLUDING archived ones (archived: true).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "field or -field (whitelisted fields; uses offset paging via ?offset= instead of cursors; not combinable with updated_since).", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters on whitelisted fields: __gte __lte __gt __lt __contains __in (comma-separated). E.g. amount__gte=1000, created_at__lt=2026-01-01, status__in=open,won.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Name contains.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "active | inactive.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "Filter by owner.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO alpha-2.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "1 to include archived records.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "custom_fields", "schema": { "type": "string" } } ] }, "post": { "summary": "Create an account. Duplicate website domain returns 409 with the existing id (override with ?force=1).", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "website": { "type": "string", "description": "Domain is derived from this for duplicate detection." }, "linkedin_url": { "type": "string", "description": "" }, "phone": { "type": "string", "description": "" }, "street": { "type": "string", "description": "" }, "city": { "type": "string", "description": "" }, "state_region": { "type": "string", "description": "" }, "postal_code": { "type": "string", "description": "" }, "country": { "type": "string", "description": "ISO-3166 alpha-2, e.g. US." }, "status": { "type": "string", "description": "active | inactive." }, "customer_type": { "type": "string", "description": "An Account Type key from this workspace's catalog (Admin \u2192 Account types), e.g. customer, prospect, vendor. Reads also include customer_type_name. Empty string clears it." }, "owner_id": { "type": "string", "description": "Must be an active member of the workspace." }, "parent_id": { "type": "string", "description": "Parent account." }, "notes": { "type": "string", "description": "" }, "custom_fields": { "type": "object", "description": "{key: value} \u2014 see GET /meta/custom-fields/." } } } } } } } }, "/accounts/upsert/": { "post": { "summary": "Create-or-update matched by website domain. Response carries created: true|false.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "website": { "type": "string", "description": "Domain is derived from this for duplicate detection." }, "linkedin_url": { "type": "string", "description": "" }, "phone": { "type": "string", "description": "" }, "street": { "type": "string", "description": "" }, "city": { "type": "string", "description": "" }, "state_region": { "type": "string", "description": "" }, "postal_code": { "type": "string", "description": "" }, "country": { "type": "string", "description": "ISO-3166 alpha-2, e.g. US." }, "status": { "type": "string", "description": "active | inactive." }, "customer_type": { "type": "string", "description": "An Account Type key from this workspace's catalog (Admin \u2192 Account types), e.g. customer, prospect, vendor. Reads also include customer_type_name. Empty string clears it." }, "owner_id": { "type": "string", "description": "Must be an active member of the workspace." }, "parent_id": { "type": "string", "description": "Parent account." }, "notes": { "type": "string", "description": "" }, "custom_fields": { "type": "object", "description": "{key: value} \u2014 see GET /meta/custom-fields/." } } } } } } } }, "/accounts/{id}/": { "get": { "summary": "Fetch one account (custom fields included).", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update fields you send; everything else is untouched.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "website": { "type": "string", "description": "Domain is derived from this for duplicate detection." }, "linkedin_url": { "type": "string", "description": "" }, "phone": { "type": "string", "description": "" }, "street": { "type": "string", "description": "" }, "city": { "type": "string", "description": "" }, "state_region": { "type": "string", "description": "" }, "postal_code": { "type": "string", "description": "" }, "country": { "type": "string", "description": "ISO-3166 alpha-2, e.g. US." }, "status": { "type": "string", "description": "active | inactive." }, "customer_type": { "type": "string", "description": "An Account Type key from this workspace's catalog (Admin \u2192 Account types), e.g. customer, prospect, vendor. Reads also include customer_type_name. Empty string clears it." }, "owner_id": { "type": "string", "description": "Must be an active member of the workspace." }, "parent_id": { "type": "string", "description": "Parent account." }, "notes": { "type": "string", "description": "" }, "custom_fields": { "type": "object", "description": "{key: value} \u2014 see GET /meta/custom-fields/." } } } } } } }, "delete": { "summary": "Archive (soft-delete) \u2014 the record is recoverable in the app, never destroyed.", "tags": [ "Accounts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/contacts/": { "get": { "summary": "List contacts.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated field names to return (lean responses).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 \u2014 incremental sync mode: returns records changed since then, oldest first, INCLUDING archived ones (archived: true).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "field or -field (whitelisted fields; uses offset paging via ?offset= instead of cursors; not combinable with updated_since).", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters on whitelisted fields: __gte __lte __gt __lt __contains __in (comma-separated). E.g. amount__gte=1000, created_at__lt=2026-01-01, status__in=open,won.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Name or email contains.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Exact email.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Linked to this account.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "1 to include archived.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "custom_fields,affiliations", "schema": { "type": "string" } } ] }, "post": { "summary": "Create a contact. Duplicate email returns 409 with the existing id.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "" }, "last_name": { "type": "string", "description": "" }, "title": { "type": "string", "description": "The person's title, e.g. Operations Manager (standard field; distinct from the per-company job_title on create)." }, "email": { "type": "string", "description": "Unique per workspace; duplicate returns 409." }, "phone": { "type": "string", "description": "" }, "mobile": { "type": "string", "description": "" }, "linkedin_url": { "type": "string", "description": "" }, "owner_id": { "type": "string", "description": "" }, "notes": { "type": "string", "description": "" }, "account_id": { "type": "string", "description": "Create only: links the contact to an account." }, "job_title": { "type": "string", "description": "Create only: title at that account." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } } }, "/contacts/upsert/": { "post": { "summary": "Create-or-update matched by email. Response carries created: true|false.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "" }, "last_name": { "type": "string", "description": "" }, "title": { "type": "string", "description": "The person's title, e.g. Operations Manager (standard field; distinct from the per-company job_title on create)." }, "email": { "type": "string", "description": "Unique per workspace; duplicate returns 409." }, "phone": { "type": "string", "description": "" }, "mobile": { "type": "string", "description": "" }, "linkedin_url": { "type": "string", "description": "" }, "owner_id": { "type": "string", "description": "" }, "notes": { "type": "string", "description": "" }, "account_id": { "type": "string", "description": "Create only: links the contact to an account." }, "job_title": { "type": "string", "description": "Create only: title at that account." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } } }, "/contacts/{id}/": { "get": { "summary": "Fetch one contact (custom fields + affiliations included).", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update a contact.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "" }, "last_name": { "type": "string", "description": "" }, "title": { "type": "string", "description": "The person's title, e.g. Operations Manager (standard field; distinct from the per-company job_title on create)." }, "email": { "type": "string", "description": "Unique per workspace; duplicate returns 409." }, "phone": { "type": "string", "description": "" }, "mobile": { "type": "string", "description": "" }, "linkedin_url": { "type": "string", "description": "" }, "owner_id": { "type": "string", "description": "" }, "notes": { "type": "string", "description": "" }, "account_id": { "type": "string", "description": "Create only: links the contact to an account." }, "job_title": { "type": "string", "description": "Create only: title at that account." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } }, "delete": { "summary": "Archive (soft-delete).", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/deals/": { "get": { "summary": "List deals.", "tags": [ "Deals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated field names to return (lean responses).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 \u2014 incremental sync mode: returns records changed since then, oldest first, INCLUDING archived ones (archived: true).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "field or -field (whitelisted fields; uses offset paging via ?offset= instead of cursors; not combinable with updated_since).", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters on whitelisted fields: __gte __lte __gt __lt __contains __in (comma-separated). E.g. amount__gte=1000, created_at__lt=2026-01-01, status__in=open,won.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Name contains.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "open | won | lost.", "schema": { "type": "string" } }, { "name": "pipeline_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "stage_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Primary account.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "1 to include archived.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "custom_fields", "schema": { "type": "string" } } ] }, "post": { "summary": "Create a deal (fires deal.created).", "tags": [ "Deals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "primary_account_id": { "type": "string", "description": "Required on create." }, "pipeline_id": { "type": "string", "description": "Defaults to the workspace's first pipeline." }, "stage_id": { "type": "string", "description": "Must belong to the pipeline. Changing it moves the deal (status/closed_at follow the stage type, automations fire)." }, "amount": { "type": "string", "description": "Decimal." }, "currency": { "type": "string", "description": "3-letter code." }, "owner_id": { "type": "string", "description": "" }, "lead_source_id": { "type": "string", "description": "" }, "source_detail": { "type": "string", "description": "" }, "expected_close_date": { "type": "string", "description": "YYYY-MM-DD." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } } }, "/deals/upsert/": { "post": { "summary": "Create-or-update matched by name + primary_account_id. Stage changes go through PATCH /deals/{id}/ so full move semantics apply.", "tags": [ "Deals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "primary_account_id": { "type": "string", "description": "Required on create." }, "pipeline_id": { "type": "string", "description": "Defaults to the workspace's first pipeline." }, "stage_id": { "type": "string", "description": "Must belong to the pipeline. Changing it moves the deal (status/closed_at follow the stage type, automations fire)." }, "amount": { "type": "string", "description": "Decimal." }, "currency": { "type": "string", "description": "3-letter code." }, "owner_id": { "type": "string", "description": "" }, "lead_source_id": { "type": "string", "description": "" }, "source_detail": { "type": "string", "description": "" }, "expected_close_date": { "type": "string", "description": "YYYY-MM-DD." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } } }, "/deals/{id}/": { "get": { "summary": "Fetch one deal.", "tags": [ "Deals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update a deal. Sending a new stage_id moves the deal exactly like dragging it on the board (status, closed_at, commissions, automations).", "tags": [ "Deals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "primary_account_id": { "type": "string", "description": "Required on create." }, "pipeline_id": { "type": "string", "description": "Defaults to the workspace's first pipeline." }, "stage_id": { "type": "string", "description": "Must belong to the pipeline. Changing it moves the deal (status/closed_at follow the stage type, automations fire)." }, "amount": { "type": "string", "description": "Decimal." }, "currency": { "type": "string", "description": "3-letter code." }, "owner_id": { "type": "string", "description": "" }, "lead_source_id": { "type": "string", "description": "" }, "source_detail": { "type": "string", "description": "" }, "expected_close_date": { "type": "string", "description": "YYYY-MM-DD." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } }, "delete": { "summary": "Archive (soft-delete).", "tags": [ "Deals" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/meetings/": { "get": { "summary": "List meetings (activities with the 'meeting' type).", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated field names to return (lean responses).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 \u2014 incremental sync mode: returns records changed since then, oldest first, INCLUDING archived ones (archived: true).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "field or -field (whitelisted fields; uses offset paging via ?offset= instead of cursors; not combinable with updated_since).", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters on whitelisted fields: __gte __lte __gt __lt __contains __in (comma-separated). E.g. amount__gte=1000, created_at__lt=2026-01-01, status__in=open,won.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "open | completed | cancelled.", "schema": { "type": "string" } }, { "name": "assigned_to_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "starts_after", "in": "query", "required": false, "description": "ISO 8601 \u2014 scheduled_at lower bound.", "schema": { "type": "string" } }, { "name": "starts_before", "in": "query", "required": false, "description": "ISO 8601 \u2014 scheduled_at upper bound.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "deal_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] }, "post": { "summary": "Create a meeting (subject + starts_at required; duration_min, assigned_to_id, account_ids/contact_ids/deal_ids/project_ids optional). Read/update items via /activities/{id}/. For a Microsoft-connected assignee, the meeting appears on their Outlook calendar on the next sync.", "tags": [ "Meetings" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } } } }, "/activities/": { "get": { "summary": "List activities (calls, tasks, meetings, notes\u2026).", "tags": [ "Activities" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated field names to return (lean responses).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 \u2014 incremental sync mode: returns records changed since then, oldest first, INCLUDING archived ones (archived: true).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "field or -field (whitelisted fields; uses offset paging via ?offset= instead of cursors; not combinable with updated_since).", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters on whitelisted fields: __gte __lte __gt __lt __contains __in (comma-separated). E.g. amount__gte=1000, created_at__lt=2026-01-01, status__in=open,won.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "open | completed | cancelled.", "schema": { "type": "string" } }, { "name": "assigned_to_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "type_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "deal_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "due_before", "in": "query", "required": false, "description": "ISO 8601.", "schema": { "type": "string" } }, { "name": "due_after", "in": "query", "required": false, "description": "ISO 8601.", "schema": { "type": "string" } } ] }, "post": { "summary": "Log an activity / create a task.", "tags": [ "Activities" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Required on create." }, "body": { "type": "string", "description": "" }, "type_id": { "type": "string", "description": "An activity type id (see /meta/options/); or pass `type` with the type key. Defaults to the first type." }, "direction": { "type": "string", "description": "inbound | outbound | internal." }, "status": { "type": "string", "description": "open | completed | cancelled." }, "scheduled_at": { "type": "string", "description": "ISO 8601." }, "due_at": { "type": "string", "description": "ISO 8601." }, "completed_at": { "type": "string", "description": "ISO 8601." }, "duration_min": { "type": "number", "description": "" }, "assigned_to_id": { "type": "string", "description": "" }, "account_ids": { "type": "string", "description": "Linked accounts." }, "contact_ids": { "type": "string", "description": "Linked contacts." }, "deal_ids": { "type": "string", "description": "Linked deals." }, "project_ids": { "type": "string", "description": "Linked projects." } } } } } } } }, "/activities/{id}/": { "get": { "summary": "Fetch one activity.", "tags": [ "Activities" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update an activity (marking status completed stamps completed_at).", "tags": [ "Activities" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Required on create." }, "body": { "type": "string", "description": "" }, "type_id": { "type": "string", "description": "An activity type id (see /meta/options/); or pass `type` with the type key. Defaults to the first type." }, "direction": { "type": "string", "description": "inbound | outbound | internal." }, "status": { "type": "string", "description": "open | completed | cancelled." }, "scheduled_at": { "type": "string", "description": "ISO 8601." }, "due_at": { "type": "string", "description": "ISO 8601." }, "completed_at": { "type": "string", "description": "ISO 8601." }, "duration_min": { "type": "number", "description": "" }, "assigned_to_id": { "type": "string", "description": "" }, "account_ids": { "type": "string", "description": "Linked accounts." }, "contact_ids": { "type": "string", "description": "Linked contacts." }, "deal_ids": { "type": "string", "description": "Linked deals." }, "project_ids": { "type": "string", "description": "Linked projects." } } } } } } } }, "/projects/": { "get": { "summary": "List projects.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (default 50, max 200).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Comma-separated field names to return (lean responses).", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO 8601 \u2014 incremental sync mode: returns records changed since then, oldest first, INCLUDING archived ones (archived: true).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "field or -field (whitelisted fields; uses offset paging via ?offset= instead of cursors; not combinable with updated_since).", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters on whitelisted fields: __gte __lte __gt __lt __contains __in (comma-separated). E.g. amount__gte=1000, created_at__lt=2026-01-01, status__in=open,won.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Name contains.", "schema": { "type": "string" } }, { "name": "stage_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "health", "in": "query", "required": false, "description": "on_track | at_risk | off_track.", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "required": false, "description": "low | medium | high.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "custom_fields", "schema": { "type": "string" } } ] }, "post": { "summary": "Create a project (fires project.created).", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "stage_id": { "type": "string", "description": "Project stage (see /meta/options/). Changing it fires project.stage_changed." }, "owner_id": { "type": "string", "description": "" }, "health": { "type": "string", "description": "on_track | at_risk | off_track." }, "priority": { "type": "string", "description": "low | medium | high." }, "start_date": { "type": "string", "description": "YYYY-MM-DD." }, "target_end_date": { "type": "string", "description": "YYYY-MM-DD." }, "actual_end_date": { "type": "string", "description": "YYYY-MM-DD." }, "account_ids": { "type": "string", "description": "Create only: linked accounts (first becomes primary)." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } } }, "/projects/{id}/": { "get": { "summary": "Fetch one project.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update a project.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "stage_id": { "type": "string", "description": "Project stage (see /meta/options/). Changing it fires project.stage_changed." }, "owner_id": { "type": "string", "description": "" }, "health": { "type": "string", "description": "on_track | at_risk | off_track." }, "priority": { "type": "string", "description": "low | medium | high." }, "start_date": { "type": "string", "description": "YYYY-MM-DD." }, "target_end_date": { "type": "string", "description": "YYYY-MM-DD." }, "actual_end_date": { "type": "string", "description": "YYYY-MM-DD." }, "account_ids": { "type": "string", "description": "Create only: linked accounts (first becomes primary)." }, "custom_fields": { "type": "object", "description": "{key: value}." } } } } } } } }, "/users/": { "get": { "summary": "List the workspace's active members (read-only).", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } } }, "/meta/custom-fields/": { "get": { "summary": "Custom field definitions per entity: id, key, label, type, options, read_only (formula/rollup/file values are read-only via API).", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } }, "post": { "summary": "Create a custom field definition (key auto-generated from the label; per-type options validation matches the in-app builder).", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "description": "account | contact | opportunity | project (plural slugs accepted)." }, "label": { "type": "string", "description": "Required." }, "type": { "type": "string", "description": "One of the 20 field types (text, number, select, multiselect, date, lookup, formula, rollup, file, \u2026)." }, "options": { "type": "string", "description": "Select/radio/multiselect choices; lookup target entity; formula expression; rollup config." } } } } } } } }, "/meta/custom-fields/{id}/": { "get": { "summary": "Fetch one custom field definition.", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update label, options, sort_order, or is_active. A field's TYPE cannot change \u2014 create a new field instead.", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "" }, "options": { "type": "string", "description": "Revalidated per type." }, "sort_order": { "type": "number", "description": "" }, "is_active": { "type": "number", "description": "" } } } } } } } }, "/meta/options/": { "get": { "summary": "Pipelines + stages, project stages, activity types, lead sources, and the available webhook event names.", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } } }, "/events/": { "get": { "summary": "The workspace's event stream \u2014 polling fallback for webhooks.", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "since", "in": "query", "required": false, "description": "ISO 8601 \u2014 events created after this.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Filter by event name.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] } }, "/search/": { "get": { "summary": "Cross-object substring search: account names/domains/phones, contact names/emails/phones, deal and project names. Grouped lean results.", "tags": [ "Search" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text (min 2 characters).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per type (default 10, max 25).", "schema": { "type": "string" } } ] } }, "/batch/{entity}/": { "post": { "summary": "Bulk ingest for accounts | contacts | deals: up to 100 records per request, mode create or upsert, per-row results \u2014 one bad row never aborts the rest.", "tags": [ "Batch & export" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "description": "create | upsert." }, "records": { "type": "array", "description": "Same shapes as the entity's POST body." } } } } } } } }, "/export/{entity}/": { "get": { "summary": "Bulk pull for accounts | contacts | deals | activities | projects. Requires the export scope; pages up to 1000; lower rate limit; every request audited as an export.", "tags": [ "Batch & export" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Up to 1000 (default 500).", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Sync mode, as on lists.", "schema": { "type": "string" } }, { "name": "__", "in": "query", "required": false, "description": "Operator filters, as on lists.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "custom_fields", "schema": { "type": "string" } } ] } }, "/webhooks/": { "get": { "summary": "List this workspace's webhook subscriptions (no secrets).", "tags": [ "Webhook management" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } }, "post": { "summary": "Create a subscription. The signing secret and the loop-skip token are returned ONCE, in this response only.", "tags": [ "Webhook management" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "target_url": { "type": "string", "description": "Your https endpoint." }, "events": { "type": "string", "description": "Event names; empty list = all events." } } } } } } } }, "/webhooks/{id}/": { "get": { "summary": "Fetch one subscription.", "tags": [ "Webhook management" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update name, target_url, events, or is_active (re-activating clears an auto-disable).", "tags": [ "Webhook management" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "target_url": { "type": "string", "description": "" }, "events": { "type": "string", "description": "" }, "is_active": { "type": "number", "description": "" } } } } } } }, "delete": { "summary": "Delete a subscription.", "tags": [ "Webhook management" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/webhooks/{id}/deliveries/": { "get": { "summary": "The subscription's 50 most recent deliveries.", "tags": [ "Webhook management" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/files/{entity}/{record_id}/": { "get": { "summary": "List a record's attachments (file-type custom fields): field key, filename, size, download URL. Entities: accounts | contacts | deals | projects.", "tags": [ "Files & notes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } } }, "/files/{entity}/{record_id}/{field_key}/": { "get": { "summary": "Download the attached file (Content-Disposition: attachment).", "tags": [ "Files & notes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } }, "post": { "summary": "Attach or replace: multipart/form-data with a 'file' field, 25 MB max, one file per field per record (mirrors the app).", "tags": [ "Files & notes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } } }, "delete": { "summary": "Remove the attached file.", "tags": [ "Files & notes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } } } }, "/notes/": { "get": { "summary": "List notes (the Note activity type, notes-shaped).", "tags": [ "Files & notes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "account_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "deal_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] }, "post": { "summary": "Attach a note to records without learning the activity model.", "tags": [ "Files & notes" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Required. The note text." }, "subject": { "type": "string", "description": "Optional; defaults to the first line of content." }, "account_id": { "type": "string", "description": "Link to an account (or account_ids list)." }, "contact_id": { "type": "string", "description": "Link to a contact (or contact_ids list)." }, "deal_id": { "type": "string", "description": "Link to a deal (or deal_ids list)." }, "project_id": { "type": "string", "description": "Link to a project (or project_ids list)." } } } } } } } }, "/quotes/": { "get": { "summary": "List quotes.", "tags": [ "Quotes & partners (read-only)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "draft | sent | accepted | declined.", "schema": { "type": "string" } }, { "name": "deal_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] } }, "/quotes/{id}/": { "get": { "summary": "Fetch one quote incl. line items and totals.", "tags": [ "Quotes & partners (read-only)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/partners/": { "get": { "summary": "List partners.", "tags": [ "Quotes & partners (read-only)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "pending | active | \u2026", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] } }, "/partners/{id}/": { "get": { "summary": "Fetch one partner.", "tags": [ "Quotes & partners (read-only)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/partner-leads/": { "get": { "summary": "List partner-registered leads.", "tags": [ "Quotes & partners (read-only)" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "pending | approved | rejected.", "schema": { "type": "string" } }, { "name": "partner_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] } }, "/history/{entity}/{id}/": { "get": { "summary": "A record's field-level change history, newest first: who changed what, old \u2192 new, and how (app, API, AI assistant, or automation). Entities: account, contact, deal, project.", "tags": [ "History & comments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 50, max 200.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Skip N rows.", "schema": { "type": "string" } } ] } }, "/comments/": { "get": { "summary": "List a record's comments (oldest first).", "tags": [ "History & comments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "entity", "in": "query", "required": false, "description": "account | contact | deal | project.", "schema": { "type": "string" } }, { "name": "record_id", "in": "query", "required": false, "description": "The record's UUID.", "schema": { "type": "string" } } ] }, "post": { "summary": "Add a comment. @username mentions notify the mentioned members; fires comment.created.", "tags": [ "History & comments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" }, "201": { "description": "Created" }, "409": { "description": "Duplicate / idempotency conflict" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entity": { "type": "string", "description": "account | contact | deal | project." }, "record_id": { "type": "string", "description": "" }, "body": { "type": "string", "description": "The comment text (max 5000 chars)." } } } } } } } }, "/comments/{id}/": { "patch": { "summary": "Edit a comment's body.", "tags": [ "History & comments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "" } } } } } } }, "delete": { "summary": "Soft-delete a comment. (Refused for OAuth connections, like every delete.)", "tags": [ "History & comments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Bad or missing API key" }, "403": { "description": "Missing scope / API disabled / IP blocked" }, "404": { "description": "Not found in this workspace" }, "429": { "description": "Rate limited (Retry-After header)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } } } }