Custom fields

In Pipedrive, every custom field has a 40-character hexadecimal hash key instead of a readable name, and those keys are unique to your account. A field you call "Deal Size" might be dcf558aac1ae4e8c4f849ba5e668430d8df9be12 in one company and a completely different hash in another. Dropdown options are stored as numeric IDs, not their labels.

pdcli hides all of that. You discover fields, read them, and write them by their human names — the CLI resolves names to keys and labels to option IDs on every call.

Discover fields

field list <entity> shows every field for an entity, custom fields included, with their hash keys, types, and option labels. Entities: deal, person, org, product, activity, lead, and note. (field get reads the same set; a lead inherits its deal fields, and note exposes the note schema.)

pdcli field list deal

┌──────────────────────────────────────────┬───────────┬──────────┬──────────────────────┐
│ Key                                       │ Name      │ Type     │ Options              │
├──────────────────────────────────────────┼───────────┼──────────┼──────────────────────┤
│ title                                     │ Title     │ varchar  │                      │
│ value                                     │ Value     │ monetary │                      │
│ dcf558aac1ae4e8c4f849ba5e668430d8df9be12  │ Deal Size │ enum     │ Small, Medium, Large │
│ a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2  │ Score     │ double   │                      │
└──────────────────────────────────────────┴───────────┴──────────┴──────────────────────┘

field get <entity> <name|key> shows one field by either its human name or its hash key. For enum/set fields it lists each option's ID next to its label:

pdcli field get deal "Deal Size"
pdcli field get deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12

┌──────────────────────────────────────────┬───────────┬──────┬──────────────────────────┐
│ Key                                       │ Name      │ Type │ Options                  │
├──────────────────────────────────────────┼───────────┼──────┼──────────────────────────┤
│ dcf558aac1ae4e8c4f849ba5e668430d8df9be12  │ Deal Size │ enum │ 12=Small,13=Medium,14=Large │
└──────────────────────────────────────────┴───────────┴──────┴──────────────────────────┘

Managing fields

Beyond discovery, pdcli manages the field schema itself — create a field, rename it, add or drop dropdown options, or delete it. These run on the v2 fields endpoints and cover the writable core entities: deal, person, org, and product. (activity, lead, and note fields are read-only — they show up in field list/field get but can't be created or altered here.)

Every schema change invalidates pdcli's in-process field cache automatically, so the name⇄key and label⇄ID resolution on subsequent writes in the same run picks up the new shape without a manual refresh.

Create a field

--name and --type are required. For an enum or set (multi-select) field, pass the dropdown labels with --options — it's required for those types and ignored for the rest:

pdcli field create deal --name "Budget" --type double
pdcli field create person --name "Tier" --type enum --options "Gold,Silver,Bronze"

The created field is returned with its freshly minted hash Key, so you can pipe it straight into a write:

┌──────────────────────────────────────────┬────────┬──────┬─────────────────────────┐
│ Key                                       │ Name   │ Type │ Options                 │
├──────────────────────────────────────────┼────────┼──────┼─────────────────────────┤
│ a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2  │ Tier   │ enum │ 1=Gold,2=Silver,3=Bronze │
└──────────────────────────────────────────┴────────┴──────┴─────────────────────────┘

Rename a field

field update <entity> <key> renames a field via --name. The field is addressed by its hash key (the field_code from field list); the field_code and field_type themselves can't be changed:

pdcli field update deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12 --name "Deal Value"

Manage dropdown options

For enum/set fields, add and remove options without touching the rest of the schema:

pdcli field option add deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12 --label "Critical"
pdcli field option remove deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12 --option 4

add takes the new label; remove takes the numeric option ID (run field get to see each option's ID next to its label). Removing an option is destructive — records that held that value lose it — so it confirms first; -y/--yes skips the prompt for scripts.

Delete a field

pdcli field delete deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12
pdcli field delete deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12 --yes

Caution

Deleting a field discards the data every record stored in it — there's no undo. The command confirms first and the prompt defaults to No; pass -y/--yes only when you're sure (e.g. in a script).

Reading: names in tables, raw keys in JSON

In table output, custom-field values are shown under their human names, and option IDs are swapped back to their labels. JSON output stays raw — hash keys and numeric option IDs intact — so scripts have something stable to parse.

pdcli deal get 42                 # table: shows "Deal Size: Large"
pdcli deal get 42 --output json   # JSON: custom_fields.{hash}: 14

v2 nests custom-field values under a custom_fields object on the record.

Resolve in JSON too: --resolve-fields

When you want the readable names in machine output as well, opt in with --resolve-fields. It resolves hash keys to names and option IDs to labels in json, yaml, and csv output — matching what the table always shows:

pdcli deal get 1 --output json --resolve-fields

{
  "id": 1,
  "title": "Acme renewal",
  "custom_fields": { "Deal Size": "Large", "Score": 4.5 }
}

This is opt-in: it applies to the get commands and the core list commands (deal, person, org, activity, product — one field-definitions fetch covers the whole list). On lists, resolution affects json/yaml/csv only (list tables don't render custom-field columns); on get, the table view always resolves. If two custom fields share the same name, the second is disambiguated with a short key fragment (e.g. Region (a1b2c3d4)) so neither value is clobbered.

Writing: --field "Name=Value"

On every write command that accepts custom fields (deal, person, org, product, activity — create, update, and deal bulk-update), pass --field "Name=Value". The flag is repeatable, one field per flag:

pdcli deal create --title "Acme renewal" \
  --field "Deal Size=Large" \
  --field "Score=4.5"

What resolution does for you:

• Name to key — Deal Size becomes its 40-char hash. You can also pass the hash key or field_code directly if you prefer.
• Label to option ID — for enum fields, Large becomes the numeric option ID.
• Set (multi-option) fields — give comma-separated labels, each resolved to its ID: --field "Tags=VIP,Renewal".
• Numeric coercion — double, monetary, and int field values are converted to numbers, so Score=4.5 is sent as 4.5, not the string "4.5".
• Custom fields nest under custom_fields; standard fields go at the top level.

When a label is wrong

If you give an option label that doesn't exist, pdcli stops before writing and lists the valid options (exit code 65):

pdcli deal create --title "Sized" --field "Deal Size=Huge"

Error: Unknown option "Huge" for field "Deal Size". Valid: Small, Medium, Large

An unknown field name also fails fast, pointing you at discovery (exit code 65):

Error: Unknown field "Dela Size". Run: pdcli field list <entity>

Same resolution everywhere

The exact same name-and-label resolution runs on single writes (create/update), on deal bulk-update, and on CSV imports — where each CSV header is treated as a field name. So a Deal Size column in your spreadsheet resolves the same way --field "Deal Size=Large" does on the command line.

Raw escape hatch

If you'd rather supply the raw v2 shape yourself, --body takes JSON and typed flags win over it. You'd use the hash keys directly:

pdcli deal create --title "Raw" \
  --body '{"custom_fields":{"dcf558aac1ae4e8c4f849ba5e668430d8df9be12":14}}'