Four values in one example
Imagine a deal field named Customer tier. It has an internal field code, a display label Customer tier, an option labeled Gold, and option ID 123. The v2 request conceptually looks like this:
The field code answers “which field?” The number answers “which option?” The label is used by people and by your mapping interface.
{
"custom_fields": {
"FIELD_CODE_FOR_CUSTOMER_TIER": 123
}
}
Load current options
Retrieve field metadata for the target entity and inspect its options. Do not hard-code IDs copied from another company or another environment. Custom fields are company-specific, and an administrator can add, rename, deactivate, or recreate options.
Store a mapping keyed by a stable business value you control:
Refresh the mapping when the field changes and fail clearly when an incoming value has no active option.
{
"gold": {
"displayLabel": "Gold",
"pipedriveOptionId": 123,
"fieldCode": "REDACTED"
}
}
Single option versus multi-select
The migration guide documents a key v2 difference. A single option is represented by one numeric option ID. Multiple options are represented by an array of numeric IDs. A legacy request may have used a string such as “123,456”; that is not the v2 array.
Test these cases: no value, one value, two values, removal of one value, and clearing all values. The empty representation must be confirmed against the endpoint behavior you use. Do not assume null, empty string, and empty array mean the same thing.
Case and whitespace problems
Incoming labels often contain capitalization or whitespace differences: gold, Gold, and Gold with a trailing space. Decide whether your source mapping is strict or forgiving. A forgiving mapper can trim whitespace and compare case-insensitively, but it should log the original value and normalized value so an upstream data-quality problem is visible.
Never silently map an unknown label to the first option. Send it to review. A wrong category can be more damaging than a failed request because the CRM will look healthy while reports are wrong.
Record type and field ownership checks
Pipedrive does not have Salesforce-style record types, but the same general debugging principle applies: verify that the field belongs to the entity and company used by the token. A deal field cannot be used in a person payload. A field code copied from a test company is not valid for production merely because the labels match.
Before writing, assert entity, company context, field code, field type, and option ID. Keep those assertions close to the API adapter rather than distributing them across workflow nodes.
Read-after-write verification
Use a controlled record to write Gold, retrieve it, and confirm the returned value is 123 or the equivalent current ID. Then retrieve the field metadata and resolve the label. Test a second option and a multi-select combination. This catches the common mistake of putting the value at the root instead of under custom_fields.
If the write returns success but the UI looks unchanged, check whether you updated the correct record, whether the option is inactive, and whether your UI is showing a cached view. The API response and a fresh read should be the first evidence.
Migrating a label-based workflow
Keep labels in your business rules, but translate them at the boundary:
This lets a marketing manager change the display text without forcing developers to edit every workflow, provided the mapping policy handles the change deliberately.
- Receive a label from the source.
- Normalize it according to policy.
- Look up the current option ID.
- Confirm the field type.
- Build the v2 custom_fields object.
- Send the request.
- Verify or queue a retry.
Option lifecycle
When an option is renamed, decide whether it is the same business category or a new one. When it is deactivated, stop sending it and decide how existing records should be handled. When a field is recreated, assume both field code and option IDs may change.
Record the metadata snapshot used for each migration. It gives you an explanation when a report changes after an administrator edits a dropdown.
Validate choices before a bulk import
Before importing thousands of records, sample the incoming labels and compare them with the current option dictionary. Produce three lists: exact matches, normalized matches that need an audit note, and unknown values. Resolve unknown values before sending the bulk job. This prevents a single spelling variation from producing hundreds of failed requests or, worse, a misleading fallback category.
For an existing sync, compare the option dictionary at startup and stop the job if a required option has disappeared. A controlled pause is safer than continuing with partial mappings. If a label was intentionally renamed, update the business mapping and document whether historical records should retain the old option.
Use separate test fields or a test company when experimenting with a new multi-select shape. Test the order of array values if downstream comparisons depend on it, and treat the set as unordered in business logic unless the platform explicitly promises ordering. The API value is a storage representation; the UI label is a presentation.
Keep an audit note for every mapping change, including the old label, new label, option IDs, affected workflow, and reviewer.
That record is especially useful when sales reports depend on historical category meanings over time.
The trap: the label is readable, so developers send it. Pipedrive’s API field may require the numeric option ID, and v2 multi-select values require an array.
Test option lifecycle, not only a successful write
Keep fixtures for an active option, renamed option, deactivated option, unknown label, and multi-select clearing. The expected behavior should be explicit for each case. A mapping that accepts one “Gold” example can still fail after an administrator edits the field. Treat metadata changes as a reviewed deployment input and stop bulk imports when a required option disappears.
Where these facts come from
