{ "info": { "title": "Heffl Public API (Legacy v1)", "version": "1.0.0", "description": "Legacy Heffl REST API v1. Maintained for existing integrations. For new projects, use API v2 at https://docs.heffl.com/api-v2/introduction.", "contact": { "name": "Heffl Support", "url": "https://heffl.com/support", "email": "support@heffl.com" } }, "servers": [ { "url": "https://api.heffl.com/api/v1", "description": "Production API Server" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication. Get yours at app.heffl.com/settings/developers" } } }, "openapi": "3.1.1", "paths": { "/leads": { "post": { "operationId": "leads.create", "summary": "Create a new lead", "description": "Creates a new lead in your CRM. The lead will be assigned to the user associated with your API key.", "tags": [ "Leads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Lead's full name" }, "mobile": { "type": "string", "description": "Mobile phone number with country code" }, "secondaryMobile": { "type": "string", "description": "Secondary mobile phone number with country code" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "title": { "type": "string", "description": "Job title or position" }, "value": { "type": "number", "description": "Expected deal value or amount" }, "sourceId": { "type": "string", "description": "Lead source public ID" }, "stageId": { "type": "string", "description": "Lead stage public ID" }, "website": { "anyOf": [ {}, { "type": "null" } ], "description": "Company website URL" } }, "required": [ "name" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Lead public ID" }, "number": { "type": "string", "description": "Auto-generated lead number" }, "name": { "type": "string", "description": "Full name" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "mobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mobile phone number" }, "secondaryMobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary mobile" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Expected value" }, "archived": { "type": "boolean", "description": "Whether the lead is archived" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead source public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the lead was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "archived", "createdAt" ] } } } } } }, "get": { "operationId": "leads.list", "summary": "List leads", "description": "Returns a paginated list of leads. Supports search and filtering.", "tags": [ "Leads" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items to return (max 100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "default": "", "description": "Search by name, email, mobile, or website" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "archived", "in": "query", "schema": { "type": "boolean", "description": "Filter by archived status" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "stageId", "in": "query", "schema": { "type": "string", "description": "Filter by stage public ID" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Lead public ID" }, "number": { "type": "string", "description": "Auto-generated lead number" }, "name": { "type": "string", "description": "Full name" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "mobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mobile phone number" }, "secondaryMobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary mobile" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Expected value" }, "archived": { "type": "boolean", "description": "Whether the lead is archived" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead source public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the lead was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "archived", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/leads/{id}": { "get": { "operationId": "leads.get", "summary": "Get a lead", "description": "Returns a single lead by its public ID.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Lead public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Lead public ID" }, "number": { "type": "string", "description": "Auto-generated lead number" }, "name": { "type": "string", "description": "Full name" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "mobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mobile phone number" }, "secondaryMobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary mobile" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Expected value" }, "archived": { "type": "boolean", "description": "Whether the lead is archived" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead source public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the lead was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "archived", "createdAt" ] } } } } } }, "patch": { "operationId": "leads.update", "summary": "Update a lead", "description": "Updates an existing lead in your CRM. Only provided fields will be updated.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Lead public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Lead's full name" }, "mobile": { "type": "string", "description": "Mobile phone number with country code" }, "secondaryMobile": { "type": "string", "description": "Secondary mobile phone number with country code" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "title": { "type": "string", "description": "Job title or position" }, "value": { "type": "number", "description": "Expected deal value or amount" }, "sourceId": { "type": "string", "description": "Lead source public ID" }, "stageId": { "type": "string", "description": "Lead stage public ID" }, "website": { "anyOf": [ {}, { "type": "null" } ], "description": "Company website URL" } }, "required": [], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Lead public ID" }, "number": { "type": "string", "description": "Auto-generated lead number" }, "name": { "type": "string", "description": "Full name" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "mobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mobile phone number" }, "secondaryMobile": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Secondary mobile" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Expected value" }, "archived": { "type": "boolean", "description": "Whether the lead is archived" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead source public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the lead was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "archived", "createdAt" ] } } } } } }, "delete": { "operationId": "leads.delete", "summary": "Delete a lead", "description": "Permanently deletes a lead. This action cannot be undone.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Lead public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/clients": { "post": { "operationId": "clients.create", "summary": "Create a new client", "description": "Creates a new client/company in your CRM. The client will be assigned to the user associated with your API key.", "tags": [ "Clients" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "company", "contact" ], "default": "company", "description": "Client type: company for companies, contact for contacts" }, "name": { "type": "string", "description": "Company name (required for companies, optional for contacts)" }, "firstName": { "type": "string", "description": "First name (required for contacts)" }, "lastName": { "type": "string", "description": "Last name (optional for contacts)" }, "salutation": { "type": "string", "description": "Title (Mr., Mrs., Dr., etc.)" }, "phone": { "type": "string", "description": "Phone number with country code" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Email address" }, "jobTitle": { "type": "string", "description": "Job title or position" }, "website": { "anyOf": [ {}, { "type": "null" } ], "description": "Company website URL" }, "taxNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tax ID or VAT number" }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address" }, "landmark": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Nearby landmark" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (2 letters, e.g., US, GB)" }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal code or ZIP code" } } }, { "type": "null" } ], "description": "Billing address details" }, "openingBalance": { "type": "number", "minimum": 0, "default": 0, "description": "Starting account balance (defaults to 0)" }, "primaryContact": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "phone": { "type": "string" }, "salutation": { "type": "string" }, "jobTitle": { "type": "string" } }, "required": [ "firstName" ], "additionalProperties": {}, "description": "Optional primary contact for company records" } }, "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Client public ID" }, "number": { "type": "string", "description": "Auto-generated client number" }, "name": { "type": "string", "description": "Client name" }, "type": { "enum": [ "company", "contact" ], "description": "Client type" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name (for contacts)" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name (for contacts)" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the client was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "type", "createdAt" ] } } } } } }, "get": { "operationId": "clients.list", "summary": "List clients", "description": "Returns a paginated list of clients. Supports search and type filtering.", "tags": [ "Clients" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items to return (max 100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "default": "", "description": "Search by name, email, or phone" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "type", "in": "query", "schema": { "enum": [ "company", "contact" ], "description": "Filter by client type" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Client public ID" }, "number": { "type": "string", "description": "Auto-generated client number" }, "name": { "type": "string", "description": "Client name" }, "type": { "enum": [ "company", "contact" ], "description": "Client type" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name (for contacts)" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name (for contacts)" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the client was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "type", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/clients/{id}": { "get": { "operationId": "clients.get", "summary": "Get a client", "description": "Returns a single client by its public ID.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Client public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Client public ID" }, "number": { "type": "string", "description": "Auto-generated client number" }, "name": { "type": "string", "description": "Client name" }, "type": { "enum": [ "company", "contact" ], "description": "Client type" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name (for contacts)" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name (for contacts)" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the client was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "type", "createdAt" ] } } } } } }, "patch": { "operationId": "clients.update", "summary": "Update a client", "description": "Updates an existing client/company in your CRM. Only provided fields will be updated.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Client public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "enum": [ "company", "contact" ], "description": "Client type: company for companies, contact for contacts" }, "name": { "type": "string", "description": "Company name (required for companies, optional for contacts)" }, "firstName": { "type": "string", "description": "First name (required for contacts, optional for companies)" }, "lastName": { "type": "string", "description": "Last name (optional for contacts)" }, "salutation": { "type": "string", "description": "Title (Mr., Mrs., Dr., etc.)" }, "phone": { "type": "string", "description": "Phone number with country code" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Email address" }, "jobTitle": { "type": "string", "description": "Job title or position" }, "website": { "anyOf": [ {}, { "type": "null" } ], "description": "Company website URL" }, "taxNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tax ID or VAT number" }, "billingAddress": { "anyOf": [ { "type": "object", "properties": { "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Street address" }, "landmark": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Nearby landmark" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code (2 letters, e.g., US, GB)" }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Postal code or ZIP code" } } }, { "type": "null" } ], "description": "Billing address details" }, "primaryContact": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string" }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "phone": { "type": "string" }, "salutation": { "type": "string" }, "jobTitle": { "type": "string" } }, "required": [ "firstName" ], "additionalProperties": {}, "description": "Optional primary contact for company records" } }, "required": [], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Client public ID" }, "number": { "type": "string", "description": "Auto-generated client number" }, "name": { "type": "string", "description": "Client name" }, "type": { "enum": [ "company", "contact" ], "description": "Client type" }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name (for contacts)" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name (for contacts)" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Website URL" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client stage public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the client was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "name", "type", "createdAt" ] } } } } } }, "delete": { "operationId": "clients.delete", "summary": "Delete a client", "description": "Permanently deletes a client. Will fail if the client has associated deals, invoices, or quotations.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Client public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/deals": { "post": { "operationId": "deals.create", "summary": "Create a new deal", "description": "Creates a new deal in your CRM pipeline.", "tags": [ "Deals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Deal title" }, "pipelineId": { "type": "string", "description": "Pipeline public ID" }, "stageId": { "type": "string", "description": "Pipeline stage public ID" }, "clientId": { "type": "string", "description": "Client public ID (required)" }, "leadId": { "type": "string", "description": "Lead public ID" }, "sourceId": { "type": "string", "description": "Deal source public ID" }, "price": { "type": "number", "description": "Deal value/price" }, "expectedCloseDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Expected close date" }, "priority": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Deal priority" } }, "required": [ "title", "pipelineId", "stageId", "clientId" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Deal public ID" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Auto-generated deal number" }, "title": { "type": "string", "description": "Deal title" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Deal price/value" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal status" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal priority" }, "expectedCloseDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Expected close date" }, "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client public ID" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline stage public ID" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal source public ID" }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the deal was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "title", "createdAt" ] } } } } } }, "get": { "operationId": "deals.list", "summary": "List deals", "description": "Returns a paginated list of deals. Supports search and filtering.", "tags": [ "Deals" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items to return (max 100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "default": "", "description": "Search by deal title" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "pipelineId", "in": "query", "schema": { "type": "string", "description": "Filter by pipeline public ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "stageId", "in": "query", "schema": { "type": "string", "description": "Filter by stage public ID" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "ACTIVE", "WON", "LOST" ], "description": "Filter by deal status (ACTIVE, WON, LOST)" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Deal public ID" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Auto-generated deal number" }, "title": { "type": "string", "description": "Deal title" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Deal price/value" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal status" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal priority" }, "expectedCloseDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Expected close date" }, "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client public ID" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline stage public ID" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal source public ID" }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the deal was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "title", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/deals/{id}": { "get": { "operationId": "deals.get", "summary": "Get a deal", "description": "Returns a single deal by its public ID.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Deal public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Deal public ID" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Auto-generated deal number" }, "title": { "type": "string", "description": "Deal title" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Deal price/value" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal status" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal priority" }, "expectedCloseDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Expected close date" }, "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client public ID" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline stage public ID" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal source public ID" }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the deal was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "title", "createdAt" ] } } } } } }, "patch": { "operationId": "deals.update", "summary": "Update a deal", "description": "Updates an existing deal. Only provided fields will be updated.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Deal public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Deal title" }, "price": { "type": "number", "description": "Deal value/price" }, "stageId": { "type": "string", "description": "Pipeline stage public ID" }, "status": { "enum": [ "ACTIVE", "WON", "LOST" ], "description": "Deal status (ACTIVE, WON, LOST)" }, "priority": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Deal priority" }, "sourceId": { "type": "string", "description": "Deal source public ID" }, "expectedCloseDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Expected close date" } }, "required": [], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Deal public ID" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Auto-generated deal number" }, "title": { "type": "string", "description": "Deal title" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Deal price/value" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal status" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal priority" }, "expectedCloseDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Expected close date" }, "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client public ID" }, "pipelineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline public ID" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pipeline stage public ID" }, "sourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deal source public ID" }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lead public ID" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the deal was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "title", "createdAt" ] } } } } } }, "delete": { "operationId": "deals.delete", "summary": "Delete a deal", "description": "Permanently deletes a deal. Will fail if the deal has associated quotations, projects, or documents.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Deal public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/tasks": { "post": { "operationId": "tasks.create", "summary": "Create a new task", "description": "Creates a new task. The task will be assigned to the user associated with your API key.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Task title" }, "description": { "type": "string", "description": "Task description" }, "type": { "enum": [ "call", "todo", "meeting" ], "default": "todo", "description": "Task type" }, "status": { "enum": [ "OPEN", "IN_PROGRESS", "ON_HOLD", "COMPLETED", "CANCELLED" ], "default": "OPEN", "description": "Task status" }, "dueDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Due date for the task" }, "startDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Start date for the task" }, "priority": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Task priority" }, "entity": { "enum": [ "leads", "deals", "clients" ], "description": "Entity type to associate the task with" }, "entityId": { "type": "string", "description": "Public ID of the entity to associate the task with" } }, "required": [ "title" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task public ID" }, "number": { "type": "string", "description": "Auto-generated task number" }, "title": { "type": "string", "description": "Task title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task description" }, "status": { "type": "string", "description": "Task status" }, "type": { "type": "string", "description": "Task type" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task priority" }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Due date" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Start date" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the task was created" } }, "required": [ "id", "number", "title", "status", "type", "createdAt" ] } } } } } }, "get": { "operationId": "tasks.list", "summary": "List tasks", "description": "Returns a paginated list of tasks. Supports search and filtering.", "tags": [ "Tasks" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items to return (max 100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "default": "", "description": "Search by task title" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "status", "in": "query", "schema": { "enum": [ "OPEN", "IN_PROGRESS", "ON_HOLD", "COMPLETED", "CANCELLED" ], "description": "Filter by status" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "type", "in": "query", "schema": { "enum": [ "call", "todo", "meeting" ], "description": "Filter by task type" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true }, { "name": "priority", "in": "query", "schema": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Filter by priority" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Task public ID" }, "number": { "type": "string", "description": "Auto-generated task number" }, "title": { "type": "string", "description": "Task title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task description" }, "status": { "type": "string", "description": "Task status" }, "type": { "type": "string", "description": "Task type" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task priority" }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Due date" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Start date" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the task was created" } }, "required": [ "id", "number", "title", "status", "type", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/tasks/{id}": { "get": { "operationId": "tasks.get", "summary": "Get a task", "description": "Returns a single task by its public ID.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task public ID" }, "number": { "type": "string", "description": "Auto-generated task number" }, "title": { "type": "string", "description": "Task title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task description" }, "status": { "type": "string", "description": "Task status" }, "type": { "type": "string", "description": "Task type" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task priority" }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Due date" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Start date" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the task was created" } }, "required": [ "id", "number", "title", "status", "type", "createdAt" ] } } } } } }, "patch": { "operationId": "tasks.update", "summary": "Update a task", "description": "Updates an existing task. Only provided fields will be updated.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Task title" }, "description": { "type": "string", "description": "Task description" }, "status": { "enum": [ "OPEN", "IN_PROGRESS", "ON_HOLD", "COMPLETED", "CANCELLED" ], "description": "Task status" }, "priority": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Task priority" }, "dueDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Due date" }, "startDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Start date" } }, "required": [], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task public ID" }, "number": { "type": "string", "description": "Auto-generated task number" }, "title": { "type": "string", "description": "Task title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task description" }, "status": { "type": "string", "description": "Task status" }, "type": { "type": "string", "description": "Task type" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task priority" }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Due date" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time", "x-native-type": "date" }, { "type": "null" } ], "description": "Start date" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the task was created" } }, "required": [ "id", "number", "title", "status", "type", "createdAt" ] } } } } } }, "delete": { "operationId": "tasks.delete", "summary": "Delete a task", "description": "Permanently deletes a task.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/tags": { "get": { "operationId": "legacy.tags.list", "summary": "List tags", "description": "Returns all tags for your team, optionally filtered by type.", "tags": [ "Reference Data" ], "parameters": [ { "name": "type", "in": "query", "schema": { "enum": [ "leads", "deals", "clients", "contacts", "projects", "project_tasks", "invoices", "quotations", "schedules", "fs_jobs", "purchase_orders", "vendors", "bills" ], "description": "Filter by tag type" }, "style": "deepObject", "explode": true, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Tag ID" }, "name": { "type": "string", "description": "Tag name" }, "color": { "type": "string", "description": "Tag color" }, "type": { "type": "string", "description": "Tag type" } }, "required": [ "id", "name", "color", "type" ] } } }, "required": [ "items" ] } } } } } } }, "/pipelines": { "get": { "operationId": "pipelines.list", "summary": "List deal pipelines", "description": "Returns all deal pipelines with their stages.", "tags": [ "Reference Data" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Pipeline public ID" }, "name": { "type": "string", "description": "Pipeline name" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stage public ID" }, "name": { "type": "string", "description": "Stage name" }, "position": { "type": "number", "description": "Stage position" }, "probability": { "type": "number", "description": "Win probability %" } }, "required": [ "id", "name", "position", "probability" ] } } }, "required": [ "id", "name", "stages" ] } } }, "required": [ "items" ] } } } } } } }, "/pipelines/{id}": { "get": { "operationId": "pipelines.get", "summary": "Get a pipeline", "description": "Returns a single deal pipeline with its stages.", "tags": [ "Reference Data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Pipeline public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "number" }, "probability": { "type": "number" } }, "required": [ "id", "name", "position", "probability" ] } } }, "required": [ "id", "name", "stages" ] } } } } } } }, "/products": { "get": { "operationId": "legacy.products.list", "summary": "List products", "description": "Returns a paginated list of products.", "tags": [ "Reference Data" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items to return (max 100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "default": "", "description": "Search by product name" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Product public ID" }, "name": { "type": "string", "description": "Product name" }, "price": { "type": "number", "description": "Product price" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Product description" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SKU code" }, "type": { "type": "string", "description": "Product type" }, "isActive": { "type": "boolean", "description": "Whether product is active" } }, "required": [ "id", "name", "price", "type", "isActive" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/products/{id}": { "get": { "operationId": "legacy.products.get", "summary": "Get a product", "description": "Returns a single product by public ID.", "tags": [ "Reference Data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Product public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "id", "name", "price", "type", "isActive" ] } } } } } } }, "/leads/stages": { "get": { "operationId": "leadStages.list", "summary": "List lead stages", "description": "Returns all lead stages ordered by position.", "tags": [ "Reference Data" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stage public ID" }, "label": { "type": "string", "description": "Stage label" }, "type": { "type": "string", "description": "Stage type" }, "position": { "type": "number", "description": "Stage position" } }, "required": [ "id", "label", "type", "position" ] } } }, "required": [ "items" ] } } } } } } }, "/leads/sources": { "get": { "operationId": "leadSources.list", "summary": "List lead sources", "description": "Returns all CRM sources (lead sources).", "tags": [ "Reference Data" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Source public ID" }, "name": { "type": "string", "description": "Source name" } }, "required": [ "id", "name" ] } } }, "required": [ "items" ] } } } } } } }, "/invoices": { "post": { "operationId": "invoices.create", "summary": "Create a new invoice", "description": "Creates a new invoice with line items. Returns the invoice with calculated totals.", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "description": "Client public ID (required)" }, "date": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Invoice date" }, "dueDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Due date" }, "lineItems": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Line item name" }, "productId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Product public ID (optional)" }, "quantity": { "type": "number", "minimum": 0, "default": 0, "description": "Quantity" }, "price": { "type": "number", "minimum": 0, "default": 0, "description": "Unit price" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Line item description" }, "taxRateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tax rate public ID" }, "discount": { "type": "number", "minimum": 0, "default": 0, "description": "Discount value" }, "discountType": { "enum": [ "fixed", "percent" ], "default": "fixed", "description": "Discount type: fixed amount or percent" }, "buyPrice": { "type": "number", "minimum": 0, "default": 0, "description": "Cost/buy price" } }, "required": [ "name" ] }, "description": "Invoice line items" }, "isInclusiveTax": { "type": "boolean", "default": false, "description": "Whether prices include tax" }, "status": { "enum": [ "DRAFT", "SENT" ], "default": "DRAFT", "description": "Invoice status (DRAFT or SENT)" }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact public ID" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invoice subject" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invoice notes" }, "salesPersonId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sales person user public ID" }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Document template public ID. If not provided, uses the team's default invoice template." }, "tags": { "type": "array", "items": { "type": "number" }, "default": [], "description": "Tag IDs to associate with the invoice" } }, "required": [ "clientId", "date", "dueDate", "lineItems" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Invoice public ID" }, "number": { "type": "string", "description": "Auto-generated invoice number" }, "date": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Invoice date" }, "dueDate": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "Invoice due date" }, "status": { "type": "string", "description": "Invoice status" }, "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client public ID" }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Contact public ID" }, "currency": { "type": "string", "description": "Currency code" }, "isInclusiveTax": { "type": "boolean", "description": "Whether prices include tax" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invoice subject" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invoice notes" }, "salesPersonId": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Sales person user ID" }, "subTotal": { "type": "number", "description": "Subtotal before tax" }, "taxTotal": { "type": "number", "description": "Total tax amount" }, "discountTotal": { "type": "number", "description": "Total discount amount" }, "total": { "type": "number", "description": "Grand total" }, "pendingTotal": { "type": "number", "description": "Amount pending" }, "paidTotal": { "type": "number", "description": "Total amount paid" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Line item name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Line item description" }, "productId": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Product ID" }, "quantity": { "type": "number", "description": "Quantity" }, "price": { "type": "number", "description": "Unit price" }, "tax": { "type": "number", "description": "Tax percentage" }, "discount": { "type": "number", "description": "Discount value" }, "discountType": { "enum": [ "fixed", "percent" ], "description": "Discount type" }, "buyPrice": { "type": "number", "description": "Cost/buy price" }, "viewType": { "enum": [ "LINE_ITEM", "HEADING" ], "description": "Line item type" }, "amount": { "type": "number", "description": "Line total after discount and tax" }, "taxAmount": { "type": "number", "description": "Tax amount for this line" }, "discountAmount": { "type": "number", "description": "Discount amount for this line" } }, "required": [ "name", "quantity", "price", "tax", "discount", "discountType", "buyPrice", "viewType", "amount", "taxAmount", "discountAmount" ] }, "description": "Invoice line items" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date", "description": "When the invoice was created" }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Custom field values" } }, "required": [ "id", "number", "date", "dueDate", "status", "currency", "isInclusiveTax", "subTotal", "taxTotal", "discountTotal", "total", "pendingTotal", "paidTotal", "lineItems", "createdAt" ] } } } } } } }, "/webhooks": { "post": { "operationId": "webhooks.subscribe", "summary": "Subscribe to webhook events", "description": "Creates a webhook endpoint that receives HTTP POST notifications when specified events occur.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Webhook name (e.g. 'Zapier: New Lead')" }, "url": { "type": "string", "format": "uri", "description": "URL to receive webhook POST requests" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Events to subscribe to" } }, "required": [ "name", "url", "events" ], "additionalProperties": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint public ID" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "secret": { "type": "string", "description": "Signing secret (one-time reveal)" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date" } }, "required": [ "id", "name", "url", "events", "status", "secret", "createdAt" ] } } } } } }, "get": { "operationId": "webhooks.list", "summary": "List webhook subscriptions", "description": "Returns webhook endpoints for your team.", "tags": [ "Webhooks" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items to return (max 100)" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "search", "in": "query", "schema": { "type": "string", "default": "", "description": "Search by webhook name or URL" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date" } }, "required": [ "id", "name", "url", "events", "status", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ] } } } } } } }, "/webhooks/{id}": { "get": { "operationId": "webhooks.get", "summary": "Get webhook subscription", "description": "Returns a single webhook endpoint.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Webhook endpoint public ID" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "x-native-type": "date" } }, "required": [ "id", "name", "url", "events", "status", "createdAt" ] } } } } } }, "delete": { "operationId": "webhooks.unsubscribe", "summary": "Unsubscribe from webhook events", "description": "Deletes a webhook endpoint and stops receiving events.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Webhook endpoint public ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/users": { "get": { "operationId": "legacy.users.list", "summary": "List users", "description": "Returns a paginated list of users who belong to the API key's team.", "tags": [ "Users" ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Cursor for pagination. Pass the previous response nextCursor value to fetch the next page." }, { "in": "query", "name": "limit", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items to return (max 100)" }, { "in": "query", "name": "search", "schema": { "type": "string", "default": "" }, "description": "Search by first name, last name, or email" }, { "in": "query", "name": "active", "schema": { "type": "boolean" }, "description": "Filter by active team membership status" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "User public ID" }, "firstName": { "type": "string", "description": "First name" }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name" }, "email": { "type": "string", "description": "Email address" }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Job title" }, "role": { "type": "string", "description": "Team role" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the user was created" } }, "required": [ "id", "firstName", "email", "role", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page. Null if there are no more results." }, "hasMore": { "type": "boolean", "description": "Whether additional results are available" } }, "required": [ "items", "hasMore" ], "additionalProperties": false } } } } } } } } }