August 12, 2024

Filter Organizations and Contacts by ContactType

GET Contacts and GET Organizations

Endpoints:

• https://api.karbonhq.com/v3/Contacts
• 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. $filter=ContactType eq 'Prospect' will match only the Contact Type Prospect
• as a partial match on ContactType, e.g. $filter=contains(ContactType, 'Pro') will match the Contact Types Prospect and 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 Client - VIP.

You’ll need:

• To ensure you have set up the Contact Type on your VIP clients as 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 https://api.karbonhq.com/v3/Organizations?$filter=ContactType eq 'Client - VIP'. This will return a response containing a list of Organizatinons. From here, iterate over the list, making a POST request to https://api.karbonhq.com/v3/WorkItems - 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: https://api.karbonhq.com/v3/WebhookSubscriptions

⚠️ Target URLs must be secure

All newly created Webhook Subscriptions require a TargetUrl that the uses https:// scheme.

Note: This requirement is case sensitive, i.e. URLs beginning with HTTPS:// will not be accepted.

If the Target URL does not begin with https://, the following error message is returned with an HTTP 400 reponse code:

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

Event timestamp in Webhook payload

A Timestamp 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:

{
  "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 SigningKey. The value assigned to SigningKey must be a string at least 16 characters in length, and include only alphanumeric characters A-Z, a-z, 0-9, - and _.

When a webhook payload is delivered to the subscribed Target URL a Signature HTTP header will be included. This is a hexadecimal representation of a SHA256 hash computed using the raw webhook payload and the supplied SigningKey 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 SigningKey should be treated as a secret and not shared publically.

Example Request

Set the SigningKey to example_1234-ABCD by making a POST request to https://api.karbonhq.com/v3/WebhookSubscriptions:

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

Example Payload Signature

Using the SigningKey value example_1234-ABCD, the payload {"ResourcePermaKey":"kCsVf7svWQw","ResourceType":"Contact","ActionType":"Updated","Timestamp":"2024-08-01T21:54:36Z"} will include a Signature HTTP header with the value 8c42dd0e4779a2e8a56d3b8ef962238ca26f95ddc2d9abb0e76f04991a3442f3.

Note: The SigningKey property is NOT returned in a GET request to https://api.karbonhq.com/v3/WebhookSubscriptions

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 /v3/Contacts API has been updated to support additional UK-specific details within the Accounting Details section. This update affects the following endpoints:

• GET /v3/Contacts
• POST /v3/Contacts
• 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 EntityType is set to one of the charitable entities, such as Charitable Incorporated Organisation (CIO), Company Limited by Guarantee (CLG), or Royal Charter, the API will now accept a Charity Number in the RegistrationNumber field as part of the entity’s registration details.

Date of Signed Engagement

A new field, Date of Signed Engagement (DateSignedEngagement), 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

POST /v3/Contacts

{
    "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.