August 12, 2024

Filter Organizations and Contacts by ContactType

GET Contacts and GET Organizations

Endpoints:

• JSONCopyCopied!

  https://api.karbonhq.com/v3/Contacts
• JSONCopyCopied!

  https://api.karbonhq.com/v3/Organizations

When listing Contacts and Organizations it is now possible to filter results by Contact Type. The filter can be specified in two ways:

• as an exact match on ContactType, e.g.
  JSONCopyCopied!

  $filter=ContactType eq 'Prospect'
  will match only the Contact Type
  JSONCopyCopied!

  Prospect
• as a partial match on ContactType, e.g.
  JSONCopyCopied!

  $filter=contains(ContactType, 'Pro')
  will match the Contact Types
  JSONCopyCopied!

  Prospect
  and
  JSONCopyCopied!

  Service Provider

Refer to the Contacts API documentation or Organizations API documentation for a full example of the response from these endpoints.

Example use case

You want to automate the creation of check-in work items for VIP clients who have a Contact Type of

.

You'll need:

• To ensure you have set up the Contact Type on your VIP clients as
  JSONCopyCopied!

  Client - VIP
• A work template for the check-in work
• An idea of when you want the work to start and be due by

Make a GET request to

. This will return a response containing a list of Organizatinons. From here, iterate over the list, making a POST request to - updating the request payload to include the ClientKey of the Organization, the WorkTemplateKey of the Work Template you wish to use and any other updates to dates or assignees.

Webhook Security enhancements

POST WebhookSubscriptions

Endpoint:

⚠️ Target URLs must be secure

All newly created Webhook Subscriptions require a

that the uses scheme.

Note: This requirement is case sensitive, i.e. URLs beginning with

will not be accepted.

If the Target URL does not begin with

, the following error message is returned with an HTTP reponse code:

JSONCopyCopied!
{
    "error": {
        "code": "4002",
        "message": "Target URL must begin with https://"
    }
}

Event timestamp in Webhook payload

A

property is now included in the webhook payload, denoting when the event was initially triggered.

This is useful to:

• determine whether the message is stale and can be discarded
• avoid susceptability to replay attacks in HMAC payload signing (see below)

An example of the new Webhook payload is:

JSONCopyCopied!
{
  "ResourcePermaKey": "kCsVf7svWQw",
  "ResourceType": "Contact",
  "ActionType": "Updated",
  "Timestamp": "2024-08-01T21:54:36Z"
}

HMAC Payload signing for Webhooks

It is now possible verify that Karbon was the sender of a webhook notification using a Hash-Based Message Authentication Codes (HMAC) payload signing. To do this, create a WebHook Subscription and include the optional property

. The value assigned to must be a string at least 16 characters in length, and include only alphanumeric characters -, -, -, and .

When a webhook payload is delivered to the subscribed Target URL a

HTTP header will be included. This is a hexadecimal representation of a SHA256 hash computed using the raw webhook payload and the supplied value.

Note: When validating the signature be sure to use the raw payload. Using a parsed or formatted version of the payload will return a different signature.

⚠️ The value assigned to

should be treated as a secret and not shared publically.

Example Request

Set the

to by making a request to :

JSONCopyCopied!
{
    "TargetUrl": "https://example.com/",
    "WebhookType": "Contaact",
    "SigningKey": "example_1234-ABCD"
}

Example Payload Signature

Using the

value , the payload will include a HTTP header with the value .

Note: The

property is NOT returned in a GET request to

Additional reading:

• Hash-Based Message Authentication Codes (OKTA)
• HMAC signature validation code examples (Github)

Additions to Accounting Details

UK-Specific Enhancements to the Contacts API

The

API has been updated to support additional UK-specific details within the Accounting Details section. This update affects the following endpoints:

• JSONCopyCopied!

  GET /v3/Contacts
• JSONCopyCopied!

  POST /v3/Contacts
• JSONCopyCopied!

  PUT /v3/Contacts

New Entity Types for UK Contacts

When the country is set to "UK" in Accounting Details, additional entity types are now available in the EntityType field. These include:

• Charitable Incorporated Organisation (CIO)
• Company Limited by Guarantee (CLG)
• Community Interest Company (CIC)
• Limited Liability Partnership (LLP)
• Local Authority
• Non-Departmental Public Body
• Pension Scheme
• Royal Charter
• Unincorporated Association

If the

is set to one of the charitable entities, such as , , or , the API will now accept a in the field as part of the entity’s registration details.

Date of Signed Engagement

A new field, Date of Signed Engagement (

), has been added to capture the date when the engagement was officially signed. This field is relevant for both organisations and individuals.

Example Use Case

These enhancements allow for more precise classification and compliance when managing UK-based contacts. The introduction of additional entity types ensures that all necessary legal and organisational details are recorded, particularly for charitable organisations.

Example Request

JSONCopyCopied!
{
    "FirstName": "William",
    "LastName": "Connor",
    "EntityDescription": {
        "Text": "UK-based Community Interest Company"
    },
    "AccountingDetail": {
        "CountryCode": "UK",
        "EntityType": "Community Interest Company",
        "DateOfSignedEngagement": "2024-08-01T00:00:00Z"
    }
}

In this example, a new contact for a Community Interest Company (CIC) in the UK is being created, including the date of signed engagement.