The identifiers side by side
| Value | Example form | Purpose | |---|---|---| | Record ID | 12345 | Selects the deal/person/resource | | Field code | Long opaque string | Selects the custom field | | Field ID | Numeric metadata value in older contexts | Legacy or metadata reference; do not assume it is the v2 property key | | Option ID | 123 | Selects one dropdown choice | | Display label | Customer tier | Human-readable UI text |
The safest mapping stores these in separate named properties. A generic variable called id invites the wrong value to be inserted into a URL or JSON body.
What changed in v2
Pipedrive’s migration guide documents v2 field endpoints such as GET /api/v2/dealFields/:field_code. It also says custom fields are moved into a separate custom_fields object. These are related changes: the field metadata route identifies the field with its code, while the entity payload uses that same code as the custom_fields key.
Conceptually:
and:
The number 123 is an example option ID. It does not identify the field.
{
"custom_fields": {
"YOUR_FIELD_CODE": 123
}
}
How to retrieve the right field
List fields for the target entity, then match by display name only as a lookup step. Save the returned field code, type, active state, and options. If duplicate labels exist, do not pick the first match; require an administrator to disambiguate by entity and metadata.
A field dictionary should be scoped by company and entity:
Never share a field dictionary across Pipedrive companies without checking it. Two companies can create fields with the same label and different codes.
{
"company": "COMPANY_CONTEXT",
"entity": "deal",
"label": "Customer tier",
"field_code": "REDACTED",
"type": "enum"
}
Why old query strings fail
An old integration may build a URL with field_id because its v1 endpoint accepted that parameter or because the developer copied a response property. In v2, the endpoint expects the documented field_code route or query parameter. A request can authenticate correctly and still fail validation because the identifier is in the wrong place.
Search the codebase for field_id, field_code, custom_fields, and every hard-coded long key. Review query builders as well as JSON serializers. Many migrations update the body but leave a filtering query that still uses the old identifier.
Option IDs need a second lookup
For an enum field, the field code answers “which field?” and the option ID answers “which choice?” Fetch options from field metadata and map labels at the edge of your system. Store the chosen ID, not the label, in the outbound v2 payload.
For a multi-select field, v2 uses an array of numeric option IDs. A legacy comma-separated string is not the same type. Test zero, one, and several selected options, plus clearing the field, because empty-array behavior should be verified against the endpoint documentation.
Read-after-write verification
Create a test record with one known option, fetch it, and assert three things: the record ID is correct, the custom field appears under custom_fields, and the returned value matches the expected numeric option. Then test a text field and a currency field separately. A single successful enum test does not prove that all field shapes are correct.
If the field disappears from the response, check whether it is empty, omitted by the endpoint, inaccessible to the token, or not part of the entity. Use field metadata and permissions to separate those cases.
Safer application interfaces
Avoid accepting this:
Prefer an explicit structure:
At the adapter boundary, translate friendly application names into verified Pipedrive codes. This keeps business code readable without pretending that a friendly name is a platform identifier.
updateDeal({
dealId: 123,
customFields: {
customerTierFieldCode: 456
}
})
Migration checklist
Inventory all field IDs and codes. Retrieve current metadata. Confirm each target entity. Update v2 paths. Move custom fields under custom_fields. Convert enum values to numeric option IDs and multi-select values to arrays. Send numbers as numbers. Test create and PATCH update separately. Verify the response and run the same test from the actual automation tool.
Plan for field recreation. If an administrator deletes and recreates a field, the display label can remain unchanged while the code changes. Alert on a missing code and require a deliberate mapping update.
Debug the URL, body, and metadata independently
When a field request fails, separate the three identifiers involved. First confirm the record ID by fetching the record directly. Next confirm the field code by retrieving metadata for that entity and company. Finally confirm the option ID or value type. Testing all three at once makes it easy to change the correct part for the wrong reason.
Keep a redacted diagnostic record containing entity, record ID, field code prefix and suffix, field type, option ID, endpoint, and response status. The prefix and suffix help detect accidental truncation without storing an entire sensitive mapping in an ordinary log. If you support multiple companies, include the connection identifier so a valid code from one tenant is not mistaken for a valid code everywhere.
During a v1-to-v2 cutover, run a fixture test for text, number, currency, single option, and multi-option fields. Assert both the outgoing shape and the read-after-write result. This catches a migration that changes the property name correctly but leaves the value encoded as a legacy string.
The trap: using the correct option ID as the property name. The request must use the field code as the key and the option ID as the value.
Debug the identifier at three boundaries
Record the identifier before mapping, after serialization, and in the final URL or JSON body. The first value should be the application’s friendly field reference, the second should be the verified field code, and the third should be the exact value sent to Pipedrive. Comparing these boundaries catches a mapper that correctly loads metadata but later substitutes a numeric field ID or option ID.
Where these facts come from
