Field Value Formats

Every process field value has two properties:

if_text - the text people see on screens, in emails and in merge documents.
if_value - what ProcessPlan stores to identify, compare and calculate with. For a dropdown that is the option’s id. For a number it is the plain number.

When you start a process or save fields through the API, you send a list of field objects. Each one names its field with if_tf_id and carries the value in the format its field type expects:

{
  "process_instance_field_list": [
    { "if_tf_id": "123456789012345678", "if_text": "Jane Buyer" },
    { "if_tf_id": "123456789012345679", "if_value": "2400" },
    { "if_tf_id": "123456789012345680", "if_value": "123456789012013001;123456789012013002" }
  ]
}

These formats apply to every request that writes field values: starting a process, saving fields on a running process, and submitting a public form. Each field’s type is its tf_type number, listed under field_display_types_enum in Enumerables and Constants. GET /process_template_header/##/process_instance_field/list/start lists the fields a new process of that template starts with, including their ids.

General rules

Lists are separated by semicolons. Use a bare ; between ids in if_value (id;id) and ; between names in if_text (Photo Signboard; Flag Holder). A comma is not a separator: id,id is read as one value that matches nothing.
For choice, people and lookup fields, you can send just one property. Send the ids in if_value and leave if_text empty, and ProcessPlan fills in the names. Sending ids alone also means a misspelled name can never reach your records.
Some types rebuild if_text from if_value. Numbers, percentages, dates and times are shown in the field’s or account’s format, so any text you send for them is replaced.
The field’s own settings still apply. A start is refused when it leaves a required field empty. Any write is refused when a value fails the field’s validation formula, falls outside its minimum and maximum, or repeats a value in a field set to be unique.
Trim your text. Automations compare whole text answers including spaces at the start and end (see How automations read field values).

Formats by field type

Text

Field type (`tf_type`)	`if_value`	`if_text`
Text (Single Line) (300)	empty	the text
Text (Multiline) (301, 303, 386)	empty	the text, line breaks as `\n`
E-Signature (356)	empty	the signer’s typed name, shown as a signature in merge documents
Password (379)	empty	the password

If you send only if_value for a text field, ProcessPlan copies it into if_text.

Numbers

Field type (`tf_type`)	`if_value`	`if_text`
Number (304)	the plain number, such as `2400` or `1250.5`, with no currency symbol or thousands separator	rebuilt in the field’s format, such as `$2,400`
Percent (371)	the fraction, so `0.0275` for 2.75%	rebuilt, such as `2.75%`
Rating (425)	a whole number within the field’s scale (1 to 5 unless the field sets another)	rebuilt

A rating with decimals is rounded to the nearest whole number. A Percent field sent with only if_text reads that text as a whole percentage, so 2.75 is stored as 2.75%.

Dates and times

Field type (`tf_type`)	`if_value`	`if_text`
Date (308)	`2026-06-03`	rebuilt in the account’s date format
Time (354)	an ISO 8601 date and time with its offset, such as `2000-01-01T14:00:00.000+10:00` (only the time of day is used)	rebuilt, such as `2:00 PM`
Date/Time (376)	an ISO 8601 date and time with its offset, such as `2026-12-12T09:00:00.000+10:00`	rebuilt in the account’s date and time format

Always include the offset on a Time or Date/Time value. Without it, the time can be read in a different time zone from the one you meant.

Choices

Field type (`tf_type`)	`if_value`	`if_text`
Dropdown (305)	the option’s id	the option’s name, or empty
Radio Button (307)	the option’s id	the option’s name, or empty
Checklist (306)	the ticked options’ ids, separated by `;`	the names separated by `;` , or empty

Option ids are listed by GET /process_template_field/##/process_template_field_option/list. If you send only if_text, ProcessPlan looks for an option with that name. A name that matches no option is kept as text with no option id, so automations treat the field as if nothing were chosen.

People

Field type (`tf_type`)	`if_value`	`if_text`
User List (Limited) (314), User List (Lookup) (363)	the user’s id	the user’s full name, or empty
User List (Multiple) (368)	the users’ ids, separated by `;`	the names separated by `;` , or empty
User Group List (373)	the group’s id	the group’s name, or empty
User Role List (374)	the role’s id	the role’s name, or empty

For a user field you can instead send only if_text, holding the person’s email address or full name, and ProcessPlan finds the user.

Process table lookups

Field type (`tf_type`)	`if_value`	`if_text`
Process Table Lookup (Single) (360), Process Table Radio Buttons (389)	the record’s id	the record’s name, or empty
Process Table Lookup (Multiple) (377), Process Table Checklist (362)	the records’ ids, separated by `;`	the names separated by `;` , or empty

When you send ids only, ProcessPlan fills if_text with each record’s name. If you send only if_text, it looks for a record with that name among the records the field offers.

Email addresses and links

Field type (`tf_type`)	`if_value`	`if_text`
Email Address (310)	empty	one or more addresses, separated by `;`
URL (311)	empty	the address

ProcessPlan stores email addresses as [email protected]; [email protected]. A URL without http:// or https:// gets https:// added in front.

Files

File Attachment (312) and Signature Canvas (399) fields hold files rather than text. Upload each file with the file endpoints in API Endpoints and attach it to the field. ProcessPlan then sets the field’s if_text to the file names.

Set by ProcessPlan

Conversation (424) - send new text in if_text to add an entry. Sending the newest entry’s text again adds nothing. ProcessPlan keeps the field’s properties itself, and earlier entries are never changed.
Merge Document Link (370) - built from the field’s document template. Anything you send is replaced.
Fields with a value formula - ProcessPlan works the value out, so don’t rely on writing it yourself.

For a field type not listed on this page, read a value the ProcessPlan screens saved (GET /process_instance_header/##/process_instance_field/list) and write yours in the same shape.

How automations read field values

Automation conditions read one property or the other depending on the field type. A value written in the wrong place can make a condition fail even though the field looks right on screen.

Choice and user fields are matched on the ids in if_value. The names never change a condition’s outcome, but they are what people see in emails, documents and task screens.
Lookups are matched on the record id, or on the record’s name when the condition was written with text.
Text is matched on if_text. “Contains” ignores capitals. “Equals” ignores capitals but compares the whole text, spaces included, so Head Office (with a trailing space) does not equal Head Office.
Numbers and percentages are matched on if_value. A currency symbol or comma in if_value stops a number comparison from matching.
Dates are matched on the date, and times on the time of day. The offset you send decides which date and time those are.