Reference

Custom fields

Friendly, snake_case keys for the FieldInsight custom fields your integration is allowed to read and write.

Custom fields are referenced by a stable external name like scope_of_work. The available names are configured per integration — only mapped fields are accepted. The set may be restricted to specific job types.

Common uses

Custom fields are the right home for anything that doesn’t fit one of the standard fields. In practice they’re used for:

Completion details the tech captures on site — work performed, parts replaced, readings taken, defects found.
Specific request data — asset or serial numbers, model identifiers, batch references.
Scheduling context the office needs up front — site contact details, access window, equipment status, dispatch instructions.
Cross-system tracking — your work-order, ticket, or shipment tracking number so records line up across both sides.

If a field you need isn’t in /v1/custom-fields, contact us — adding a new mapping is a quick configuration change on our side.

Discover what you can send

GET /v1/custom-fields returns the full set of fields you can use.

curl -H "Authorization: Bearer fi_pk_…" https://<host>/v1/custom-fields

{
  "items": [
    {
      "external_name": "scope_of_work",
      "fi_field_id": "349661",
      "job_type_id": null
    },
    {
      "external_name": "site_contact_phone",
      "fi_field_id": "349662",
      "job_type_id": "29400"
    }
  ]
}

job_type_id: null means the field can be used on any job type. job_type_id: "29400" means the field can only be used on jobs of that type — sending it on another type returns 400 unknown-custom-field.

Reading custom fields

On GET /v1/jobs, custom fields appear keyed by their friendly name:

"custom_fields": { "scope_of_work": "Install" }

Writing custom fields

On POST / PATCH, send the same shape. Unknown keys are rejected with 400 unknown-custom-field rather than silently dropped, so you’ll know immediately if a field name is wrong or out of scope.

"custom_fields": { "scope_of_work": "Install + commissioning" }

Values are strings on the wire regardless of how the underlying field is configured. If you need a number or date, format it consistently on your side.