Skip to content
  • There are no suggestions because the search field is empty.

Work with custom fields

Read and write to custom fields programmatically with the Casebook API

Introduction

In Casebook, custom fields can be created to augment Cases, Intake reports, and People with fields that are important to your organization that are not included in default fields.

Custom fields can be configured to store text, a number, a date, a true or false Boolean, or a single-select dropdown value (enum).

This guide provides instructions and code samples for reading from and writing to all types of custom fields in the Casebook API.

Prerequisites

Your organization must be licensed for External Data Interoperability (API) to interact with the Casebook API.

You will need to register an incoming application and obtain a Bearer token before starting this guide.

Instructions

Fetch custom field values for a Case, Intake Report, or Person record

Requests that return Cases, Intake Reports, or People will include a custom_fields attribute which lists all populated custom fields with their value.  If there is no value in any custom field on the record, then the value for the custom_fields attribute will be null or empty.

For example, custom field values for Cases can be fetched using Cases - Query all Cases or Cases - Fetch a Case by ID endpoints in the Cases API:

{
  "data": {
    "id": "ab47a706-59b0-44b5-bc9b-6986ce8c7668",
    "type": "cases",
    "attributes": {
      "name": "Smith Family Housing Support",
      "custom_fields": { 
        "programTier": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "monthlyRentSubsidy": 450.50,
        "veteranHousehold": true,
        "lastInspectionDate": "2023-11-15",
        "assignedOutreachRegion": "Northwest"
      }
    }
  }
}

This sample case has five custom fields - four with values set which can be used like the default attributes in the case.  However programTier has an ID set, indicating that a dropdown option has been selected which will require a lookup.

The following endpoints will describe how to look up custom fields and/or dropdown options for mapping or to use programmatically.

Query all custom fields

Admin - GET Entity Field Configurations can be used to retrieve a list of custom fields in Casebook, including the field's name, field_type, is_required, andlabel attributes.

GET <BASE_URL>/admin/entity_field_configurations?filter[name]=<YOUR_CUSTOM_FIELD_NAME>
  • Headers:
    • Authorization: Bearer <YOUR_BEARER_TOKEN>
    • Content-Type: application/vnd.api+json
  • Body: N/A
  • Query Parameters:
    • filter[name]: <YOUR_CUSTOM_FIELD_NAME>

Query all dropdown options (dynamic enums) for a dropdown custom field

The value of a custom text, number, Boolean, and date fields can be used without any additional interpretation. However custom dropdown fields require an additional step to read or write a value.

In order to read or populate a custom field that is configured as a dropdown, it is necessary to first retrieve a list of available options.

Admin - GET Dynamic Enums can be used to retrieve a list of dropdown options in Casebook

GET <BASE_URL>/admin/dynamic_enums
  • Headers:
    • Authorization: Bearer <YOUR_BEARER_TOKEN>
    • Content-Type: application/vnd.api+json
  • Body: N/A
  • Query Parameters:
    • filter[entity_field_configuration.name]: <YOUR_CUSTOM_FIELD_NAME>

Tips

Filtering custom fields by name can be used to quickly and reliably lookup a custom field returned in Case, Intake Report, and/or People records (e.g. ?filter[name]=programTier)

Similarly, filtering dropdown options by entity_field_configuration.name returns dropdown options for a specific custom field (e.g. ?filter[entity_field_configuration.name]=programTier)

Next steps

Next, fetch records which support custom fields to get started:

For more help with the Casebook API, get in touch with the Casebook Support team.