{ "openapi": "3.1.0", "servers": [ { "url": "https://api.karbonhq.com", "description": "The production API server" } ], "info": { "description": "> 📖 **Agent/developer quick-reference:** See [KARBON_API.md](./KARBON_API.md) in this repository.\n\nThis document covers Karbon API endpoints and data formats. You can find additional developer resources at [Karbon Developer Center](https://developers.karbonhq.com).\n\n**Please note the following:**\n\n- Karbon's APIs use the OData standard to help with resource searching. Use [OData's reference guide](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/) to learn more about OData URI conventions.\n- OData's `$expand` option is only available where explicitly mentioned.\n- If an endpoint allows you to use multiple properties with the `$expand` option, you can assign a comma-separated list of the properties to the `$expand` option.\n- Wherever `$orderby` option is explicitly mentioned, you can also use allowed property name followed by space then `desc` keyword to receive the response in descending order.\n\n> ⚠️ The examples shown below are for **illustrative purposes only**. Attempting to call an API using the examples for request payload might result in unusual behaviour because the Karbon generated values for various entities' keys may differ from the values in your tenant.\n\n## Credentials for accessing Karbon APIs\n\nYou will need two credentials - an Authorization token and an AccessKey - to access Karbon APIs. If you don't already have these credentials, follow the steps below to receive them and access Karbon APIs:\n\n1. Karbon Customers can enable API access and obtain the Authorization (`Bearer`) token and Access Key under **Settings -> Connected Apps -> API Applications -> `{Your API Application}`** in Karbon.\n1. Assign the Authorization token to `Authorization` header and Karbon Tenant AccessKey to `AccessKey` header to send requests to Karbon APIs.\n", "version": "v3", "title": "Karbon API", "termsOfService": "https://karbonhq.com/terms-of-use/", "contact": { "name": "API Support", "url": "https://developers.karbonhq.com/issues/" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "tags": [ { "name": "Billing", "description": "List and view an Invoice and associated line items" }, { "name": "Business Cards", "description": "View or update the Business Card attached to a Contact and/or Organization" }, { "name": "Client Groups", "description": "Create a client group to manage related contacts, create work for them, and see all related jobs in a single view. [Read more](https://help.karbonhq.com/en/articles/5880261-manage-a-client-group)" }, { "name": "Comments", "description": "Use comments on tasks to add notes or bring a colleague into the conversation to collaborate on the task. [Read more](https://help.karbonhq.com/en/articles/2111192-comment-and-collaborate-on-a-task)" }, { "name": "Contacts", "description": "Manage your contacts and get the full overview over clients, whether they are individuals or organizations. [Read more](https://help.karbonhq.com/en/articles/5708609-overview-of-contacts)" }, { "name": "Custom Fields", "description": "Endpoints to manage Custom Fields on Contacts and Organizations in Karbon, refer to the Karbon help and support content for more information on [creating custom fields](https://help.karbonhq.com/en/articles/10971113-create-a-new-custom-contact-field) and [frequently asked questions](https://help.karbonhq.com/en/articles/10971266-custom-contact-fields-faqs)" }, { "name": "Estimate Summaries", "description": "Estimate and track time to understand jobs that are on-budget, allocate resources, and uncover performance insights to transform your firm. [Read more](https://help.karbonhq.com/en/articles/4439115-overview-of-time-budgets)" }, { "name": "Files", "description": "Handle files and attachments. [Read more](https://help.karbonhq.com/en/articles/5714089-files-and-attachments)" }, { "name": "Integrated Workflows", "description": "Endpoints that enable Karbon Integration Partners to manage integrated workflow tasks enabled for their integrations. Note that these endpoints cannot be used to access Tasks or Client Tasks. Access is limited to approved developers building apps that serve all Karbon customers." }, { "name": "Organizations", "description": "Create an organization to represent marriages and couples and client groups to represent families. [Read more](https://help.karbonhq.com/en/articles/5708609-overview-of-contacts#h_8ee87bfcc1)" }, { "name": "Notes", "description": "Hold a conversation internally within your company. Unlike an email, Notes are viewed only by members of your team. [Read more](https://help.karbonhq.com/en/s/articles/5919746-use-notes)" }, { "name": "Tags", "description": "Assign or remove tags from an entity - Note: Tags APIs are currently in beta and are not enabled for all API users" }, { "name": "Tenant Settings", "description": "Retrieve lists of valid Contact Types, Work Types and Work Statuses" }, { "name": "Timesheets and Time Entries", "description": "Retrieve individual (non-aggregated) time entries, each record represents a single time entry for a specific day, user, and work item. [Read more](https://help.karbonhq.com/en/s/articles/6022358-managing-time-budgets-and-expenses-in-karbon).\n**Deprecated** Review Time aggregate Timesheets for colleagues. [Read more](https://help.karbonhq.com/en/s/articles/6022358-managing-time-budgets-and-expenses-in-karbon)" }, { "name": "Users", "description": "Create and view the basics & defaults for colleagues, teams and job roles to customize Karbon to represent the way you and your team work. [Read more](https://help.karbonhq.com/en/articles/3731216-edit-your-user-profile)" }, { "name": "Webhook Payloads", "description": "Details of the different payloads sent for Karbon Webhook subscriptions" }, { "name": "Webhook Subscriptions", "description": "Integrate your system with Karbon to receive changes made to your data in Karbon.\n\nNote: Webhook payloads take the following form:\n\n```JSON\n{\n \"ResourcePermaKey\": \"{EntityKey}\",\n \"ResourceType\": \"{EntityType}\",\n \"ActionType\": \"{ActionType}\"\n \"TimeStamp\": \"{YYYY-MM-DDTHH:mm:ssZ}\"\n}\n```\n\n" }, { "name": "Work Items", "description": "Manage a Work Item to best fit your workflow, including timelines, tasks and work teams. [Read more](https://help.karbonhq.com/en/articles/6057036-managing-work-items-and-teams)" }, { "name": "Work Schedules", "description": "Set a Work Item to repeat on a defined schedule. [Read more](https://help.karbonhq.com/en/articles/6096234-setup-repeating-work-on-a-schedule)" }, { "name": "Work Templates", "description": "Find and review templates that you created to fit your firm's unique workflows. [Read more](https://help.karbonhq.com/en/articles/5325202-create-and-customize-work-templates)" } ], "security": [ { "ApiKeyAuth": [], "BearerAuth": [] } ], "webhooks": { "contact": { "post": { "tags": ["Webhook Payloads"], "description": "Contact created or updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the created or updated contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/contact-webhook" } } } } } }, "customfield": { "post": { "tags": ["Webhook Payloads"], "description": "Custom field value added or updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the created or updated custom field value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customfield-webhook" } } } } } }, "estimate-summary": { "post": { "tags": ["Webhook Payloads"], "description": "Estimate Summary updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the updated Estimate Summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/estimate-summary-webhook" } } } } } }, "integration-task": { "post": { "tags": ["Webhook Payloads"], "description": "Integration Task created", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about an Integration Task that has been added to Work Item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/integration-task-webhook" } } } } } }, "invoice": { "post": { "tags": ["Webhook Payloads"], "description": "Invoice status updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the created or updated Invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice-webhook" } } } } } }, "note": { "post": { "tags": ["Webhook Payloads"], "description": "Note created or updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the created or updated Note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note-webhook" } } } } } }, "note-comment": { "post": { "tags": ["Webhook Payloads"], "description": "Note Comment created or updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the created or updated Note Comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note-comment-webhook" } } } } } }, "user": { "post": { "tags": ["Webhook Payloads"], "description": "User has accepted Karbon invite", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the user who has accepted their invite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-webhook" } } } } } }, "work": { "post": { "tags": ["Webhook Payloads"], "description": "Work created or updated", "parameters": [ { "$ref": "#/components/parameters/WebhookRequestHeader" } ], "requestBody": { "description": "Information about the created or updated WorkItem", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/work-webhook" } } } } } } }, "paths": { "/v3/IntegrationTaskDefinitions": { "get": { "operationId": "ListIntegrationTaskDefintions", "tags": ["Integrated Workflows"], "summary": "Get a list of integration task definitions", "description": "Use the `GET` method on this endpoint to receive a list of the integration task types that have been defined for your integration", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationTaskDefinitions" } } } } } } }, "/v3/IntegrationTasks": { "get": { "operationId": "ListIntegrationTasks", "tags": ["Integrated Workflows"], "summary": "Get a list of integration tasks", "description": "Use the `GET` method on this endpoint to receive a list of the integration tasks created in the Karbon account which has connected your integration", "parameters": [ { "$ref": "#/components/parameters/IntegrationTaskListFilter" }, { "$ref": "#/components/parameters/IntegrationTaskListOrderBy" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationTasks" } } } } } } }, "/v3/IntegrationTasks/{IntegrationTaskKey}": { "get": { "operationId": "GetIntegrationTask", "tags": ["Integrated Workflows"], "summary": "Get an integration task details", "description": "Use the `GET` method on this endpoint to retrieve the details of a single integration task", "parameters": [ { "$ref": "#/components/parameters/IntegrationTaskKey" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationTask" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } } } }, "put": { "operationId": "UpdateIntegrationTask", "tags": ["Integrated Workflows"], "summary": "Update an integration task", "description": "Use the `PUT` method on this endpoint to update the details of a single integration task", "parameters": [ { "$ref": "#/components/parameters/IntegrationTaskKey" } ], "responses": { "204": { "description": "No Content", "content": {} }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" } } } }, "409": { "description": "Conflict — the resource was modified by another request. Refetch the latest version and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Stale Object State": { "$ref": "#/components/examples/Conflict_StaleObjectState" } } } } } }, "requestBody": { "description": "An integration task request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationTaskWriteable" } } } } } }, "/v3/Invoices": { "get": { "operationId": "getInvoices", "tags": ["Billing"], "summary": "Gets a list of Invoices", "parameters": [ { "$ref": "#/components/parameters/SkipRecords" }, { "$ref": "#/components/parameters/TopRecords" }, { "in": "query", "name": "$filter", "schema": { "type": "string" }, "examples": { "invoiceStatusApproved": { "value": "InvoiceStatus eq 'Approved'", "summary": "Invoices with the status 'Approved'" }, "invoiceStatusAwaitingPayment": { "value": "InvoiceStatus eq 'AwaitingPayment'", "summary": "Invoices with the status 'AwaitingPayment'" }, "invoiceStatusPaid": { "value": "InvoiceStatus eq 'Paid'", "summary": "Invoices with the status 'Paid'" }, "invoiceStatusExported": { "value": "InvoiceStatus eq 'Exported'", "summary": "Invoices with the status 'Exported'" }, "invoiceStatusVoided": { "value": "InvoiceStatus eq 'Voided'", "summary": "Invoices with the status 'Voided'" } }, "description": "When this parameter is combined with the URI, this endpoint will return a subset of the Invoices that satisfy the `$filter` expression. The `InvoiceStatus` property supports the `eq` operator." }, { "in": "query", "name": "$orderby", "schema": { "type": "string" }, "examples": { "orderByInvoiceDate": { "value": "InvoiceDate", "summary": "Order results by InvoiceDate, oldest to newest" }, "orderByInvoiceDateDesc": { "value": "InvoiceDate desc", "summary": "Order results by InvoiceDate, newest to oldest" }, "orderByInvoiceCreatedAt": { "value": "CreatedAt", "summary": "Order results by CreatedAt timestamp, oldest to newest" }, "orderByInvoiceCreatedAtDesc": { "value": "CreatedAt desc", "summary": "Order results by CreatedAt timestamp, newest to oldest" }, "orderByInvoiceUpdatedAt": { "value": "UpdatedAt", "summary": "Order results by UpdatedAt timestamp, oldest to newest" }, "orderByInvoiceUpdatedAtDesc": { "value": "UpdatedAt desc", "summary": "Order results by UpdatedAt timestamp, newest to oldest" }, "orderByInvoiceNumber": { "value": "InvoiceNumber", "summary": "Order results by InvoiceNumber, oldest to newest" }, "orderByInvoiceNumberDesc": { "value": "InvoiceNumber desc", "summary": "Order results by InvoiceNumber, newest to oldest" } }, "description": "Alter the sort order of the invoice list" } ], "description": "Use the `GET` method on this endpoint to receive a list of Invoices", "responses": { "200": { "description": "Successful Invoices GET operation", "content": { "application/json": { "schema": { "properties": { "@odata.context": { "type": "string", "example": "https://api.karbonhq.com/v3/$metadata#Invoices", "description": "The information about Karbon controllers generating this response." }, "@odata.count": { "type": "integer", "example": 10, "description": "The total number of results" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/BillingInvoice" } } } }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#Invoices", "@odata.count": 1, "value": [ { "InvoiceKey": "M2dVbCt4RHk", "InvoiceNumber": "KIN-1001", "TotalAmountDue": 1607.13, "InvoiceTotal": 1607.13, "InvoiceSubTotal": 1397.5, "InvoiceTaxTotal": 209.63, "InvoiceDate": "2023-07-21T00:00:00Z", "PaymentDueDate": "2023-07-28T00:00:00Z", "UpdatedAt": "2023-07-20T23:52:11Z", "CurrencyCode": "AUD", "PaymentInstructions": null, "InvoiceStatus": "AwaitingPayment", "Client": { "ClientKey": "2xxnBLyCP4Ts", "ClientType": "Organization", "Name": "Acme Corp", "AddressLine": "15 Example Street", "City": "Sydney", "StateProvinceCounty": "NSW", "ZipCode": "4004", "Country": "Australia", "EmailAddress": "acme@example.com" }, "TaxLineItems": [ { "TaxName": "GST", "TaxValue": 209.63 } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "example": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } } } }, "/v3/Invoices/{InvoiceKey}": { "get": { "operationId": "getInvoiceByKey", "tags": ["Billing"], "summary": "Gets a single Invoice", "parameters": [ { "required": true, "in": "path", "name": "InvoiceKey", "example": "M2dVbCt4RHk", "schema": { "type": "string" }, "description": "The Karbon-generated Invoice key" }, { "$ref": "#/components/parameters/InvoiceExpandParams" } ], "description": "Use the `GET` method on this endpoint to receive the details of an Invoice specified using the InvoiceKey.", "responses": { "200": { "description": "Successful Invoice GET operation", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "@odata.context": { "type": "string", "example": "https://api.karbonhq.com/v3/$metadata#Invoices/$entity", "description": "The information about Karbon controllers generating this response." } } }, { "$ref": "#/components/schemas/BillingInvoiceWithPayment" } ] }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#Invoices/$entity", "InvoiceKey": "M2dVbCt4RHk", "InvoiceNumber": "KIN-1001", "TotalAmountDue": 1607.13, "InvoiceTotal": 1607.13, "InvoiceSubTotal": 1397.5, "InvoiceTaxTotal": 209.63, "InvoiceDate": "2023-07-21T00:00:00Z", "PaymentDueDate": "2023-07-28T00:00:00Z", "UpdatedAt": "2023-07-20T23:52:11Z", "CurrencyCode": "AUD", "PaymentInstructions": "Payment due 7 days from invoice date", "InvoiceStatus": "AwaitingPayment", "Client": { "ClientKey": "2xxnBLyCP4Ts", "ClientType": "Organization", "Name": "Acme Corp", "AddressLine": "15 Example Street", "City": "Sydney", "StateProvinceCounty": "NSW", "ZipCode": "4004", "Country": "Australia", "EmailAddress": "acme@example.com" }, "TaxLineItems": [ { "TaxName": "GST", "TaxValue": 209.63 } ], "LineItems": [ { "LineItemKey": "string", "BillableItemEntityKey": "string", "BillableItemType": "TimeEntry", "Description": "string", "Quantity": 0, "UnitPrice": "string", "Amount": 0, "TaxRate": 0, "TaxRateName": "string" } ], "Payments": [ { "PaymentKey": "4n3mrlQPycxn", "PaymentReference": "KPY-001", "PaymentType": "ManualPayment", "PaymentDate": "2025-01-07", "Amount": 1100.5 } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "UDI Not Found": { "$ref": "#/components/examples/Invoice_Not_Found" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } } } }, "/v3/Payments": { "get": { "operationId": "getPayments", "tags": ["Billing"], "summary": "Gets a list of Payments", "parameters": [ { "$ref": "#/components/parameters/SkipRecords" }, { "$ref": "#/components/parameters/TopRecords" } ], "description": "Use the `GET` method on this endpoint to receive a list of Payments", "responses": { "200": { "description": "Successful Payments GET operation", "content": { "application/json": { "schema": { "properties": { "@odata.context": { "type": "string", "example": "https://api.karbonhq.com/v3/$metadata#Payments", "description": "The information about Karbon controllers generating this response." }, "@odata.count": { "type": "integer", "example": 10, "description": "The total number of results" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPayment" } } } }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#Payments", "@odata.count": 1, "value": [ { "InvoiceKey": "72dVb4dTRkH", "PaymentReference": "KPY-1000", "PaymentType": "ManualPayment", "PaymentDate": "2023-07-28", "GrossAmount": 1550.5, "PaymentMethod": "Check", "KarbonPayment": { "CardType": "", "CardCountry": null, "CardFunding": "", "PayoutStatus": "", "SurchargeAmount": 0, "KarbonFeeAmount": 0, "KarbonFeeTaxAmount": 0, "NetAmount": 0 }, "Client": null } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "example": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } } } }, "/v3/ManualPayments": { "post": { "operationId": "createManualPayment", "tags": ["Billing"], "summary": "Create a manual payment against an Invoice", "description": "Use the `POST` method on this endpoint to create a Manual Payment", "responses": { "201": { "description": "Manual Payment recorded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "@odata.context": { "type": "string", "example": "https://api.karbonhq.com/v3/$metadata#Invoices/$entity", "description": "The information about Karbon controllers generating this response." }, "InvoiceKey": { "type": "string", "example": "2F3pqz88T2hW", "description": "The unique Key of the Invoice which the payment was applied to." }, "PaymentMethod": { "type": "string", "example": "Cash", "description": "The method used to make the payment." }, "PaymentDate": { "type": "string", "format": "date-time", "example": "2024-06-24T00:00:00Z", "description": "The date the payment made by the customer." }, "TotalAmount": { "type": "number", "format": "double", "example": 99.95, "description": "The amount of the payment" }, "Reference": { "description": "An optional reference to include with the payment.", "oneOf": [ { "type": "string", "maxLength": 250, "example": "Payment made in cash." }, { "type": "null" } ] }, "PaymentProcessingKey": { "type": "string", "example": "2cmDVpGdCp99", "description": "The unique id of the payment record." } } }, "example": { "@odata.context": "https://api-stage.karbonhq.com/v3/$metadata#ManualPayments/$entity", "InvoiceKey": "2F3pqz88T2hW", "PaymentMethod": "Cash", "PaymentDate": "2024-06-06T00:00:00Z", "TotalAmount": 1100.11, "Reference": "Cash payment", "PaymentProcessingKey": "2cmDVpGdCp99" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "description": "The response shown when trying to overpay an invoice", "type": "object", "properties": { "Error": { "type": "object", "properties": { "Code": { "type": "string", "description": "A code that denotes different types of error under the 400 response code.", "example": "4002" }, "Message": { "type": "string", "description": "The error message", "example": "An attempt was made to overpay Invoice with [tenantPermaKey=2BzmMRkhbwBT] and [invoicePermaKey=tnl31HQDzRS]." } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } }, "requestBody": { "description": "A manual payment request body", "required": true, "content": { "application/json": { "schema": { "required": ["InvoiceKey", "PaymentMethod", "PaymentDate", "TotalAmount"], "properties": { "InvoiceKey": { "type": "string", "example": "tnl31HQDzRS", "description": "The unique key of the Invoice to pay" }, "PaymentMethod": { "type": "string", "example": "Cash", "enum": [ "Bank Transfer", "Direct Debit", "Credit Card Online", "Credit Card Office", "Check", "Cash", "Other" ], "description": "The method used to pay the invoice" }, "PaymentDate": { "type": "string", "example": "2024-06-30", "description": "The date the Payment is to be Recorded using an ISO 8601 datestamp", "format": "date" }, "TotalAmount": { "type": "number", "example": 520.55, "description": "The amount of the payment in the nominated currency, must be greater than 0 and equal or less than the outstanding due amount on the invoice.", "format": "float", "minimum": 0.01 }, "Reference": { "type": "string", "example": "Payment in person", "description": "An optional reference to include with the payment." } } } } } } } }, "/v3/ManualPayments/{ManualPaymentKey}": { "delete": { "operationId": "deleteManualPayment", "tags": ["Billing"], "summary": "Delete a manual payment", "description": "Use the `DELETE` method on this endpoint to delete a Manual Payment", "parameters": [ { "required": true, "in": "path", "name": "ManualPaymentKey", "example": "2Rz483jmtvzb", "schema": { "type": "string" }, "description": "The Manual Payment key" } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Manual Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualPaymentNotFoundErrorMessage" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } } } }, "/v3/ReverseManualPayment": { "post": { "operationId": "reverseManualPayment", "tags": ["Billing"], "summary": "Reverse a manual payment", "description": "Use the `POST` method on this endpoint to reverse a Manual Payment", "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Manual Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualPaymentNotFoundErrorMessage" } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } }, "requestBody": { "description": "A reverse manual payment request body", "required": true, "content": { "application/json": { "schema": { "required": ["PaymentKey", "ReversalDate"], "properties": { "PaymentKey": { "type": "string", "example": "2NmwhRJXjHdH", "description": "The unique key of the Manual Payment to reverse" }, "ReversalDate": { "type": "string", "format": "date-time", "example": "2025-08-01T00:00:00Z", "description": "The date the Reversal is to be recorded using an ISO 8601 datestamp" } } } } } } } }, "/v3/Payments/{PaymentKey}": { "get": { "operationId": "getPaymentByPaymentKey", "tags": ["Billing"], "summary": "Gets a single Payment", "parameters": [ { "in": "path", "name": "PaymentKey", "schema": { "type": "string" }, "required": true, "example": "72dVb4dTRkH", "description": "The unique key of the payment" } ], "description": "Use the `GET` method on this endpoint to receive details of a single Payment", "responses": { "200": { "description": "Successful Payment GET operation", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "@odata.context": { "type": "string", "example": "https://api.karbonhq.com/v3/$metadata#Payments/$entity", "description": "The information about Karbon controllers generating this response." } } }, { "$ref": "#/components/schemas/BillingPayment" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "example": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } } } }, "/v3/BusinessCards/{BusinessCardKey}": { "get": { "operationId": "getBusinessCardByKey", "tags": ["Business Cards"], "summary": "Gets a single Business Card", "parameters": [ { "required": true, "in": "path", "name": "BusinessCardKey", "example": "2tBHyXtJBxBy", "schema": { "type": "string" }, "description": "The Karbon-generated Business Card key" } ], "description": "Use the `GET` method on this endpoint to receive the details of a Business Card specified using the BusinessCardKey.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "@odata.context": { "type": "string", "example": "https://api.karbonhq.com/v3/$metadata#BusinessCards/$entity", "description": "The information about Karbon controllers generating this response." } } }, { "type": "object", "properties": { "EntityType": { "type": "string", "example": "Organization", "enum": ["Contact", "Organization", "ClientGroup"], "description": "The type of entity that this business card is connected to." }, "EntityKey": { "type": "string", "example": "2jHPZngklwxQ", "description": "The unique key for the entity specified this business card is connected to" } } }, { "$ref": "#/components/schemas/BusinessCard" } ] }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#BusinessCards/$entity", "@odata.type": "#KarbonService.ClientGroupDTO", "BusinessCardKey": "2tBHyXtJBxBy", "EntityType": "Organization", "EntityKey": "2jHPZngklwxQ", "IsPrimaryCard": true, "WebSites": ["www.website.one", "www.website.two"], "EmailAddresses": ["sample@example.com", "sample.two@example.com"], "OrganizationKey": "ZGNmtYyLm4z", "RoleOrTitle": "COO", "FacebookLink": "facebook.com/sampleName", "LinkedInLink": "linkedin.com/sampleName", "TwitterLink": "twitter.com/sampleName", "SkypeLink": "skype.com/sampleName", "Addresses": [ { "AddressKey": "e150a05a-2dea-4292-8bc8-03398c9384e4", "AddressLines": "45 Sample Street", "City": "Alexandria", "StateProvinceCounty": "NSW", "ZipCode": "2015", "CountryCode": "AU", "Label": "Physical" } ], "PhoneNumbers": [ { "PhoneNumberKey": "6e0b9ace-24b1-4328-a922-3b8be5ef5052", "Number": "1234567890", "CountryCode": "AU", "Label": "Work" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "UDI Not Found": { "$ref": "#/components/examples/BusinessCard_Not_Found" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } } } }, "put": { "operationId": "updateBusinessCardByKey", "tags": ["Business Cards"], "summary": "Updates a single Business Card", "parameters": [ { "required": true, "in": "path", "name": "BusinessCardKey", "schema": { "type": "string" }, "example": "2tBHyXtJBxBy", "description": "The Karbon-generated Business Card key" } ], "description": "Use the `PUT` method on this endpoint to update the details of a Business Card specified using the BusinessCardKey.", "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Incorrect or Missing Data": { "$ref": "#/components/examples/Missing_Update_Data" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Key Not Found": { "$ref": "#/components/examples/ResourceNotFound" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Non existent Key": { "$ref": "#/components/examples/Shortened_5001" }, "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } }, "409": { "description": "Conflict — the resource was modified by another request. Refetch the latest version and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Stale Object State": { "$ref": "#/components/examples/Conflict_StaleObjectState" } } } } } }, "requestBody": { "description": "Refer to the table below for more information on each field in the request body.", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "EntityType": { "type": "string", "example": "Organization", "enum": ["Contact", "Organization", "ClientGroup"], "description": "The type of entity that this business card is connected to." }, "EntityKey": { "type": "string", "example": "2jHPZngklwxQ", "description": "The unique key for the entity specified this business card is connected to" } } }, { "$ref": "#/components/schemas/BusinessCardRequest" } ] } } } } } }, "/v3/ClientGroups": { "get": { "tags": ["Client Groups"], "summary": "Gets a list of Client Groups", "parameters": [ { "in": "query", "name": "$filter", "schema": { "type": "string", "pattern": "^FullName" }, "example": "FullName eq 'Sample Management Team'", "description": "When this parameter is combined with the URI, this endpoint will return a subset of the Client Groups that satisfy the `$filter` expression.\n" }, { "in": "query", "name": "$orderby", "schema": { "type": "string", "default": "ClientGroupKey" }, "examples": { "fullName": { "value": "FullName", "summary": "Order by Full name in ascending (A-Z) order" }, "fullNameDesc": { "value": "FullName desc", "summary": "Order by Full name in descending (Z-A) order" } }, "description": "When this parameter is combined with the URI, this endpoint will return a list of Client Groups, sorted by the available properties.\n" }, { "$ref": "#/components/parameters/SkipRecords" }, { "$ref": "#/components/parameters/TopRecords" } ], "description": "Use the `GET` method on this endpoint to receive a paginated list of Client Groups from your tenant.\nUsing the query parameters available to this endpoint, you can also filter the list of Client Groups by their full name.\n\n**Notes**\n\n* This endpoint returns a maximum of 100 Client Groups at once.\n* If the query results in more than 100 Client Groups, a link to the next set of the results will be given in the `@odata.nextLink` field of the response.\n* The `$filter` query parameter supports a logical operator - `eq` and a property to help you form an expression.\n\n", "operationId": "getClientGroups", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetClientGroup" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Unsupported Property": { "$ref": "#/components/examples/Unsupported_Property_Filter" }, "Unsupported Orderby Property": { "$ref": "#/components/examples/Orderby_Unsupported_Property" }, "$top limit exceeded": { "$ref": "#/components/examples/Limit_Exceeded_Top" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } } } }, "post": { "tags": ["Client Groups"], "summary": "Creates a new Client Group", "description": "Use the `POST` method on this endpoint to create a new Client Group in your tenant.\n", "operationId": "createClientGroup", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ResponseCreateClientGroup" }, { "type": "object", "properties": { "AccountingDetails": { "type": ["string", "null"], "description": "The accounting details associated with the Client Group. This property will be `null`." } } }, { "type": "object", "properties": { "BusinessCard": { "$ref": "#/components/schemas/BusinessCard" } } }, { "type": "object", "properties": { "ClientTeam": { "$ref": "#/components/schemas/ClientTeam" } } } ] }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#ClientGroups/$entity", "@odata.type": "#KarbonService.ClientGroupDTO", "ClientGroupKey": "38zlxNyJSr8y", "FullName": "Abigail Silvers", "ClientOwner": "rodney.muller@samplecompany.com", "ClientManager": "jessica.tse@samplecompany.com", "ContactType": "Client", "UserDefinedIdentifier": "SILVERS", "RestrictionLevel": "Public", "PrimaryContact": "Duncan Moore", "LastModifiedDateTime": "2022-07-05T07:30:13.7188114Z", "Members": [ { "ContactKey": null, "OrganizationKey": "X6Hm1D2Jvxf" }, { "ContactKey": "CFbcmM5Lvzc", "OrganizationKey": null } ], "EntityDescription": { "Text": "Bicycle rental service in the New jersey area." }, "AccountingDetails": null } } }, "headers": { "Location": { "description": "The endpoint URL to the newly created Client Group.", "schema": { "type": "string", "example": "https://api.karbonhq.com/v3/ClientGroups('4t8LbR1QcbGS')" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Incorrect or Missing Data": { "$ref": "#/components/examples/Missing_Create_Data" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Duplicate UDI": { "$ref": "#/components/examples/Duplicate_UDI" }, "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } } }, "requestBody": { "description": "Refer to the table below for more information on each field in the request body.", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateClientGroup" }, { "type": "object", "properties": { "AccountingDetails": { "type": ["string", "null"], "description": "The accounting details associated with the Client Group. This property will be `null`." } } }, { "type": "object", "properties": { "BusinessCard": { "$ref": "#/components/schemas/BusinessCard" } } }, { "type": "object", "properties": { "ClientTeam": { "$ref": "#/components/schemas/ClientTeam" } } } ] }, "example": { "FullName": "Abigail Silvers", "ClientOwner": "rodney.muller@samplecompany.com", "ClientManager": "jessica.tse@samplecompany.com", "ContactType": "Client", "UserDefinedIdentifier": "SILVERS", "RestrictionLevel": "Public", "PrimaryContact": "Duncan Moore", "EntityDescription": { "Text": "Bicycle rental service in the New jersey area." }, "Members": [ { "ContactKey": null, "OrganizationKey": "X6Hm1D2Jvxf" }, { "ContactKey": "CFbcmM5Lvzc", "OrganizationKey": null } ], "ClientTeam": [ { "MemberKey": "2q2wx44pTBNh", "MemberType": "User", "RoleType": "ClientManager" } ] } } } } } }, "/v3/ClientGroups/GetClientGroupByUserDefinedIdentifier(UserDefinedIdentifier='{UserDefinedIdentifier}')": { "get": { "tags": ["Client Groups"], "summary": "Gets a Client Group using UserDefinedIdentifier", "parameters": [ { "required": true, "in": "path", "name": "UserDefinedIdentifier", "schema": { "type": "string" }, "example": "SILVERS", "description": "A unique identifier that you had created to identify this Client Group. This parameter is **not** case sensitive." }, { "in": "query", "name": "$expand", "schema": { "type": "string", "enum": ["BusinessCard"] }, "example": "BusinessCard", "description": "When this parameter is combined with the URI, this endpoint will also return the Business Card of the Client Group.\n" } ], "description": "Use the `GET` method on this endpoint to receive the details of a Client Group specified using the UserDefinedIdentifier.\n\nUsing the query parameter available to this endpoint, you can also include Business Card details of the Client Group in the response.\n", "operationId": "getClientGroupByUDI", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ResponseCreateClientGroup" }, { "type": "object", "properties": { "AccountingDetails": { "type": ["string", "null"], "description": "The accounting details associated with the Client Group. This property will be `null`." } } }, { "type": "object", "properties": { "BusinessCard": { "$ref": "#/components/schemas/BusinessCard" } } }, { "type": "object", "properties": { "ClientTeam": { "$ref": "#/components/schemas/ClientTeam" } } } ] }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#ClientGroups/$entity", "@odata.type": "#KarbonService.ClientGroupDTO", "ClientGroupKey": "38zlxNyJSr8y", "FullName": "Abigail Silvers", "ClientOwner": "rodney.muller@samplecompany.com", "ClientManager": "jessica.tse@samplecompany.com", "ContactType": "Client", "UserDefinedIdentifier": "SILVERS", "RestrictionLevel": "Public", "PrimaryContact": "Duncan Moore", "LastModifiedDateTime": "2022-07-05T07:30:13.7188114Z", "Members": [ { "ContactKey": "34yxkY51knn7", "OrganizationKey": null }, { "ContactKey": null, "OrganizationKey": "4ncPZ7q96SGc" } ], "EntityDescription": { "Text": "Bicycle rental service in the New jersey area." }, "AccountingDetails": null, "BusinessCard": { "BusinessCardKey": "2tBHyXtJBxBy", "EntityType": "ClientGroup", "EntityKey": "38zlxNyJSr8y", "IsPrimaryCard": true, "WebSites": ["www.website.one", "www.website.two"], "EmailAddresses": ["sample@example.com", "sample.two@example.com"], "OrganizationKey": "ZGNmtYyLm4z", "RoleOrTitle": "COO", "FacebookLink": "facebook.com/sampleName", "LinkedInLink": "linkedin.com/sampleName", "TwitterLink": "twitter.com/sampleName", "SkypeLink": "skype.com/sampleName", "Addresses": [ { "AddressKey": "e150a05a-2dea-4292-8bc8-03398c9384e4", "AddressLines": "45 Sample Street", "City": "Alexandria", "StateProvinceCounty": "NSW", "ZipCode": "2015", "CountryCode": "AU", "Label": "Physical" } ], "PhoneNumbers": [ { "PhoneNumberKey": "6e0b9ace-24b1-4328-a922-3b8be5ef5052", "Number": "1234567890", "CountryCode": "AU", "Label": "Work" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "UDI Is Empty": { "$ref": "#/components/examples/UDI_Is_Empty" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "UDI Not Found": { "$ref": "#/components/examples/UDI_Not_Found" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } } } } }, "/v3/ClientGroups/{ClientGroupkey}": { "get": { "tags": ["Client Groups"], "summary": "Gets a Client Group using ClientGroupkey", "parameters": [ { "required": true, "in": "path", "name": "ClientGroupkey", "schema": { "type": "string" }, "example": "4t8LbR1QcbGS", "description": "The Karbon-generated Client Group key" }, { "in": "query", "name": "$expand", "schema": { "type": "string" }, "examples": { "BusinessCard": { "value": "BusinessCard", "summary": "Include the Business Card for the Client Group the API response" }, "ClientTeam": { "value": "ClientTeam", "summary": "Include the Client Team assigned to the Client Group in the API response" }, "BusinessCardAndClientTeam": { "value": "BusinessCard,ClientTeam", "summary": "Include the Business Card and the Client Team assigned to the Client Group in the API response" } }, "description": "When this parameter is specified in the query string this endpoint will also return the Business Card and/or Client Team of the Client Group.\n" } ], "description": "Use the `GET` method on this endpoint to receive the details of a Client Group specified using the `ClientGroupKey`.\n\nUsing the query parameter available to this endpoint, you can also include the Business Card details of the Client Group in the response.\n", "operationId": "getClientGroupByID", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ResponseCreateClientGroup" }, { "type": "object", "properties": { "AccountingDetails": { "type": ["string", "null"], "description": "The accounting details associated with the Client Group. This property will be `null`." } } }, { "type": "object", "properties": { "BusinessCard": { "$ref": "#/components/schemas/BusinessCard" } } }, { "type": "object", "properties": { "ClientTeam": { "$ref": "#/components/schemas/ClientTeam" } } } ] }, "example": { "@odata.context": "https://api.karbonhq.com/v3/$metadata#ClientGroups/$entity", "@odata.type": "#KarbonService.ClientGroupDTO", "ClientGroupKey": "38zlxNyJSr8y", "FullName": "Abigail Silvers", "ClientOwner": "rodney.muller@samplecompany.com", "ClientManager": "jessica.tse@samplecompany.com", "ContactType": "Client", "UserDefinedIdentifier": "SILVERS", "RestrictionLevel": "Public", "PrimaryContact": "Duncan Moore", "LastModifiedDateTime": "2022-07-05T07:30:13.7188114Z", "Members": [ { "ContactKey": "34yxkY51knn7", "OrganizationKey": null }, { "ContactKey": null, "OrganizationKey": "4ncPZ7q96SGc" } ], "EntityDescription": { "Text": "Bicycle rental service in the New jersey area." }, "AccountingDetails": null, "BusinessCard": { "BusinessCardKey": "2tBHyXtJBxBy", "EntityType": "ClientGroup", "EntityKey": "38zlxNyJSr8y", "IsPrimaryCard": true, "WebSites": ["www.website.one", "www.website.two"], "EmailAddresses": ["sample@example.com", "sample.two@example.com"], "OrganizationKey": "ZGNmtYyLm4z", "RoleOrTitle": "COO", "FacebookLink": "facebook.com/sampleName", "LinkedInLink": "linkedin.com/sampleName", "TwitterLink": "twitter.com/sampleName", "SkypeLink": "skype.com/sampleName", "Addresses": [ { "AddressKey": "e150a05a-2dea-4292-8bc8-03398c9384e4", "AddressLines": "45 Sample Street", "City": "Alexandria", "StateProvinceCounty": "NSW", "ZipCode": "2015", "CountryCode": "AU", "Label": "Physical" } ], "PhoneNumbers": [ { "PhoneNumberKey": "6e0b9ace-24b1-4328-a922-3b8be5ef5052", "Number": "1234567890", "CountryCode": "AU", "Label": "Work" } ] }, "ClientTeam": [ { "MemberKey": "JTphCpQqQYg", "MemberType": "User", "RoleType": "ClientOwner" }, { "MemberKey": "nRML2ngs7WJ", "MemberType": "User", "RoleType": "ClientManager" }, { "MemberKey": "3fv7lflmd1Z7", "MemberType": "User", "RoleType": "UserDefinedRole2" }, { "MemberKey": "3v9YJmt55hLY", "MemberType": "User", "RoleType": "UserDefinedRole1" }, { "MemberKey": "3zdQh89xCmZM", "MemberType": "User", "RoleType": null } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Key Not Found": { "$ref": "#/components/examples/Key_Not_Found" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } } } }, "put": { "tags": ["Client Groups"], "summary": "Updates a Client Group (Full)", "parameters": [ { "required": true, "in": "path", "name": "ClientGroupkey", "schema": { "type": "string" }, "example": "4t8LbR1QcbGS", "description": "The Karbon-generated Client Group key" } ], "description": "Use the `PUT` method on this endpoint to update full details of a Client Group specified using the `ClientGroupkey`.\n\nUsing the query parameter available to this endpoint, you can also update the Business Card details of the Client Group.\n", "operationId": "putClientGroupByID", "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Incorrect or Missing Data": { "$ref": "#/components/examples/Missing_Update_Data" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Key Not Found": { "$ref": "#/components/examples/ResourceNotFound" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Non existent Key": { "$ref": "#/components/examples/Shortened_5001" }, "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } }, "409": { "description": "Conflict — the resource was modified by another request. Refetch the latest version and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Stale Object State": { "$ref": "#/components/examples/Conflict_StaleObjectState" } } } } } }, "requestBody": { "description": "Refer to the table below for more information on each field in the request body.", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CreateClientGroup" }, { "type": "object", "properties": { "BusinessCard": { "$ref": "#/components/schemas/BusinessCardRequest" } } } ] }, "example": { "FullName": "Abigail Silvers", "ClientOwner": "rodney.muller@samplecompany.com", "ClientManager": "jessica.tse@samplecompany.com", "ContactType": "Client", "UserDefinedIdentifier": "SILVERS", "RestrictionLevel": "Public", "PrimaryContact": "Duncan Moore", "EntityDescription": { "Text": "Bicycle rental service in the New jersey area." }, "BusinessCard": { "IsPrimaryCard": true, "WebSites": ["www.website.one", "www.website.two"], "EmailAddresses": ["sample@example.com", "sample.two@example.com"], "RoleOrTitle": "COO", "FacebookLink": "facebook.com/sampleName", "LinkedInLink": "linkedin.com/sampleName", "TwitterLink": "twitter.com/sampleName", "SkypeLink": "skype.com/sampleName", "Addresses": [ { "AddressLines": "45 Sample Street", "City": "Alexandria", "StateProvinceCounty": "NSW", "ZipCode": "2015", "CountryCode": "AU", "Label": "Physical" } ], "PhoneNumbers": [ { "Number": "1234567890", "CountryCode": "AU", "Label": "Work" } ] } } } } } }, "patch": { "tags": ["Client Groups"], "summary": "Updates a Client Group (Partial)", "parameters": [ { "required": true, "in": "path", "name": "ClientGroupkey", "schema": { "type": "string" }, "example": "4t8LbR1QcbGS", "description": "The Karbon-generated Client Group key" } ], "description": "Use the `PATCH` method on this endpoint to update partial details of a Client Group specified using the `ClientGroupkey`.\n\nThis method **only supports** editing the `FullName` property.\n", "operationId": "patchClientGroupByID", "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Unsupported Property": { "$ref": "#/components/examples/Update_Unsupported_Property" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Key Not Found": { "$ref": "#/components/examples/ResourceNotFound" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Non existent Key": { "$ref": "#/components/examples/Shortened_5001" }, "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } }, "409": { "description": "Conflict — the resource was modified by another request. Refetch the latest version and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Stale Object State": { "$ref": "#/components/examples/Conflict_StaleObjectState" } } } } } }, "requestBody": { "description": "Refer to the table below for more information on each field in the request body.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "FullName": { "type": "string", "description": "The full name of the Client Group", "example": "Abigail Silvers" } } }, "example": { "FullName": "Abigail Silvers" } } } } } }, "/v3/Comments('{Commentkey}')": { "get": { "tags": ["Comments"], "summary": "Gets a Comment using CommentKey", "description": "This endpoint can be used to get the comment attached to any Karbon entity (e.g., Work Item, Timesheet, Notes, Contacts).\n\n\nTo place a call using this endpoint, you will need the unique `Commentkey` that is used to identify a particular comment in Karbon.", "operationId": "getComment", "parameters": [ { "name": "Commentkey", "in": "path", "description": "A Karbon-generated unique value that is used to identify the comment", "required": true, "schema": { "type": "string" }, "example": "Xn2r5u7xZe" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetComment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Incorrect or Missing Data": { "$ref": "#/components/examples/Missing_Update_Data" }, "Unsupported Option": { "$ref": "#/components/examples/Unsupported_option" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceNotFound" }, "examples": { "Unauthorized Access": { "$ref": "#/components/examples/UnauthorizedAccess" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Key Not Found": { "$ref": "#/components/examples/CommentKey_Not_Found" } } } } }, "429": { "description": "Rate Limit Exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorMessage" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessages" }, "examples": { "Undefined Error": { "$ref": "#/components/examples/elongated_5001" } } } } } } } }, "/v3/Contacts": { "get": { "tags": ["Contacts"], "summary": "Gets a list of Contacts", "parameters": [ { "in": "query", "name": "$filter", "schema": { "type": "string" }, "examples": { "FullName": { "value": "FullName eq 'Sample Management Team", "summary": "Return only the Contacts where the Full Name matches 'Sample Client Team'" }, "EmailAddress": { "value": "EmailAddress eq 'karbon@example.com'", "summary": "Return only the Contacts where the Email Address matches 'karbon@example.com'" }, "PhoneNumber": { "value": "PhoneNumber eq '220114588'", "summary": "Return only the Contacts where the Phone Number matches '220114588'" }, "ContactType": { "value": "ContactType eq 'Client'", "summary": "Return only the Contacts where the Contact Type matches 'Client'" }, "externalKey": { "value": "ExternalKey eq '123987456'", "summary": "Return only the Contacts whose ExternalKey matches '123987456'. ExternalKey is the identifier from an integrated external system - XPM Client ID, Xero Contact ID, or QuickBooks Online Intuit Customer ID. Only the eq operator is supported." } }, "description": "When this parameter is combined with the URI, this endpoint will return a subset of the Contacts that satisfy the `$filter` expression.\n" }, { "in": "query", "name": "$orderby", "schema": { "type": "string", "enum": ["FullName", "FullName desc", "LastModifiedDateTime", "LastModifiedDateTime desc"], "default": "ClientGroupKey" }, "example": "FullName", "description": "When this parameter is combined with the URI, this endpoint will return a list of Contacts, sorted by the available properties.\n" }, { "$ref": "#/components/parameters/SkipRecords" }, { "$ref": "#/components/parameters/TopRecords" } ], "description": "Use the `GET` method on this endpoint to receive a paginated list of Contacts from your tenant. Using the query parameters available to this endpoint, you can also filter the list of Contacts by their full name, email address, or phone number.\n\n**Notes**