Retrieve custom field values from work order via API

Question

Hey all — working on an integration that pulls work order data into our internal dashboard, and I'm hitting a wall with custom fields.

Here's what I'm seeing: when I hit GET /v1/work_orders/{id} , the response includes custom_fields as an array of objects, but the values are coming back as IDs rather than the actual data. For example:

{
 "custom_fields": [
 {
 "field_id": "cf_abc123",
 "value": "opt_456"
 }
 ]
}

I'm expecting to see the human-readable value (like "Commercial" or whatever was selected), not an opaque ID. Is there a way to get the expanded values in the same call? I checked the docs but didn't see an obvious expand parameter for this.

What I'm ultimately trying to build: a unified view that shows standard work order data alongside our custom fields without making N+1 API calls to resolve each field reference. Worth noting that some of these are dropdown fields, others are text — so the data types vary.

YMMV but hoping someone has solved this already.

Leo Nakamura · Accepted Answer

Use ?expand=custom_fields query parameter.

Returns resolved values:

{
 "custom_fields": [
 {
 "field_id": "cf_abc123",
 "field_name": "Job Type",
 "field_type": "dropdown",
 "value": "Commercial",
 "value_id": "opt_456"
 }
 ]
}

Docs: Using the FieldPulse API

Omar Hassan · Answer

Worth noting that the expansion behavior differs slightly for multi-select fields (i.e., fields allowing multiple values). In those cases, value returns an array of selected options rather than a single string, and value_id becomes an array as well.

Example:

{
 "field_id": "cf_def789",
 "field_name": "Required Certifications",
 "field_type": "multiselect",
 "value": ["HVAC", "Electrical", "Safety"],
 "value_id": ["opt_001", "opt_003", "opt_007"]
}

This is documented in the API reference under "Custom Field Types" but easy to miss if you're only testing with single-value fields. I'd recommend explicitly testing with each field type your organization uses, as the schema variation can affect deserialization logic in strictly-typed languages.