openapi: 3.0.1 info: title: Pipedrive API v1 Activities DealFields API version: 1.0.0 description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time. ' servers: - url: https://api.pipedrive.com/v1 tags: - name: DealFields description: '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. ' paths: /dealFields: get: summary: Get all deal fields description: Returns data about all deal fields. x-token-cost: 20 operationId: getDealFields parameters: - in: query name: start description: Pagination start schema: type: integer default: 0 - in: query name: limit description: Items shown per page schema: type: integer tags: - DealFields security: - api_key: [] - oauth2: - deals:read - deals:full - deal-fields:full - admin responses: '200': description: Success content: application/json: schema: title: GetFieldsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - title: FieldsResponse - type: object properties: data: type: array items: type: object title: GetField allOf: - title: Field type: object properties: id: type: integer nullable: true description: The ID of the field. Value is `null` in case of subfields. key: type: string description: The key of the field. For custom fields this is generated upon creation. name: type: string description: The name of the field order_nr: type: integer description: The order number of the field field_type: allOf: - type: string enum: - address - date - daterange - double - enum - monetary - org - people - phone - set - text - time - timerange - user - varchar - varchar_auto - visible_to description: The type of the field
ValueDescription
`address`Address field
`date`Date (format YYYY-MM-DD)
`daterange`Date-range field (has a start date and end date value, both YYYY-MM-DD)
`double`Numeric value
`enum`Options field with a single possible chosen option
`monetary`Monetary field (has a numeric value and a currency value)
`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)
`set`Options field with a possibility of having multiple chosen options
`text`Long text (up to 65k characters)
`time`Time field (format HH:MM:SS)
`timerange`Time-range field (has a start time and end time value, both HH:MM:SS)
`user`User field (contains a user ID of another Pipedrive user)
`varchar`Text (up to 255 characters)
`varchar_auto`Autocomplete text (up to 255 characters)
`visible_to`System field that keeps item's visibility setting
add_time: type: string format: date-time description: The creation time of the field update_time: type: string format: date-time nullable: true description: The update time of the field last_updated_by_user_id: type: integer nullable: true description: The ID of the user who created or most recently updated the field, only applicable for custom fields created_by_user_id: type: integer nullable: true description: The ID of the user who created the field active_flag: type: boolean description: The active flag of the field edit_flag: type: boolean description: The edit flag of the field index_visible_flag: type: boolean description: Not used details_visible_flag: type: boolean description: Not used add_visible_flag: type: boolean description: Not used important_flag: type: boolean description: Not used bulk_edit_allowed: type: boolean description: Whether or not the field of an item can be edited in bulk searchable_flag: type: boolean description: Whether or not items can be searched by this field filtering_allowed: type: boolean description: Whether or not items can be filtered by this field sortable_flag: type: boolean description: Whether or not items can be sorted by this field mandatory_flag: type: boolean description: Whether or not the field is mandatory options: type: array nullable: true items: type: object description: The options of the field. When there are no options, `null` is returned. options_deleted: type: array items: type: object description: The deleted options of the field. Only present when there is at least 1 deleted option. is_subfield: type: boolean description: Whether or not the field is a subfield of another field. Only present if field is subfield. subfields: type: array items: type: object description: The subfields of the field. Only present when the field has subfields. - type: object properties: field_type: type: string enum: - boolean - double - int - json - date - daterange - time - timerange - text - varchar - varchar_auto - varchar_options - address - enum - monetary - phone - set - activity - deal - lead - org - people - pipeline - product - project - stage - user - billing_frequency - picture - price_list - projects_board - projects_phase - status - visible_to description: List of all possible field types additional_data: description: The additional data of the list type: object properties: start: type: integer description: Pagination start limit: type: integer description: Items shown per page more_items_in_collection: type: boolean description: If there are more list items in the collection than displayed or not example: success: true data: - id: 1 key: title name: Title order_nr: 2 field_type: varchar add_time: '2019-02-04 13:58:03' update_time: '2019-02-04 13:58:03' last_updated_by_user_id: 1 created_by_user_id: 1 active_flag: true edit_flag: false index_visible_flag: true details_visible_flag: true add_visible_flag: true important_flag: false bulk_edit_allowed: true searchable_flag: false filtering_allowed: true sortable_flag: true options: null mandatory_flag: true - id: 2 key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e name: Customer Type order_nr: 1 field_type: enum add_time: '2019-02-04 13:58:03' update_time: '2019-02-04 13:58:03' last_updated_by_user_id: 1 created_by_user_id: 1 active_flag: true edit_flag: true index_visible_flag: true details_visible_flag: true add_visible_flag: false important_flag: false bulk_edit_allowed: true searchable_flag: false filtering_allowed: true sortable_flag: true options: - id: 190 label: Private person - id: 191 label: Company - id: 192 label: Government mandatory_flag: true additional_data: pagination: start: 0 limit: 100 more_items_in_collection: false post: summary: Add a new deal field description: Adds a new deal field. For more information, see the tutorial for adding a new custom field. x-token-cost: 10 operationId: addDealField tags: - DealFields security: - api_key: [] - oauth2: - deal-fields:full - admin requestBody: content: application/json: schema: title: createFieldRequest allOf: - type: object required: - name properties: name: type: string description: The name of the field options: type: array items: type: object description: 'When `field_type` is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. Example: `[{"label":"New Item"}]`' add_visible_flag: type: boolean default: true description: Whether the field is available in the 'add new' modal or not (both in the web and mobile app) - type: object required: - field_type properties: field_type: type: string enum: - address - date - daterange - double - enum - monetary - org - people - phone - set - text - time - timerange - user - varchar - varchar_auto - visible_to description: The type of the field
ValueDescription
`address`Address field
`date`Date (format YYYY-MM-DD)
`daterange`Date-range field (has a start date and end date value, both YYYY-MM-DD)
`double`Numeric value
`enum`Options field with a single possible chosen option
`monetary`Monetary field (has a numeric value and a currency value)
`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)
`set`Options field with a possibility of having multiple chosen options
`text`Long text (up to 65k characters)
`time`Time field (format HH:MM:SS)
`timerange`Time-range field (has a start time and end time value, both HH:MM:SS)
`user`User field (contains a user ID of another Pipedrive user)
`varchar`Text (up to 255 characters)
`varchar_auto`Autocomplete text (up to 255 characters)
`visible_to`System field that keeps item's visibility setting
responses: '200': description: Success content: application/json: schema: title: GetFieldResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: GetField allOf: - title: Field type: object properties: id: type: integer nullable: true description: The ID of the field. Value is `null` in case of subfields. key: type: string description: The key of the field. For custom fields this is generated upon creation. name: type: string description: The name of the field order_nr: type: integer description: The order number of the field field_type: allOf: - type: string enum: - address - date - daterange - double - enum - monetary - org - people - phone - set - text - time - timerange - user - varchar - varchar_auto - visible_to description: The type of the field
ValueDescription
`address`Address field
`date`Date (format YYYY-MM-DD)
`daterange`Date-range field (has a start date and end date value, both YYYY-MM-DD)
`double`Numeric value
`enum`Options field with a single possible chosen option
`monetary`Monetary field (has a numeric value and a currency value)
`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)
`set`Options field with a possibility of having multiple chosen options
`text`Long text (up to 65k characters)
`time`Time field (format HH:MM:SS)
`timerange`Time-range field (has a start time and end time value, both HH:MM:SS)
`user`User field (contains a user ID of another Pipedrive user)
`varchar`Text (up to 255 characters)
`varchar_auto`Autocomplete text (up to 255 characters)
`visible_to`System field that keeps item's visibility setting
add_time: type: string format: date-time description: The creation time of the field update_time: type: string format: date-time nullable: true description: The update time of the field last_updated_by_user_id: type: integer nullable: true description: The ID of the user who created or most recently updated the field, only applicable for custom fields created_by_user_id: type: integer nullable: true description: The ID of the user who created the field active_flag: type: boolean description: The active flag of the field edit_flag: type: boolean description: The edit flag of the field index_visible_flag: type: boolean description: Not used details_visible_flag: type: boolean description: Not used add_visible_flag: type: boolean description: Not used important_flag: type: boolean description: Not used bulk_edit_allowed: type: boolean description: Whether or not the field of an item can be edited in bulk searchable_flag: type: boolean description: Whether or not items can be searched by this field filtering_allowed: type: boolean description: Whether or not items can be filtered by this field sortable_flag: type: boolean description: Whether or not items can be sorted by this field mandatory_flag: type: boolean description: Whether or not the field is mandatory options: type: array nullable: true items: type: object description: The options of the field. When there are no options, `null` is returned. options_deleted: type: array items: type: object description: The deleted options of the field. Only present when there is at least 1 deleted option. is_subfield: type: boolean description: Whether or not the field is a subfield of another field. Only present if field is subfield. subfields: type: array items: type: object description: The subfields of the field. Only present when the field has subfields. - type: object properties: field_type: type: string enum: - boolean - double - int - json - date - daterange - time - timerange - text - varchar - varchar_auto - varchar_options - address - enum - monetary - phone - set - activity - deal - lead - org - people - pipeline - product - project - stage - user - billing_frequency - picture - price_list - projects_board - projects_phase - status - visible_to description: List of all possible field types example: success: true data: id: 2 key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e name: Customer Type order_nr: 1 field_type: enum add_time: '2019-02-04 13:58:03' update_time: '2019-02-04 13:58:03' last_updated_by_user_id: 1 created_by_user_id: 1 active_flag: true edit_flag: true index_visible_flag: true details_visible_flag: true add_visible_flag: false important_flag: false bulk_edit_allowed: true searchable_flag: false filtering_allowed: true sortable_flag: true options: - id: 190 label: Private person - id: 191 label: Company - id: 192 label: Government mandatory_flag: true delete: summary: Delete multiple deal fields in bulk description: Marks multiple deal fields as deleted. x-token-cost: 10 operationId: deleteDealFields tags: - DealFields security: - api_key: [] - oauth2: - deal-fields:full - admin parameters: - in: query name: ids schema: type: string required: true description: The comma-separated field IDs to delete responses: '200': description: Success content: application/json: schema: title: DeleteFieldsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object properties: id: type: array items: type: integer description: The list of deleted field IDs example: success: true data: id: - 123 - 456 /dealFields/{id}: get: summary: Get one deal field description: Returns data about a specific deal field. x-token-cost: 2 operationId: getDealField tags: - DealFields security: - api_key: [] - oauth2: - deals:read - deals:full - deal-fields:full - admin parameters: - in: path name: id description: The ID of the field required: true schema: type: integer responses: '200': description: Success content: application/json: schema: title: GetFieldResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: GetField allOf: - title: Field type: object properties: id: type: integer nullable: true description: The ID of the field. Value is `null` in case of subfields. key: type: string description: The key of the field. For custom fields this is generated upon creation. name: type: string description: The name of the field order_nr: type: integer description: The order number of the field field_type: allOf: - type: string enum: - address - date - daterange - double - enum - monetary - org - people - phone - set - text - time - timerange - user - varchar - varchar_auto - visible_to description: The type of the field
ValueDescription
`address`Address field
`date`Date (format YYYY-MM-DD)
`daterange`Date-range field (has a start date and end date value, both YYYY-MM-DD)
`double`Numeric value
`enum`Options field with a single possible chosen option
`monetary`Monetary field (has a numeric value and a currency value)
`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)
`set`Options field with a possibility of having multiple chosen options
`text`Long text (up to 65k characters)
`time`Time field (format HH:MM:SS)
`timerange`Time-range field (has a start time and end time value, both HH:MM:SS)
`user`User field (contains a user ID of another Pipedrive user)
`varchar`Text (up to 255 characters)
`varchar_auto`Autocomplete text (up to 255 characters)
`visible_to`System field that keeps item's visibility setting
add_time: type: string format: date-time description: The creation time of the field update_time: type: string format: date-time nullable: true description: The update time of the field last_updated_by_user_id: type: integer nullable: true description: The ID of the user who created or most recently updated the field, only applicable for custom fields created_by_user_id: type: integer nullable: true description: The ID of the user who created the field active_flag: type: boolean description: The active flag of the field edit_flag: type: boolean description: The edit flag of the field index_visible_flag: type: boolean description: Not used details_visible_flag: type: boolean description: Not used add_visible_flag: type: boolean description: Not used important_flag: type: boolean description: Not used bulk_edit_allowed: type: boolean description: Whether or not the field of an item can be edited in bulk searchable_flag: type: boolean description: Whether or not items can be searched by this field filtering_allowed: type: boolean description: Whether or not items can be filtered by this field sortable_flag: type: boolean description: Whether or not items can be sorted by this field mandatory_flag: type: boolean description: Whether or not the field is mandatory options: type: array nullable: true items: type: object description: The options of the field. When there are no options, `null` is returned. options_deleted: type: array items: type: object description: The deleted options of the field. Only present when there is at least 1 deleted option. is_subfield: type: boolean description: Whether or not the field is a subfield of another field. Only present if field is subfield. subfields: type: array items: type: object description: The subfields of the field. Only present when the field has subfields. - type: object properties: field_type: type: string enum: - boolean - double - int - json - date - daterange - time - timerange - text - varchar - varchar_auto - varchar_options - address - enum - monetary - phone - set - activity - deal - lead - org - people - pipeline - product - project - stage - user - billing_frequency - picture - price_list - projects_board - projects_phase - status - visible_to description: List of all possible field types example: success: true data: id: 2 key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e name: Customer Type order_nr: 1 field_type: enum add_time: '2019-02-04 13:58:03' update_time: '2019-02-04 13:58:03' last_updated_by_user_id: 1 created_by_user_id: 1 active_flag: true edit_flag: true index_visible_flag: true details_visible_flag: true add_visible_flag: false important_flag: false bulk_edit_allowed: true searchable_flag: false filtering_allowed: true sortable_flag: true options: - id: 190 label: Private person - id: 191 label: Company - id: 192 label: Government mandatory_flag: true delete: summary: Delete a deal field description: Marks a field as deleted. For more information, see the tutorial for deleting a custom field. x-token-cost: 6 operationId: deleteDealField tags: - DealFields security: - api_key: [] - oauth2: - deal-fields:full - admin parameters: - in: path name: id description: The ID of the field required: true schema: type: integer responses: '200': description: Success content: application/json: schema: title: DeleteResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object properties: id: type: integer description: The ID of the field that was deleted example: success: true data: id: 123 put: summary: Update a deal field description: Updates a deal field. For more information, see the tutorial for updating custom fields' values. x-token-cost: 10 operationId: updateDealField tags: - DealFields security: - api_key: [] - oauth2: - deal-fields:full - admin parameters: - in: path name: id description: The ID of the field required: true schema: type: integer requestBody: content: application/json: schema: title: updateFieldRequest type: object properties: name: type: string description: The name of the field options: type: array items: type: object description: 'When `field_type` is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: `[{"id":123,"label":"Existing Item"},{"label":"New Item"}]`' add_visible_flag: type: boolean default: true description: Whether the field is available in 'add new' modal or not (both in web and mobile app) responses: '200': description: Success content: application/json: schema: title: GetFieldResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: GetField allOf: - title: Field type: object properties: id: type: integer nullable: true description: The ID of the field. Value is `null` in case of subfields. key: type: string description: The key of the field. For custom fields this is generated upon creation. name: type: string description: The name of the field order_nr: type: integer description: The order number of the field field_type: allOf: - type: string enum: - address - date - daterange - double - enum - monetary - org - people - phone - set - text - time - timerange - user - varchar - varchar_auto - visible_to description: The type of the field
ValueDescription
`address`Address field
`date`Date (format YYYY-MM-DD)
`daterange`Date-range field (has a start date and end date value, both YYYY-MM-DD)
`double`Numeric value
`enum`Options field with a single possible chosen option
`monetary`Monetary field (has a numeric value and a currency value)
`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)
`set`Options field with a possibility of having multiple chosen options
`text`Long text (up to 65k characters)
`time`Time field (format HH:MM:SS)
`timerange`Time-range field (has a start time and end time value, both HH:MM:SS)
`user`User field (contains a user ID of another Pipedrive user)
`varchar`Text (up to 255 characters)
`varchar_auto`Autocomplete text (up to 255 characters)
`visible_to`System field that keeps item's visibility setting
add_time: type: string format: date-time description: The creation time of the field update_time: type: string format: date-time nullable: true description: The update time of the field last_updated_by_user_id: type: integer nullable: true description: The ID of the user who created or most recently updated the field, only applicable for custom fields created_by_user_id: type: integer nullable: true description: The ID of the user who created the field active_flag: type: boolean description: The active flag of the field edit_flag: type: boolean description: The edit flag of the field index_visible_flag: type: boolean description: Not used details_visible_flag: type: boolean description: Not used add_visible_flag: type: boolean description: Not used important_flag: type: boolean description: Not used bulk_edit_allowed: type: boolean description: Whether or not the field of an item can be edited in bulk searchable_flag: type: boolean description: Whether or not items can be searched by this field filtering_allowed: type: boolean description: Whether or not items can be filtered by this field sortable_flag: type: boolean description: Whether or not items can be sorted by this field mandatory_flag: type: boolean description: Whether or not the field is mandatory options: type: array nullable: true items: type: object description: The options of the field. When there are no options, `null` is returned. options_deleted: type: array items: type: object description: The deleted options of the field. Only present when there is at least 1 deleted option. is_subfield: type: boolean description: Whether or not the field is a subfield of another field. Only present if field is subfield. subfields: type: array items: type: object description: The subfields of the field. Only present when the field has subfields. - type: object properties: field_type: type: string enum: - boolean - double - int - json - date - daterange - time - timerange - text - varchar - varchar_auto - varchar_options - address - enum - monetary - phone - set - activity - deal - lead - org - people - pipeline - product - project - stage - user - billing_frequency - picture - price_list - projects_board - projects_phase - status - visible_to description: List of all possible field types example: success: true data: id: 2 key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e name: Customer Type order_nr: 1 field_type: enum add_time: '2019-02-04 13:58:03' update_time: '2019-02-04 13:58:03' last_updated_by_user_id: 1 created_by_user_id: 1 active_flag: true edit_flag: true index_visible_flag: true details_visible_flag: true add_visible_flag: false important_flag: false bulk_edit_allowed: true searchable_flag: false filtering_allowed: true sortable_flag: true options: - id: 190 label: Private person - id: 191 label: Company - id: 192 label: Government mandatory_flag: true /dealFields/{field_code}: get: summary: Get one deal field description: Returns metadata about a specific deal field. x-token-cost: 1 operationId: getDealField tags: - DealFields security: - api_key: [] - oauth2: - deals:read - deals:full - admin - deal-fields:full parameters: - in: path name: field_code description: The unique code identifying the field required: true schema: type: string - in: query name: include_fields description: Optional comma separated string array of additional data namespaces to include in response schema: type: string enum: - ui_visibility - important_fields - required_fields - ui_visibility,important_fields - ui_visibility,required_fields - important_fields,required_fields - ui_visibility,important_fields,required_fields responses: '200': description: Get one deal field content: application/json: schema: type: object properties: success: type: boolean description: Whether the request was successful data: type: object required: - field_name - field_code - description - field_type - is_custom_field - is_optional_response_field properties: field_name: type: string description: The display name/label of the field field_code: type: string description: The unique identifier for the field (40-character hash for custom fields) description: type: string description: The description of the field field_type: type: string description: The type of the field enum: - int - double - boolean - varchar - text - phone - varchar_options - varchar_auto - date - daterange - time - timerange - enum - set - address - monetary - deal - deals - lead - org - people - project - stage - user - activity - json - picture - status - visible_to - price_list - billing_frequency - projects_board - projects_phase options: type: array nullable: true description: Array of available options for enum/set fields, null for other field types items: type: object properties: id: type: integer description: The option ID label: type: string description: The option display label color: type: string nullable: true description: Optional color code for the option update_time: type: string format: date-time nullable: true description: When the option was last updated add_time: type: string format: date-time nullable: true description: When the option was created subfields: type: array nullable: true description: Array of subfields for complex field types (address, monetary), null for simple field types items: type: object properties: field_code: type: string description: The subfield identifier field_name: type: string description: The subfield display name field_type: type: string description: The subfield type is_custom_field: type: boolean description: Whether this is a user-created custom field is_optional_response_field: type: boolean description: Whether this field is not returned by default in entity responses ui_visibility: type: object description: UI visibility settings (only included when requested via include_fields parameter) properties: add_visible_flag: type: boolean description: Whether the field is shown in the add modal details_visible_flag: type: boolean description: Whether the field is shown in the details view projects_detail_visible_flag: type: boolean description: Whether the field is shown in project details view show_in_pipelines: type: object description: Pipeline visibility configuration properties: show_in_all: type: boolean description: Whether the field is shown in all pipelines pipeline_ids: type: array items: type: integer description: Specific pipeline IDs where the field is shown (if show_in_all is false) important_fields: type: object description: Important fields configuration properties: enabled: type: boolean description: Whether the field is marked as important stage_ids: type: array items: type: integer description: Array of stage IDs where the field is important required_fields: type: object description: Required fields configuration properties: enabled: type: boolean description: Whether the field is required stage_ids: type: array items: type: integer description: Array of stage IDs where the field is required statuses: type: object description: Pipeline-specific status requirements, mapping pipeline ID to array of statuses additionalProperties: type: array items: type: string enum: - won - lost example: success: true data: field_name: Deal Title field_code: title description: The title or name of the deal field_type: varchar options: null subfields: null is_custom_field: false is_optional_response_field: false ui_visibility: add_visible_flag: true details_visible_flag: true projects_detail_visible_flag: true show_in_pipelines: show_in_all: true pipeline_ids: [] important_fields: enabled: false stage_ids: [] required_fields: enabled: false stage_ids: [] statuses: {} patch: summary: Update one deal field description: 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. x-token-cost: 5 operationId: updateDealField tags: - DealFields security: - api_key: [] - oauth2: - deals:full - admin - deal-fields:full parameters: - in: path name: field_code description: The unique code identifying the field required: true schema: type: string requestBody: required: true content: application/json: schema: type: object minProperties: 1 properties: field_name: type: string minLength: 1 maxLength: 255 description: Field name ui_visibility: type: object description: UI visibility settings for the field. Controls where the field appears in the Pipedrive web UI. additionalProperties: true properties: add_visible_flag: type: boolean description: 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). default: false details_visible_flag: type: boolean description: Whether the field is shown in the deal details view. Default is true. default: true projects_detail_visible_flag: type: boolean description: Whether the field is shown in the project details view when the deal is linked to a project. Default is false. default: false show_in_pipelines: type: object description: 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. properties: show_in_all: type: boolean description: When true, the field is visible in all pipelines. When false, visibility is controlled by pipeline_ids. Default is true. default: true pipeline_ids: type: array items: type: integer description: 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: type: object description: Configuration for highlighting the field at specific stages. additionalProperties: true properties: enabled: type: boolean description: 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. default: false stage_ids: type: array items: type: integer description: 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: type: object description: Required fields configuration for marking the field as mandatory when interacted with in the Pipedrive web UI. additionalProperties: true properties: enabled: type: boolean description: 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. default: false stage_ids: type: array items: type: integer description: 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: type: object description: 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: {} additionalProperties: type: array items: type: string enum: - won - lost description: type: string nullable: true description: Field description responses: '200': description: Get one deal field content: application/json: schema: type: object properties: success: type: boolean description: Whether the request was successful data: type: object required: - field_name - field_code - description - field_type - is_custom_field - is_optional_response_field properties: field_name: type: string description: The display name/label of the field field_code: type: string description: The unique identifier for the field (40-character hash for custom fields) description: type: string description: The description of the field field_type: type: string description: The type of the field enum: - int - double - boolean - varchar - text - phone - varchar_options - varchar_auto - date - daterange - time - timerange - enum - set - address - monetary - deal - deals - lead - org - people - project - stage - user - activity - json - picture - status - visible_to - price_list - billing_frequency - projects_board - projects_phase options: type: array nullable: true description: Array of available options for enum/set fields, null for other field types items: type: object properties: id: type: integer description: The option ID label: type: string description: The option display label color: type: string nullable: true description: Optional color code for the option update_time: type: string format: date-time nullable: true description: When the option was last updated add_time: type: string format: date-time nullable: true description: When the option was created subfields: type: array nullable: true description: Array of subfields for complex field types (address, monetary), null for simple field types items: type: object properties: field_code: type: string description: The subfield identifier field_name: type: string description: The subfield display name field_type: type: string description: The subfield type is_custom_field: type: boolean description: Whether this is a user-created custom field is_optional_response_field: type: boolean description: Whether this field is not returned by default in entity responses ui_visibility: type: object description: UI visibility settings (only included when requested via include_fields parameter) properties: add_visible_flag: type: boolean description: Whether the field is shown in the add modal details_visible_flag: type: boolean description: Whether the field is shown in the details view projects_detail_visible_flag: type: boolean description: Whether the field is shown in project details view show_in_pipelines: type: object description: Pipeline visibility configuration properties: show_in_all: type: boolean description: Whether the field is shown in all pipelines pipeline_ids: type: array items: type: integer description: Specific pipeline IDs where the field is shown (if show_in_all is false) important_fields: type: object description: Important fields configuration properties: enabled: type: boolean description: Whether the field is marked as important stage_ids: type: array items: type: integer description: Array of stage IDs where the field is important required_fields: type: object description: Required fields configuration properties: enabled: type: boolean description: Whether the field is required stage_ids: type: array items: type: integer description: Array of stage IDs where the field is required statuses: type: object description: Pipeline-specific status requirements, mapping pipeline ID to array of statuses additionalProperties: type: array items: type: string enum: - won - lost example: success: true data: field_name: Deal Title field_code: title description: The title or name of the deal field_type: varchar options: null subfields: null is_custom_field: false is_optional_response_field: false ui_visibility: add_visible_flag: true details_visible_flag: true projects_detail_visible_flag: true show_in_pipelines: show_in_all: true pipeline_ids: [] important_fields: enabled: false stage_ids: [] required_fields: enabled: false stage_ids: [] statuses: {} delete: summary: Delete one deal field description: Marks a custom field as deleted. x-token-cost: 3 operationId: deleteDealField tags: - DealFields security: - api_key: [] - oauth2: - admin - deal-fields:full parameters: - in: path name: field_code description: The unique code identifying the field required: true schema: type: string responses: '200': description: Delete one deal field content: application/json: schema: type: object properties: success: type: boolean description: Whether the request was successful data: type: object required: - field_name - field_code - description - field_type - is_custom_field - is_optional_response_field properties: field_name: type: string description: The display name/label of the field field_code: type: string description: The unique identifier for the field (40-character hash for custom fields) description: type: string description: The description of the field field_type: type: string description: The type of the field options: type: array nullable: true description: Array of available options for enum/set fields, null for other field types items: type: object subfields: type: array nullable: true description: Array of subfields for complex field types (address, monetary), null for simple field types items: type: object is_custom_field: type: boolean description: Whether this is a user-created custom field is_optional_response_field: type: boolean description: Whether this field is not returned by default in entity responses example: success: true data: field_name: Custom text field field_code: 946947d1b02fd3ef20798d6112ec5d895a686a21 description: A custom text field field_type: varchar options: null subfields: null is_custom_field: true is_optional_response_field: false /dealFields/{field_code}/options: post: summary: Add deal field options in bulk description: 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. x-token-cost: 5 operationId: addDealFieldOptions tags: - DealFields security: - api_key: [] - oauth2: - deals:full - admin - deal-fields:full parameters: - in: path name: field_code description: The unique code identifying the field required: true schema: type: string requestBody: required: true content: application/json: schema: type: array description: Array of options to add. Each item must contain a label. At least one option is required. items: type: object required: - label properties: label: type: string minLength: 1 maxLength: 255 description: The display label for the new option responses: '200': description: Field options operation result content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: object required: - id - label properties: id: type: integer description: The unique identifier of the option label: type: string description: The display label of the option additional_data: type: object nullable: true example: success: true data: - id: 4 label: Critical additional_data: null delete: summary: Delete deal field options in bulk description: 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. x-token-cost: 3 operationId: deleteDealFieldOptions tags: - DealFields security: - api_key: [] - oauth2: - deals:full - admin - deal-fields:full parameters: - in: path name: field_code description: The unique code identifying the field required: true schema: type: string requestBody: required: true content: application/json: schema: type: array description: 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. items: type: object required: - id properties: id: type: integer description: The unique identifier of the option to delete responses: '200': description: Field options operation result content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: object required: - id - label properties: id: type: integer description: The unique identifier of the option label: type: string description: The display label of the option additional_data: type: object nullable: true example: success: true data: - id: 4 label: Critical additional_data: null patch: summary: Update deal field options in bulk description: 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. x-token-cost: 5 operationId: updateDealFieldOptions tags: - DealFields security: - api_key: [] - oauth2: - deals:full - admin - deal-fields:full parameters: - in: path name: field_code description: The unique code identifying the field required: true schema: type: string requestBody: required: true content: application/json: schema: type: array description: 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. items: type: object required: - id - label properties: id: type: integer description: The unique identifier of the option to update label: type: string minLength: 1 maxLength: 255 description: The new display label for the option responses: '200': description: Field options operation result content: application/json: schema: type: object properties: success: type: boolean data: type: array items: type: object required: - id - label properties: id: type: integer description: The unique identifier of the option label: type: string description: The display label of the option additional_data: type: object nullable: true example: success: true data: - id: 4 label: Critical additional_data: null components: securitySchemes: basic_authentication: type: http scheme: basic description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic `. api_key: type: apiKey name: x-api-token in: header oauth2: type: oauth2 description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization flows: authorizationCode: authorizationUrl: https://oauth.pipedrive.com/oauth/authorize tokenUrl: https://oauth.pipedrive.com/oauth/token refreshUrl: https://oauth.pipedrive.com/oauth/token scopes: base: Read settings of the authorized user and currencies in an account deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal) deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal) mail:read: Read mail threads and messages mail:full: Read, update and delete mail threads. Also grants read access to mail messages activities:read: Read activities, its fields and types; all files and filters activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields products:read: Read products, its fields, files, followers and products connected to a deal products:full: Create, read, update and delete products and its fields; add products to deals deal-fields:full: Create, read, update and delete deal fields product-fields:full: Create, read, update and delete product fields contact-fields:full: Create, read, update and delete person and organization fields projects:read: Read projects and its fields, tasks and project templates projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app leads:read: Read data about leads and lead labels leads:full: Create, read, update and delete leads and lead labels phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive goals:read: Read data on all goals goals:full: Create, read, update and delete goals video-calls: Allows application to register as a video call integration provider and create conference links messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses