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 |
Value | The field's value on a specific record |
List item | An option in a |
Record Types (Type)
Patient, Order, Invoice, Product, Vendor, OrganizationLocation, InventoryLocation, PurchaseOrder
Value Types (FieldValueType)
Type | Value to send |
| A string |
| A number |
|
|
|
|
| A list item (see DropDown fields) |
| A URL |
Find Your Custom Fields
GET /v1/custom-fields
Filter | Notes |
| Record type, e.g. |
| e.g. |
| Partial or exact name match |
|
|
|
|
|
|
|
|
| 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 |
|
|
Order |
|
|
Invoice |
|
|
Product |
|
|
Vendor |
|
|
Organization location |
|
|
Inventory location |
|
|
Purchase order |
|
|
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 |
| Create a field |
| Update a field's name, description, pin, or list items |
| Delete a field (returns |
| Pin a field |
| 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 |
| 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 |
| Token missing, expired, or invalid |
| You don't have permission to access this resource |
| Record or field not found |
| Too many requests |
