Home

August 22, 2022

This document provides an overview of the Aug 2, 2022 release of Karbon’s Public API.

In summary, we have created an API endpoint that makes it possible to retrieve or update a single BusinessCard.

  1. GET Business Card by BusinessCardKey
  2. PUT Business Card by BusinessCardKey

GET Business Card by BusinessCardKey

Endpoint: https://api.karbonhq.com/v3/BusinessCards/{BusinessCardKey}

We have added a new endpoint that, when used with GET method, retrieves a Business Card using its BusinessCardKey.

To make an API call to this endpoint using GET method, replace {BusinessCardKey} parameter in the endpoint with a valid BusinessCardKey.

Note: You can still retrieve a BusinessCard through the Contacts, Organizations and ClientGroups APIs.

Example use case

You want to retrieve a Business Card associated with a Karbon entity. To receive the BusinessCard, use GET method on the following endpoint and replace {BusinessCardKey} with Karbon generated key unique to a Business Card.

Endpoint: https://api.karbonhq.com/v3/BusinessCards/{BusinessCardKey}

PUT Business Card by BusinessCardKey

Endpoint: https://api.karbonhq.com/v3/BusinessCards/{BusinessCardKey}

We have also enabled PUT method on the same endpoint, allowing you to update a Business Card using its BusinessCardKey.

To make an API call to this endpoint using PUT method:

  • Replace {BusinessCardKey} parameter in the endpoint with a valid BusinessCardKey
  • Ensure the request payload includes all BusinessCard properties
    • Supply changes to the properties that you want to update
    • Supply original value to the properties that you don’t want to update

Note

  • The EntityType property of the BusinessCard must match the entity (Contact, Organization or ClientGroup) it belongs to.
  • Setting the value of IsPrimaryCard parameter will have no effect for Business Cards associated with Organizations, ClientGroups and Contacts.
  • A future version of this API endpoint will include validation for the IsPrimaryCard property.
  • You can still update a BusinessCard using PUT method against Contacts, Organizations or ClientGroups API. However, those API endpoints require you to send a payload, containing a full data set for that entity (i.e., entity details, all other BusinessCards and any AccountingDetails).
  • Updating multiple Business Cards using the Contacts API will set the first BusinessCard as the primary card. In such scenario, it disregards the value of IsPrimaryCard property for all objects within the BusinessCards array.

Example use case

You want to update a Business Card associated with a Karbon entity. To update the BusinessCard, use PUT method on the endpoint given below. Replace {BusinessCardKey} with Karbon generated key unique to a Business Card and supply a request payload with all properties associated with the BusinessCard.

Endpoint: https://api.karbonhq.com/v3/BusinessCards/{BusinessCardKey}