DealFields
Deal fields represent the near-complete schema for a deal in the context of the company of the authorized user. Each company can have a different schema for their deals, with various custom fields. In the context of using deal fields as a schema for defining the data fields of a deal, it must be kept in mind that some types of custom fields can have additional data fields which are not separate deal fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of deal fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one deal and list its keys.
Get all deal fields
Returns metadata about all deal fields in the company.
Cost
10
Request
/api/v2/dealFields
Query parameters
include_fields
string
Optional comma separated string array of additional data namespaces to include in response
Values
ui_visibility
important_fields
required_fields
ui_visibility,important_fields
ui_visibility,required_fields
important_fields,required_fields
ui_visibility,important_fields,required_fields
limit
integer
For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.
cursor
string
For pagination, the marker (an opaque string value) representing the first item on the next page
Response
OK
Expand all
Copy code- true
- [ ... ]▶
- { ... }▶
Get one deal field
Returns metadata about a specific deal field.
Cost
1
Request
/api/v2/dealFields/{field_code}
Path parameters
field_code
string
required
The unique code identifying the field
Query parameters
include_fields
string
Optional comma separated string array of additional data namespaces to include in response
Values
ui_visibility
important_fields
required_fields
ui_visibility,important_fields
ui_visibility,required_fields
important_fields,required_fields
ui_visibility,important_fields,required_fields
Response
OK
Expand allCopy code- true
- { ... }▶
Add a new deal field
Creates a new deal custom field.
Cost
5
Request
/api/v2/dealFields
Body parameters
application/json
field_name
string
required
Field name
field_type
string
required
The type of the field
| Value | Description |
|---|---|
varchar | Text (up to 255 characters) |
varchar_auto | Autocomplete text (up to 255 characters) |
text | Long text (up to 65k characters) |
double | Numeric value |
monetary | Monetary field (has a numeric value and a currency value) |
date | Date (format YYYY-MM-DD) |
set | Options field with a possibility of having multiple chosen options |
enum | Options field with a single possible chosen option |
user | User field (contains a user ID of another Pipedrive user) |
org | Organization field (contains an organization ID which is stored on the same account) |
people | Person field (contains a person ID which is stored on the same account) |
phone | Phone field (up to 255 numbers and/or characters) |
time | Time field (format HH:MM:SS) |
timerange | Time-range field (has a start time and end time value, both HH:MM:SS) |
daterange | Date-range field (has a start date and end date value, both YYYY-MM-DD) |
address | Address field |
Values
varchar
text
double
phone
date
daterange
time
timerange
set
enum
varchar_auto
address
monetary
org
people
user
options
array
Field options (required for enum and set field types)
label
string
required
The option label
ui_visibility
object
UI visibility settings for the field. Controls where the field appears in the Pipedrive web UI.
add_visible_flag
boolean
Whether the field is shown in the add deal modal. Default is false. Cannot be set to false for required system fields (title, pipeline, stage_id, probability).
details_visible_flag
boolean
Whether the field is shown in the deal details view. Default is true.
Default
true
projects_detail_visible_flag
boolean
Whether the field is shown in the project details view when the deal is linked to a project. Default is false.
show_in_pipelines
object
Controls which pipelines display this field. Default is show_in_all=true. Note that fields marked as important or required must be visible in the pipelines where they are configured.
show_in_all
boolean
When true, the field is visible in all pipelines. When false, visibility is controlled by pipeline_ids. Default is true.
Default
true
pipeline_ids
array
Array of pipeline IDs where the field should be visible. Only used when show_in_all is false. Must reference valid, active pipelines.
important_fields
object
Configuration for highlighting the field at specific stages.
enabled
boolean
Whether the field is marked as important. When false, the field is not highlighted. When true with empty stage_ids, the field is important everywhere. When true with specific stage_ids, the field is important only at those stages. Default is false.
stage_ids
array
Array of deal stage IDs where this field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false. The stages must be in pipelines where this field is visible (show_in_pipelines).
Default
required_fields
object
Required fields configuration for marking the field as mandatory when interacted with in the Pipedrive web UI.
enabled
boolean
Whether the field is required. When false, the field is optional. When true with empty stage_ids, the field is required everywhere. When true with specific stage_ids, the field is required only at those stages. Default is false.
stage_ids
array
Array of deal stage IDs where this field is required. Must reference valid, active deal stages. Empty array when enabled is false. The stages must be in pipelines where this field is visible (show_in_pipelines).
Default
statuses
object
Pipeline-specific status requirements for when deals are won or lost. Keys are pipeline IDs (as strings), values are arrays of status strings ('won', 'lost'). Example - {"1":["won","lost"],"2":["won"]} means the field is required when marking deals as won or lost in pipeline 1, and only when won in pipeline 2. Must reference valid, active pipelines.
Default
[object Object]
description
string
Field description
Response
OK
Expand allCopy code- true
- { ... }▶
Add deal field options in bulk
Adds new options to a deal custom field that supports options (enum or set field types). This operation is atomic - all options are added or none are added. Returns only the newly added options.
Cost
5
Request
/api/v2/dealFields/{field_code}/options
Path parameters
field_code
string
required
The unique code identifying the field
Body parameters
application/json
[ ]
array
Array of options to add. Each item must contain a label. At least one option is required.
label
string
required
The display label for the new option
Response
OK
Expand allCopy code- true
- [ ... ]▶
- null
Update a deal field
Updates a deal custom field. The field_code and field_type cannot be changed. At least one field must be provided in the request body.
Cost
5
Request
/api/v2/dealFields/{field_code}
Path parameters
field_code
string
required
The unique code identifying the field
Body parameters
application/json
field_name
string
Field name
ui_visibility
object
UI visibility settings for the field. Controls where the field appears in the Pipedrive web UI.
add_visible_flag
boolean
Whether the field is shown in the add deal modal. Default is false. Cannot be set to false for required system fields (title, pipeline, stage_id, probability).
details_visible_flag
boolean
Whether the field is shown in the deal details view. Default is true.
Default
true
projects_detail_visible_flag
boolean
Whether the field is shown in the project details view when the deal is linked to a project. Default is false.
show_in_pipelines
object
Controls which pipelines display this field. Default is show_in_all=true. Note that fields marked as important or required must be visible in the pipelines where they are configured.
show_in_all
boolean
When true, the field is visible in all pipelines. When false, visibility is controlled by pipeline_ids. Default is true.
Default
true
pipeline_ids
array
Array of pipeline IDs where the field should be visible. Only used when show_in_all is false. Must reference valid, active pipelines.
important_fields
object
Configuration for highlighting the field at specific stages.
enabled
boolean
Whether the field is marked as important. When false, the field is not highlighted. When true with empty stage_ids, the field is important everywhere. When true with specific stage_ids, the field is important only at those stages. Default is false.
stage_ids
array
Array of deal stage IDs where this field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false. The stages must be in pipelines where this field is visible (show_in_pipelines).
Default
required_fields
object
Required fields configuration for marking the field as mandatory when interacted with in the Pipedrive web UI.
enabled
boolean
Whether the field is required. When false, the field is optional. When true with empty stage_ids, the field is required everywhere. When true with specific stage_ids, the field is required only at those stages. Default is false.
stage_ids
array
Array of deal stage IDs where this field is required. Must reference valid, active deal stages. Empty array when enabled is false. The stages must be in pipelines where this field is visible (show_in_pipelines).
Default
statuses
object
Pipeline-specific status requirements for when deals are won or lost. Keys are pipeline IDs (as strings), values are arrays of status strings ('won', 'lost'). Example - {"1":["won","lost"],"2":["won"]} means the field is required when marking deals as won or lost in pipeline 1, and only when won in pipeline 2. Must reference valid, active pipelines.
Default
[object Object]
description
string
Field description
Response
OK
Expand allCopy code- true
- { ... }▶
Update deal field options in bulk
Updates existing options for a deal custom field. This operation is atomic and fails if any of the specified option IDs do not exist. Returns only the updated options.
Cost
5
Request
/api/v2/dealFields/{field_code}/options
Path parameters
field_code
string
required
The unique code identifying the field
Body parameters
application/json
[ ]
array
Array of options to update. Each item must contain an ID and the updated label. At least one option is required. The entire request fails if any option does not exist.
id
integer
required
The unique identifier of the option to update
label
string
required
The new display label for the option
Response
OK
Expand allCopy code- true
- [ ... ]▶
- null
Delete multiple deal fields in bulk
Marks multiple deal fields as deleted.
Cost
10
Request
/api/v1/dealFields
Query parameters
ids
string
required
The comma-separated field IDs to delete
Response
OK
Expand allCopy code- true
- { ... }▶
Delete deal field options in bulk
Removes existing options from a deal custom field. This operation is atomic and fails if any of the specified option IDs do not exist. Returns only the deleted options.
Cost
3
Request
/api/v2/dealFields/{field_code}/options
Path parameters
field_code
string
required
The unique code identifying the field
Body parameters
application/json
[ ]
array
Array of option IDs to delete. Each item must contain an ID of the option to delete. At least one option ID is required. The entire request fails if any option does not exist.
id
integer
required
The unique identifier of the option to delete
Response
OK
Expand allCopy code- true
- [ ... ]▶
- null
Delete a deal field
Marks a custom field as deleted.
Cost
3
Request
/api/v2/dealFields/{field_code}
Path parameters
field_code
string
required
The unique code identifying the field
Response
OK
Expand allCopy code- true
- { ... }▶