Skip to main content

Custom Fields via API

Read and set custom field values on patients, orders, invoices, products, vendors, locations, and purchase orders, and manage custom field definitions.

How Custom Fields Work

A custom field is a field your organization adds to a record type, such as "Referral Source" on patients or "Branch" on orders.

Concept

Description

Field

The definition: name, record type, and value type. ID starts with CF.

Value

The field's value on a specific record

List item

An option in a DropDown field. ID starts with LI.

Record Types (Type)

Patient, Order, Invoice, Product, Vendor, OrganizationLocation, InventoryLocation, PurchaseOrder

Value Types (FieldValueType)

Type

Value to send

Text

A string

Number

A number

Date

YYYY-MM-DD

CheckBox

true or false

DropDown

A list item (see DropDown fields)

Link

A URL


Find Your Custom Fields

GET /v1/custom-fields

Filter

Notes

types

Record type, e.g. Patient

fieldValueTypes

e.g. DropDown

name / namesEqual

Partial or exact name match

ids

isPinned

includeArchived

created.from / modified.from (and .to)

pageIndex / pageSize / selectCount

Paging

GET /v1/custom-fields?types=Patient&fieldValueTypes=DropDown
{
"Items": [
{
"Id": "CFcfa0fb00d62b7c28e564d4d963ca08ed",
"Name": "Branch",
"Type": { "Id": "Patient", "Name": "Patient" },
"FieldValueType": { "Id": "DropDown", "Name": "DropDown" },
"Description": "",
"IsPinned": false,
"IsReadonly": false,
"Archived": false
}
]
}

Get one field: GET /v1/custom-fields/{fieldId}

Lookup lists: GET /v1/custom-fields/types/dictionary (record types) and GET /v1/custom-fields/field-value-types/dictionary (value types).


DropDown Fields

Get a DropDown field's options:

GET /v1/custom-fields/{fieldId}/list-items
{
"Items": [
{ "Id": "LIcfa0fb00d62b0bbb342477ba24327f7b", "Text": "Branch 1", "Archived": false },
{ "Id": "LIcfa0fb00d62b92d8eca49baecc68beb2", "Text": "Branch 2", "Archived": false }
]
}

Optional filters: text, includeArchived, pageIndex, pageSize.


Read Values on a Record

GET /v1/{record}/{id}/custom-fields
GET /v1/patients/10000105/custom-fields
{
"Items": [
{ "FieldId": "CF5201db00b62b525a2b94ca4a7f10dfc1", "Value": "Physician referral", "FieldValueType": { "Id": "Text", "Name": "Text" } },
{ "FieldId": "CFcfa0fb00d62b7c28e564d4d963ca08ed", "FieldValueType": { "Id": "DropDown", "Name": "DropDown" } }
]
}

Fields with no value set are returned without a Value.

Get one value: GET /v1/{record}/{id}/custom-fields/{fieldId}


Set Values on a Record

How you set values depends on the record type.

Patients, Orders, Invoices, and Products: Set Several at Once

PUT /v1/{record}/{id}/custom-fields
PUT /v1/patients/10000105/custom-fields
{
"Items": [
{ "FieldId": "CF5201db00b62b525a2b94ca4a7f10dfc1", "Value": "Physician referral" },
{ "FieldId": "CFcfa0fb00d62b7c28e564d4d963ca08ed", "Value": "LIcfa0fb00d62b0bbb342477ba24327f7b" }
]
}

Response: 200 OK

💡 You can also set custom fields when creating or updating the record.

Patients (POST /v1/patients, PUT /v1/patients/{id}), orders (POST /v1/patients/{patientId}/orders, PUT /v1/patients/{patientId}/orders/{id}), and invoices (POST /v1/invoices, PUT /v1/invoices/{id}) accept a CustomFields array in the same FieldId / Value format.

Vendors, organization locations, inventory locations, and purchase orders: set one at a time

PUT /v1/{record}/{id}/custom-fields/{fieldId}
PUT /v1/vendors/{vendorId}/custom-fields/CF85bfcb00b62b629ac7042bae6d69c5cf
{ "Value": "Net 30" }

Clear a value: DELETE /v1/{record}/{id}/custom-fields/{fieldId}, available for vendors, organization locations, inventory locations, and purchase orders.

Endpoints by Record Type

Record

Read

Set

Patient

GET /v1/patients/{patientId}/custom-fields

PUT /v1/patients/{patientId}/custom-fields

Order

GET /v1/orders/{orderId}/custom-fields

PUT /v1/orders/{orderId}/custom-fields

Invoice

GET /v1/invoices/{invoiceId}/custom-fields

PUT /v1/invoices/{invoiceId}/custom-fields

Product

GET /v1/products/{productId}/custom-fields

PUT /v1/products/{productId}/custom-fields

Vendor

GET /v1/vendors/{vendorId}/custom-fields

PUT /v1/vendors/{vendorId}/custom-fields/{fieldId}

Organization location

GET /v1/organization-locations/{organizationLocationId}/custom-fields

PUT /v1/organization-locations/{organizationLocationId}/custom-fields/{fieldId}

Inventory location

GET /v1/inventory-locations/{inventoryLocationId}/custom-fields

PUT /v1/inventory-locations/{inventoryLocationId}/custom-fields/{fieldId}

Purchase order

GET /v1/purchase-orders/{purchaseOrderId}/custom-fields

PUT /v1/purchase-orders/{purchaseOrderId}/custom-fields/{fieldId}

Deprecated: The single-field POST, PUT, and DELETE endpoints for patients, orders, and invoices. Use the multi-value PUT above instead.


Search Records by Custom Field Value

Patient, order, and invoice searches accept a custom field filter:

GET /v1/patients?customField.fieldId=CF5201db00b62b525a2b94ca4a7f10dfc1&customField.value=Physician%20referral

Manage Field Definitions

Endpoint

Purpose

POST /v1/custom-fields

Create a field

PUT /v1/custom-fields/{fieldId}

Update a field's name, description, pin, or list items

DELETE /v1/custom-fields/{fieldId}

Delete a field (returns 204 No Content)

POST /v1/custom-fields/{fieldId}/pin

Pin a field

POST /v1/custom-fields/{fieldId}/unpin

Unpin a field

Create a DropDown Field

POST /v1/custom-fields
{
"Type": "Order",
"Name": "Branch",
"Description": "Branch fulfilling the order",
"FieldValueType": "DropDown",
"IsPinned": true,
"FieldListItems": [
{ "Text": "Birmingham" },
{ "Text": "Huntsville" }
]
}

Type is required. To update list items, send them with their Id in FieldListItems. Items without an Id are added.

⚠️ Fields marked IsReadonly can't be changed.


Common Errors

Code

Meaning

400

Invalid request, e.g. a value that doesn't match the field's type, or a field that doesn't belong to that record type

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Record or field not found

429

Too many requests


Related articles

Did this answer your question?