{ "openapi": "3.1.0", "info": { "title": "Paidnice Public API", "version": "1.0.0", "description": "The public REST API for Paidnice. All endpoints require an API key passed as a bearer token in the Authorization header.\n\nFor full rate limit behavior and best practices, see the [Rate Limiting Guide](./rate-limits.html)." }, "externalDocs": { "description": "Rate Limiting Guide", "url": "./rate-limits.html" }, "servers": [ { "url": "https://api.paidnice.com/rest/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your Paidnice API key, passed as a bearer token. Tokens carry read and/or write scopes: GET endpoints need read, all other endpoints need write." } }, "schemas": { "Contact": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "Acme Ltd" }, "accountingSystemId": { "type": "string", "example": "123" }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "accountNumber": { "type": "string" }, "smsOptedOut": { "type": "boolean" }, "contactPersons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000123" }, "isPrimary": { "type": "boolean" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "mobileNumber": { "type": "string" }, "mobileNumberCountryCode": { "type": "string" }, "defaultNumber": { "type": "string" }, "defaultNumberCountryCode": { "type": "string" }, "includeInNotifications": { "type": "boolean" }, "sourceType": { "type": "string", "enum": [ "imported", "local" ] } }, "required": [ "id", "isPrimary", "includeInNotifications", "sourceType" ] } }, "groupId": { "type": "integer", "example": 42 }, "groupTitle": { "type": "string", "example": "Default Group" } }, "required": [ "id", "name", "accountingSystemId", "status", "smsOptedOut", "contactPersons", "groupId", "groupTitle" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "unauthorised" }, "message": { "type": "string", "example": "Missing or invalid API key" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "UpdateContactPersonsRequest": { "type": "object", "properties": { "persons": { "type": "array", "items": { "$ref": "#/components/schemas/ContactPersonInput" }, "minItems": 1, "maxItems": 100 } }, "required": [ "persons" ] }, "ContactPersonInput": { "type": "object", "properties": { "id": { "type": "string" }, "isPrimary": { "type": "boolean" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "mobileNumber": { "type": "string" }, "mobileCountryCode": { "type": "string" }, "defaultNumber": { "type": "string" }, "defaultCountryCode": { "type": "string" }, "includeInNotifications": { "type": "boolean" }, "sourceType": { "type": "string", "enum": [ "imported", "local" ] } }, "required": [ "isPrimary" ] }, "InboundSms": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "fromNumber": { "type": "string", "example": "+61400000000" }, "toNumber": { "type": "string" }, "body": { "type": "string", "example": "Can we pay this on Friday?" }, "contactId": { "type": "integer" }, "matchedActionId": { "type": "string" }, "createdAt": { "type": "string", "example": "2026-06-16T08:00:00.000Z" } }, "required": [ "id", "fromNumber", "body", "createdAt" ] }, "InboundEmail": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-0000-0000-000000000123" }, "from": { "type": "string", "example": "customer@example.com" }, "to": { "type": "string", "example": "inbound@paidnice.com" }, "cc": { "type": "string", "example": "accounts@example.com" }, "subject": { "type": "string" }, "extractedReplyText": { "type": "string", "example": "Paid half today" }, "attachmentCount": { "type": "integer", "example": 2 }, "createdAt": { "type": "string", "example": "2026-06-16T08:00:00.000Z" }, "contactId": { "type": "integer" }, "contactName": { "type": "string" } }, "required": [ "id", "from", "to", "attachmentCount", "createdAt" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-0000-0000-000000000123" }, "accountingSystemId": { "type": "string", "example": "INV-123" }, "status": { "type": "string", "example": "AUTHORISED" }, "number": { "type": "string", "example": "INV-000123" }, "reference": { "type": "string", "example": "PO-456" }, "currency": { "type": "string", "example": "USD" }, "frozen": { "type": "boolean", "example": false }, "sentToCustomer": { "type": "boolean", "example": true }, "dueAmount": { "type": "number", "example": 12.5 }, "totalAmount": { "type": "number", "example": 50 }, "subtotalAmount": { "type": "number", "example": 45 }, "taxAmount": { "type": "number", "example": 5 }, "paidAmount": { "type": "number", "example": 10 }, "discountAmount": { "type": "number", "example": 2 }, "creditedAmount": { "type": "number", "example": 3 }, "depositAmount": { "type": "number", "example": 0 }, "exchangeRate": { "type": "number", "example": 1 }, "accountingSystemExchangeRate": { "type": "number", "example": 1.25 }, "issueDate": { "type": "string", "example": "2026-06-01" }, "dueDate": { "type": "string", "example": "2026-06-15" }, "lastSyncedDate": { "type": "string", "example": "2026-06-16T08:00:00.000Z" }, "portalUrl": { "type": "string", "example": "https://portal.paidnice.com/i/abc123" }, "accountingSystemOnlineUrl": { "type": "string" }, "contactId": { "type": "integer" }, "contactName": { "type": "string" } }, "required": [ "id", "accountingSystemId", "status", "currency", "frozen", "sentToCustomer", "dueAmount", "totalAmount", "subtotalAmount", "taxAmount", "paidAmount", "discountAmount", "creditedAmount", "depositAmount", "exchangeRate", "issueDate", "dueDate", "portalUrl", "contactId" ] }, "Note": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "createdAt": { "type": "string", "example": "2026-06-16T08:00:00.000Z" }, "content": { "type": "string", "example": "Called, promised to pay Friday" }, "authorName": { "type": [ "string", "null" ], "example": "Sarah Jones" }, "contactId": { "type": "integer", "example": 123 }, "invoiceId": { "type": [ "string", "null" ], "example": "00000000-0000-0000-0000-000000000123" } }, "required": [ "id", "createdAt", "content", "authorName", "contactId", "invoiceId" ] }, "Organisation": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-0000-0000-000000000001" }, "legalName": { "type": "string", "example": "Acme Pty Ltd" }, "displayName": { "type": "string" }, "connected": { "type": "boolean" }, "accountingSystemId": { "type": "string", "description": "The organisation's id in the connected accounting system" }, "accountingSystemType": { "type": "string", "enum": [ "XERO", "QBO" ] } }, "required": [ "id", "legalName", "connected", "accountingSystemId", "accountingSystemType" ] }, "OrganisationSummary": { "type": "object", "properties": { "outstandingTotal": { "type": "number", "example": 12500.5 }, "overdueTotal": { "type": "number", "example": 4200 }, "unpaidInvoiceCount": { "type": "integer", "example": 42 }, "overdueInvoiceCount": { "type": "integer", "example": 12 }, "contactCount": { "type": "integer", "description": "Number of active contacts. Archived contacts are not counted.", "example": 310 }, "currency": { "type": "string", "example": "USD" } }, "required": [ "outstandingTotal", "overdueTotal", "unpaidInvoiceCount", "overdueInvoiceCount", "contactCount", "currency" ] } }, "parameters": {} }, "paths": { "/contacts": { "get": { "operationId": "list_contacts", "summary": "List contacts", "description": "Returns contacts for the authenticated organisation, most recently created first. Use search to find a contact by name, account number or contact person email, then use its id with the other contact and invoice operations.", "tags": [ "Contact" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of records to return", "example": 10 }, "required": false, "description": "Maximum number of records to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record." }, "required": false, "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record.", "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Case insensitive partial match on the contact name, account number or a contact person's email", "example": "acme" }, "required": false, "description": "Case insensitive partial match on the contact name, account number or a contact person's email", "name": "search", "in": "query" } ], "responses": { "200": { "description": "A page of contacts", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": "string", "description": "Pass as the cursor query parameter to fetch the next page. Absent on the last page." } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/contact/{id}": { "get": { "operationId": "get_contact", "summary": "Get contact", "description": "Returns a contact by id.", "tags": [ "Contact" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "example": 123 }, "required": false, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The contact", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The contact could not be found", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/contact/{id}/contact-persons": { "put": { "operationId": "update_contact_persons", "summary": "Update contact persons", "description": "Replaces the set of persons on a contact. Send the full desired list of persons; the change is pushed to the accounting system and the contact is then re-synced. Exactly one person must be marked as primary. The primary person is imported, while additional persons may be local depending on accounting-system rules.", "tags": [ "Contact" ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "example": 123 }, "required": false, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactPersonsRequest" } } } }, "responses": { "200": { "description": "The updated contact", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The contact could not be found", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/inbound/sms": { "get": { "operationId": "list_inbound_sms", "summary": "List inbound SMS", "description": "Returns inbound SMS messages for the authenticated organisation, most recent first.", "tags": [ "Inbound" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of records to return", "example": 10 }, "required": false, "description": "Maximum number of records to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record." }, "required": false, "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A page of inbound SMS messages", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundSms" } }, "nextCursor": { "type": "string", "description": "Pass as the cursor query parameter to fetch the next page. Absent on the last page." } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/inbound/email": { "get": { "operationId": "list_inbound_email", "summary": "List inbound email", "description": "Returns inbound emails for the authenticated organisation, most recent first.", "tags": [ "Inbound" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of records to return", "example": 10 }, "required": false, "description": "Maximum number of records to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record." }, "required": false, "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "A page of inbound emails", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboundEmail" } }, "nextCursor": { "type": "string", "description": "Pass as the cursor query parameter to fetch the next page. Absent on the last page." } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/invoices": { "get": { "operationId": "list_invoices", "summary": "List invoices", "description": "Returns invoices for the authenticated organisation ordered by due date, earliest first. Defaults to unpaid invoices; filter by contact, status or due date range. Deleted invoices are never returned.", "tags": [ "Invoice" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of records to return", "example": 10 }, "required": false, "description": "Maximum number of records to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record." }, "required": false, "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record.", "name": "cursor", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "description": "Only invoices for this contact", "example": 123 }, "required": false, "description": "Only invoices for this contact", "name": "contactId", "in": "query" }, { "schema": { "type": "string", "enum": [ "unpaid", "overdue", "paid" ], "default": "unpaid", "description": "unpaid: approved invoices with a balance owing. overdue: unpaid invoices whose due date has passed in the organisation's timezone. paid: fully paid invoices." }, "required": false, "description": "unpaid: approved invoices with a balance owing. overdue: unpaid invoices whose due date has passed in the organisation's timezone. paid: fully paid invoices.", "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Only invoices due on or before this date (YYYY-MM-DD)", "example": "2026-06-30" }, "required": false, "description": "Only invoices due on or before this date (YYYY-MM-DD)", "name": "dueBefore", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Only invoices due on or after this date (YYYY-MM-DD)", "example": "2026-06-01" }, "required": false, "description": "Only invoices due on or after this date (YYYY-MM-DD)", "name": "dueAfter", "in": "query" } ], "responses": { "200": { "description": "A page of invoices", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "type": "string", "description": "Pass as the cursor query parameter to fetch the next page. Absent on the last page." } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/invoice/{id}": { "get": { "operationId": "get_invoice", "summary": "Get invoice", "description": "Returns an invoice by internal id for the authenticated organisation.", "tags": [ "Invoice" ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-0000-0000-000000000123" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The invoice", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The invoice could not be found", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/notes": { "get": { "operationId": "list_notes", "summary": "List notes", "description": "Returns notes written on a contact or an invoice, newest first. Pass exactly one of contactId or invoiceId. Notes on a contact include the notes on each of its invoices.", "tags": [ "Note" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of records to return", "example": 10 }, "required": false, "description": "Maximum number of records to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record." }, "required": false, "description": "Opaque cursor from a previous response's nextCursor. Omit to start from the most recent record.", "name": "cursor", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "description": "Notes on this contact, including notes on its invoices", "example": 123 }, "required": false, "description": "Notes on this contact, including notes on its invoices", "name": "contactId", "in": "query" }, { "schema": { "type": "string", "format": "uuid", "description": "Notes on this invoice", "example": "00000000-0000-0000-0000-000000000123" }, "required": false, "description": "Notes on this invoice", "name": "invoiceId", "in": "query" } ], "responses": { "200": { "description": "A page of notes", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "nextCursor": { "type": "string", "description": "Pass as the cursor query parameter to fetch the next page. Absent on the last page." } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/organisation": { "get": { "operationId": "get_organisation", "summary": "Get organisation", "description": "Returns the organisation that owns the supplied API key.", "tags": [ "Organisation" ], "responses": { "200": { "description": "The organisation", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organisation" } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The organisation could not be found", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/organisation/summary": { "get": { "operationId": "get_organisation_summary", "summary": "Get organisation summary", "description": "Returns receivables totals for the authenticated organisation: amount outstanding, amount overdue, unpaid and overdue invoice counts and the number of active contacts. Totals are in the organisation's base currency.", "tags": [ "Organisation" ], "responses": { "200": { "description": "The organisation summary", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationSummary" } } } }, "400": { "description": "Invalid request", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The public API is not enabled for the organisation, or the API key lacks the required scope", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The organisation could not be found", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window", "schema": { "type": "string" } }, "X-RateLimit-Remaining": { "description": "Number of requests remaining in the current window", "schema": { "type": "string" } }, "X-RateLimit-Reset": { "description": "Unix epoch seconds by which the rolling window will have freed up capacity", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds until another request is allowed", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }