Three identifiers people mix up
| Identifier | What it means | Where it belongs | |---|---|---| | Display name | Human-readable label | UI and documentation for people | | Field key/code | API-facing custom-field identifier | custom_fields object or v2 field path | | Option ID | Numeric choice inside a dropdown/multi-select | The field value, not the field name |
For example, a field may be displayed as “Customer tier,” have an opaque field code, and contain an option ID of 123 for “Gold.” Sending Gold to a field that expects 123 is a value error. Sending 123 as the field key is a field-identity error.
Find the key in the Pipedrive interface
The exact labels can change as Pipedrive updates its settings UI, but the workflow is consistent:
Copying matters because opaque keys are easy to mistype. Compare the beginning and end of the key after pasting it, and check for hidden whitespace if the request still fails.
- Open the company’s settings.
- Go to the data-field or custom-field area.
- Choose the entity type: deal, person, organization, product, or activity.
- Locate the field by its display name.
- Open its details and use the copy API key control if shown.
- Store the copied value in your integration configuration, not in a workflow node that every editor can accidentally change.
Find fields through the API
For an API-driven setup, list the fields for the entity and search the response by name, then save its API-facing code. A representative v2 request is:
Use the endpoint reference for the entity you need. The v2 migration guide documents field resources such as dealFields, personFields, and organizationFields, and shows field-specific routes using field_code. Treat the returned object as the source of truth rather than deriving an identifier from the field label.
When you find a match, record at least the code, field type, whether it is active, and its options. A production integration should fail clearly if the field is missing instead of silently writing nothing.
GET https://api.pipedrive.com/api/v2/dealFields
Authorization: Bearer YOUR_TOKEN
Put the key in a v2 payload correctly
Custom fields are nested under custom_fields in v2. A text field can use the field code as the property name and the text as its value. A currency field uses a value/currency object. The correct shape depends on the field type.
Single-option fields use a numeric option ID; multi-option fields use an array of numeric option IDs. A date field uses a date string in the documented format. Do not copy the JSON shape from a different field type just because the key looks similar.
Why a correct-looking key still fails
First, confirm the entity. A deal field cannot be placed in a person payload. Second, confirm that the field is active and belongs to the same Pipedrive company as the token. Third, confirm the value type. JSON “12500” is a string; JSON 12500 is a number. V2 validation is stricter and does not rely on implicit coercion.
Fourth, check whether the field is a special type. Address, monetary, range, time, and multi-select fields can use nested values. Fifth, verify that your workflow did not rename the property during mapping. A node that changes YOUR_FIELD_CODE into your_field_code has changed the key.
A practical field dictionary
Keep a small version-controlled dictionary for integration code:
Do not commit a real access token or personal customer data. Refresh this dictionary when a field is recreated, because a new field can have a new key even when the label is identical.
{
"deal": {
"customer_tier": {
"field_code": "REDACTED_FIELD_CODE",
"type": "enum",
"options_loaded_at": "2026-09-12"
}
}
}
Verify the key with a read-after-write test
The fastest reliable check is a controlled record in a test or staging company. Write a distinctive value, retrieve the record, and inspect the exact location where v2 returns the field. For a currency field, verify both the numeric value and currency. For an option field, verify the option ID and the human label returned by the field metadata. Then clear the test value using the documented method.
Run this test after a field is edited in the UI, after an integration is moved between companies, and after changing from v1 to v2. A copied key can be syntactically valid but belong to another company. Comparing the field’s entity, code, type, and options catches that mistake before real customers are affected.
If the field does not appear in a read response, distinguish “not selected,” “empty,” and “not available to this credential.” Log the response shape without customer values and inspect permissions separately. That avoids wasting time changing a correct key when the actual problem is access.
Naming and maintenance rules
Give the field a clear human label, but never use that label as a machine identifier. Keep the code in one configuration layer, review changes like code, and record who approved a field replacement. If a team deletes and recreates a field, the replacement may look identical in the interface while having a different API key. A small change log prevents an old integration from writing to a retired field for weeks.
Include the entity name in every mapping note so a future reader cannot mistake a deal field for a person field.
The trap: an option ID is not the field key. If “Gold” has option ID 123, the request still needs the opaque field code as the property name and 123 as its value.
What a production field dictionary should prove
For each mapping, retain company context, entity, field code, field type, active state, option snapshot, last refresh, and owner. A label alone is not an adequate migration record because it can survive field deletion and recreation. On a mismatch, show the code prefix and suffix and ask for metadata confirmation instead of publishing the entire opaque key into an ordinary support ticket.
Where these facts come from
