| 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 |
'
enum:
- varchar
- text
- double
- phone
- date
- daterange
- time
- timerange
- set
- enum
- varchar_auto
- address
- monetary
- org
- people
- user
options:
type: array
description: Field options (required for enum and set field types)
items:
type: object
required:
- label
properties:
label:
type: string
description: The option label
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: Create 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: Priority
field_code: 946947d1b02fd3ef20798d6112ec5d895a686a21
description: Priority level for the deal
field_type: enum
options:
- id: 1
label: Low
color: green
- id: 2
label: Medium
color: yellow
- id: 3
label: High
color: red
subfields: null
is_custom_field: true
is_optional_response_field: false
ui_visibility:
add_visible_flag: true
details_visible_flag: true
projects_detail_visible_flag: false
show_in_pipelines:
show_in_all: false
pipeline_ids:
- 1
- 2
important_fields:
enabled: true
stage_ids:
- 5
- 6
required_fields:
enabled: true
stage_ids:
- 5
- 6
'/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
'/deals/{id}/convert/status/{conversion_id}':
get:
security:
- api_key: []
- oauth2:
- 'deals:full'
- 'deals:read'
tags:
- Deals
summary: Get Deal conversion status
description: 'Returns information about the conversion. Status is always present and its value (not_started, running, completed, failed, rejected) represents the current state of the conversion. Lead ID is only present if the conversion was successfully finished. This data is only temporary and removed after a few days.'
operationId: getDealConversionStatus
x-token-cost: 1
parameters:
- in: path
name: id
required: true
schema:
type: integer
description: The ID of a deal
- in: path
name: conversion_id
required: true
schema:
type: string
format: uuid
description: The ID of the conversion
responses:
'200':
description: Successful response containing payload in the `data` field
content:
application/json:
example:
success: true
data:
lead_id: 9f3e6e50-9d99-11ee-9538-29c81a92c0d1
conversion_id: 4b40248b-945a-4802-b996-60fdff8c5c69
status: completed
additional_data: null
schema:
title: GetConvertResponse
type: object
required:
- success
- data
properties:
success:
type: boolean
data:
type: object
description: An object containing conversion status. After successful conversion the converted entity ID is also present.
required:
- conversion_id
- status
properties:
lead_id:
description: The ID of the new lead.
type: string
format: uuid
deal_id:
description: The ID of the new deal.
type: integer
conversion_id:
description: The ID of the conversion job. The ID can be used to retrieve conversion status and details. The ID has UUID format.
type: string
format: uuid
status:
description: Status of the conversion job.
type: string
enum:
- not_started
- running
- completed
- failed
- rejected
additional_data:
type: object
nullable: true
example: null
'404':
description: A resource describing an error
content:
application/json:
schema:
type: object
title: GetConvertResponse
properties:
success:
type: boolean
example: false
error:
type: string
description: The description of the error
error_info:
type: string
description: A message describing how to solve the problem
data:
type: object
nullable: true
example: null
additional_data:
type: object
nullable: true
example: null
example:
success: false
error: Entity was not found
error_info: Object was not found.
data: null
additional_data: null
/persons:
get:
summary: Get all persons
description: 'Returns data about all persons. Fields `ims`, `postal_address`, `notes`, `birthday`, and `job_title` are only included if contact sync is enabled for the company.'
x-token-cost: 10
operationId: getPersons
tags:
- Persons
security:
- api_key: []
- oauth2:
- 'contacts:read'
- 'contacts:full'
parameters:
- in: query
name: filter_id
schema:
type: integer
description: 'If supplied, only persons matching the specified filter are returned'
- in: query
name: ids
description: 'Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response.'
schema:
type: string
- in: query
name: owner_id
schema:
type: integer
description: 'If supplied, only persons owned by the specified user are returned. If filter_id is provided, this is ignored.'
- in: query
name: org_id
schema:
type: integer
description: 'If supplied, only persons linked to the specified organization are returned. If filter_id is provided, this is ignored.'
- in: query
name: deal_id
schema:
type: integer
description: 'If supplied, only persons linked to the specified deal are returned. If filter_id is provided, this is ignored.'
- in: query
name: updated_since
schema:
type: string
description: 'If set, only persons with an `update_time` later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.'
- in: query
name: updated_until
schema:
type: string
description: 'If set, only persons with an `update_time` earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.'
- in: query
name: sort_by
description: 'The field to sort by. Supported fields: `id`, `update_time`, `add_time`.'
schema:
type: string
default: id
enum:
- id
- update_time
- add_time
- in: query
name: sort_direction
description: 'The sorting direction. Supported values: `asc`, `desc`.'
schema:
type: string
default: asc
enum:
- asc
- desc
- in: query
name: include_fields
description: Optional comma separated string array of additional fields to include. `marketing_status` and `doi_status` can only be included if the company has marketing app enabled.
schema:
type: string
enum:
- next_activity_id
- last_activity_id
- open_deals_count
- related_open_deals_count
- closed_deals_count
- related_closed_deals_count
- participant_open_deals_count
- participant_closed_deals_count
- email_messages_count
- activities_count
- done_activities_count
- undone_activities_count
- files_count
- notes_count
- followers_count
- won_deals_count
- related_won_deals_count
- lost_deals_count
- related_lost_deals_count
- last_incoming_mail_time
- last_outgoing_mail_time
- marketing_status
- doi_status
- smart_bcc_email
- in: query
name: custom_fields
description: 'Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.| 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 |
'
enum:
- varchar
- text
- double
- phone
- date
- daterange
- time
- timerange
- set
- enum
- varchar_auto
- address
- monetary
- org
- people
- user
options:
type: array
description: Field options (required for enum and set field types)
items:
type: object
required:
- label
properties:
label:
type: string
description: The option label
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 person modal. Default is false. Cannot be set to false for required system fields (''name'', ''org_id'').'
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the person details view. Default is true.
default: true
show_in_add_deal_dialog:
type: object
description: 'Configuration for showing this person field when adding a new deal. Only available for custom fields or specific eligible system fields. Default is show=false, order=null.'
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog. Default is false.
default: false
order:
type: integer
nullable: true
description: 'Display order in the add deal dialog. This value is auto-calculated and managed by the system. When show is set to false, order is automatically set to null. When show changes from false to true, order is automatically assigned the next available position.'
default: null
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 deal stages. Default is false.'
default: false
stage_ids:
type: array
items:
type: integer
description: 'Array of deal stage IDs where this person field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false.'
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, the field is required when creating or updating persons. Default is false.'
default: false
responses:
'200':
description: Create one person 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
- 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)
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
show_in_add_deal_dialog:
type: object
description: Configuration for showing the field in the add deal dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog
order:
type: integer
nullable: true
description: Display order in the add deal dialog (null if not shown)
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 deal 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
example:
success: true
data:
field_name: Lead Source
field_code: 946947d1b02fd3ef20798d6112ec5d895a686a21
description: The source where the lead came from
field_type: enum
options:
- id: 1
label: Inbound
- id: 2
label: Outbound
subfields: null
is_custom_field: true
is_optional_response_field: false
ui_visibility:
add_visible_flag: true
details_visible_flag: true
show_in_add_deal_dialog:
show: false
order: null
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: false
'/personFields/{field_code}':
get:
summary: Get one person field
description: Returns metadata about a specific person field.
x-token-cost: 1
operationId: getPersonField
tags:
- PersonFields
security:
- api_key: []
- oauth2:
- 'contacts:read'
- 'contacts:full'
- admin
- 'contact-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 person 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
- 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)
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
show_in_add_deal_dialog:
type: object
description: Configuration for showing the field in the add deal dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog
order:
type: integer
nullable: true
description: Display order in the add deal dialog (null if not shown)
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 deal 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
example:
success: true
data:
field_name: Person Name
field_code: name
description: The name of the person
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
show_in_add_deal_dialog:
show: true
order: 1
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: true
patch:
summary: Update one person field
description: Updates a person 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: updatePersonField
tags:
- PersonFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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 person modal. Default is false. Cannot be set to false for required system fields (''name'', ''org_id'').'
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the person details view. Default is true.
default: true
show_in_add_deal_dialog:
type: object
description: 'Configuration for showing this person field when adding a new deal. Only available for custom fields or specific eligible system fields. Default is show=false, order=null.'
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog. Default is false.
default: false
order:
type: integer
nullable: true
description: 'Display order in the add deal dialog. This value is auto-calculated and managed by the system. When show is set to false, order is automatically set to null. When show changes from false to true, order is automatically assigned the next available position.'
default: null
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 deal stages. Default is false.'
default: false
stage_ids:
type: array
items:
type: integer
description: 'Array of deal stage IDs where this person field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false.'
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, the field is required when creating or updating persons. Default is false.'
default: false
responses:
'200':
description: Get one person 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
- 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)
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
show_in_add_deal_dialog:
type: object
description: Configuration for showing the field in the add deal dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog
order:
type: integer
nullable: true
description: Display order in the add deal dialog (null if not shown)
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 deal 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
example:
success: true
data:
field_name: Person Name
field_code: name
description: The name of the person
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
show_in_add_deal_dialog:
show: true
order: 1
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: true
delete:
summary: Delete one person field
description: Marks a custom field as deleted.
x-token-cost: 3
operationId: deletePersonField
tags:
- PersonFields
security:
- api_key: []
- oauth2:
- admin
- 'contact-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 person 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
- 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)
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
'/personFields/{field_code}/options':
post:
summary: Add person field options in bulk
description: Adds new options to a person 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: addPersonFieldOptions
tags:
- PersonFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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: 3
label: Referral
additional_data: null
delete:
summary: Delete person field options in bulk
description: Removes existing options from a person 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: deletePersonFieldOptions
tags:
- PersonFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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: 3
label: Referral
additional_data: null
patch:
summary: Update person field options in bulk
description: Updates existing options for a person 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: updatePersonFieldOptions
tags:
- PersonFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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: 3
label: Referral
additional_data: null
/organizations:
get:
summary: Get all organizations
description: Returns data about all organizations.
x-token-cost: 10
operationId: getOrganizations
tags:
- Organizations
security:
- api_key: []
- oauth2:
- 'contacts:read'
- 'contacts:full'
parameters:
- in: query
name: filter_id
schema:
type: integer
description: 'If supplied, only organizations matching the specified filter are returned'
- in: query
name: ids
description: 'Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response.'
schema:
type: string
- in: query
name: owner_id
schema:
type: integer
description: 'If supplied, only organizations owned by the specified user are returned. If filter_id is provided, this is ignored.'
- in: query
name: updated_since
schema:
type: string
description: 'If set, only organizations with an `update_time` later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.'
- in: query
name: updated_until
schema:
type: string
description: 'If set, only organizations with an `update_time` earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.'
- in: query
name: sort_by
description: 'The field to sort by. Supported fields: `id`, `update_time`, `add_time`.'
schema:
type: string
default: id
enum:
- id
- update_time
- add_time
- in: query
name: sort_direction
description: 'The sorting direction. Supported values: `asc`, `desc`.'
schema:
type: string
default: asc
enum:
- asc
- desc
- in: query
name: include_fields
description: Optional comma separated string array of additional fields to include
schema:
type: string
enum:
- next_activity_id
- last_activity_id
- open_deals_count
- related_open_deals_count
- closed_deals_count
- related_closed_deals_count
- email_messages_count
- people_count
- activities_count
- done_activities_count
- undone_activities_count
- files_count
- notes_count
- followers_count
- won_deals_count
- related_won_deals_count
- lost_deals_count
- related_lost_deals_count
- smart_bcc_email
- in: query
name: custom_fields
description: 'Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response.| 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 |
'
enum:
- varchar
- text
- double
- phone
- date
- daterange
- time
- timerange
- set
- enum
- varchar_auto
- address
- monetary
- org
- people
- user
options:
type: array
description: Field options (required for enum and set field types)
items:
type: object
required:
- label
properties:
label:
type: string
description: The option label
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 organization modal. Default is false. Cannot be set to false for the 'name' system field.
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the organization details view. Default is true.
default: true
show_in_add_deal_dialog:
type: object
description: 'Configuration for showing this organization field when adding a new deal. Only available for custom fields or specific eligible system fields. Default is show=false, order=null.'
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog. Default is false.
default: false
order:
type: integer
nullable: true
description: 'Display order in the add deal dialog. This value is auto-calculated and managed by the system. When show is set to false, order is automatically set to null. When show changes from false to true, order is automatically assigned the next available position.'
default: null
show_in_add_person_dialog:
type: object
description: 'Configuration for showing this organization field when adding a new person. Only available for custom fields or specific eligible system fields. Default is show=false, order=null.'
properties:
show:
type: boolean
description: Whether the field is shown in the add person dialog. Default is false.
default: false
order:
type: integer
nullable: true
description: 'Display order in the add person dialog. This value is auto-calculated and managed by the system. When show is set to false, order is automatically set to null. When show changes from false to true, order is automatically assigned the next available position.'
default: null
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 deal stages. Default is false.'
default: false
stage_ids:
type: array
items:
type: integer
description: 'Array of deal stage IDs where this organization field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false.'
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, the field is required when creating or updating organizations. Default is false.'
default: false
responses:
'200':
description: Create one organization 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
- 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)
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
org_detail_visible_flag:
type: boolean
description: Whether the field is shown in the organization details view
person_detail_visible_flag:
type: boolean
description: Whether the field is shown in the person details view
deal_detail_visible_flag:
type: boolean
description: Whether the field is shown in the deal details view
show_in_add_deal_dialog:
type: object
description: Configuration for showing the field in the add deal dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog
order:
type: integer
nullable: true
description: Display order in the add deal dialog (null if not shown)
show_in_add_person_dialog:
type: object
description: Configuration for showing the field in the add person dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add person dialog
order:
type: integer
nullable: true
description: Display order in the add person dialog (null if not shown)
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 deal 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
example:
success: true
data:
field_name: Industry
field_code: 946947d1b02fd3ef20798d6112ec5d895a686a21
field_type: enum
options:
- id: 1
label: Technology
- id: 2
label: Finance
- id: 3
label: Healthcare
subfields: null
is_custom_field: true
is_optional_response_field: false
ui_visibility:
add_visible_flag: true
details_visible_flag: true
org_detail_visible_flag: true
person_detail_visible_flag: false
deal_detail_visible_flag: false
show_in_add_deal_dialog:
show: false
order: null
show_in_add_person_dialog:
show: true
order: 2
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: false
'/organizationFields/{field_code}':
get:
summary: Get one organization field
description: Returns metadata about a specific organization field.
x-token-cost: 1
operationId: getOrganizationField
tags:
- OrganizationFields
security:
- api_key: []
- oauth2:
- 'contacts:read'
- 'contacts:full'
- admin
- 'contact-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 organization 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
- 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)
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
org_detail_visible_flag:
type: boolean
description: Whether the field is shown in the organization details view
person_detail_visible_flag:
type: boolean
description: Whether the field is shown in the person details view
deal_detail_visible_flag:
type: boolean
description: Whether the field is shown in the deal details view
show_in_add_deal_dialog:
type: object
description: Configuration for showing the field in the add deal dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog
order:
type: integer
nullable: true
description: Display order in the add deal dialog (null if not shown)
show_in_add_person_dialog:
type: object
description: Configuration for showing the field in the add person dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add person dialog
order:
type: integer
nullable: true
description: Display order in the add person dialog (null if not shown)
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 deal 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
example:
success: true
data:
field_name: Organization Name
field_code: name
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
org_detail_visible_flag: true
person_detail_visible_flag: true
deal_detail_visible_flag: true
show_in_add_deal_dialog:
show: true
order: 1
show_in_add_person_dialog:
show: true
order: 1
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: true
patch:
summary: Update one organization field
description: Updates an organization 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: updateOrganizationField
tags:
- OrganizationFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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 organization modal. Default is false. Cannot be set to false for the 'name' system field.
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the organization details view. Default is true.
default: true
show_in_add_deal_dialog:
type: object
description: 'Configuration for showing this organization field when adding a new deal. Only available for custom fields or specific eligible system fields. Default is show=false, order=null.'
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog. Default is false.
default: false
order:
type: integer
nullable: true
description: 'Display order in the add deal dialog. This value is auto-calculated and managed by the system. When show is set to false, order is automatically set to null. When show changes from false to true, order is automatically assigned the next available position.'
default: null
show_in_add_person_dialog:
type: object
description: 'Configuration for showing this organization field when adding a new person. Only available for custom fields or specific eligible system fields. Default is show=false, order=null.'
properties:
show:
type: boolean
description: Whether the field is shown in the add person dialog. Default is false.
default: false
order:
type: integer
nullable: true
description: 'Display order in the add person dialog. This value is auto-calculated and managed by the system. When show is set to false, order is automatically set to null. When show changes from false to true, order is automatically assigned the next available position.'
default: null
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 deal stages. Default is false.'
default: false
stage_ids:
type: array
items:
type: integer
description: 'Array of deal stage IDs where this organization field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false.'
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, the field is required when creating or updating organizations. Default is false.'
default: false
responses:
'200':
description: Get one organization 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
- 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)
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
org_detail_visible_flag:
type: boolean
description: Whether the field is shown in the organization details view
person_detail_visible_flag:
type: boolean
description: Whether the field is shown in the person details view
deal_detail_visible_flag:
type: boolean
description: Whether the field is shown in the deal details view
show_in_add_deal_dialog:
type: object
description: Configuration for showing the field in the add deal dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add deal dialog
order:
type: integer
nullable: true
description: Display order in the add deal dialog (null if not shown)
show_in_add_person_dialog:
type: object
description: Configuration for showing the field in the add person dialog
properties:
show:
type: boolean
description: Whether the field is shown in the add person dialog
order:
type: integer
nullable: true
description: Display order in the add person dialog (null if not shown)
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 deal 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
example:
success: true
data:
field_name: Organization Name
field_code: name
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
org_detail_visible_flag: true
person_detail_visible_flag: true
deal_detail_visible_flag: true
show_in_add_deal_dialog:
show: true
order: 1
show_in_add_person_dialog:
show: true
order: 1
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: true
delete:
summary: Delete one organization field
description: Marks a custom field as deleted.
x-token-cost: 3
operationId: deleteOrganizationField
tags:
- OrganizationFields
security:
- api_key: []
- oauth2:
- admin
- 'contact-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 organization 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
- 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)
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
field_type: varchar
options: null
subfields: null
is_custom_field: true
is_optional_response_field: false
'/organizationFields/{field_code}/options':
post:
summary: Add organization field options in bulk
description: Adds new options to an organization 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: addOrganizationFieldOptions
tags:
- OrganizationFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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: Manufacturing
additional_data: null
delete:
summary: Delete organization field options in bulk
description: Removes existing options from an organization 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: deleteOrganizationFieldOptions
tags:
- OrganizationFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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: Manufacturing
additional_data: null
patch:
summary: Update organization field options in bulk
description: Updates existing options for an organization 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: updateOrganizationFieldOptions
tags:
- OrganizationFields
security:
- api_key: []
- oauth2:
- 'contacts:full'
- admin
- 'contact-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: Manufacturing
additional_data: null
/products:
get:
summary: Get all products
description: Returns data about all products.
x-token-cost: 10
operationId: getProducts
tags:
- Products
security:
- api_key: []
- oauth2:
- 'products:read'
- 'products:full'
parameters:
- in: query
name: owner_id
schema:
type: integer
description: 'If supplied, only products owned by the given user will be returned'
- in: query
name: ids
description: 'Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response.'
schema:
type: string
- in: query
name: filter_id
schema:
type: integer
description: The ID of the filter to use
- in: query
name: cursor
required: false
schema:
type: string
description: 'For pagination, the marker (an opaque string value) representing the first item on the next page'
- in: query
name: limit
description: '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.'
schema:
type: integer
example: 100
- in: query
name: sort_by
description: 'The field to sort by. Supported fields: `id`, `name`, `add_time`, `update_time`.'
schema:
type: string
default: id
enum:
- id
- name
- add_time
- update_time
- in: query
name: sort_direction
description: 'The sorting direction. Supported values: `asc`, `desc`.'
schema:
type: string
default: asc
enum:
- asc
- desc
- in: query
name: custom_fields
description: 'Comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for a smaller response.| 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 |
'
enum:
- varchar
- text
- double
- phone
- date
- daterange
- time
- timerange
- set
- enum
- varchar_auto
- address
- monetary
- org
- people
- user
options:
type: array
description: Field options (required for enum and set field types)
items:
type: object
required:
- label
properties:
label:
type: string
description: The option label
ui_visibility:
type: object
description: UI visibility settings for the field. Controls where the field appears in the Pipedrive web UI. Note that products have a simpler visibility model than other entity types.
additionalProperties: true
properties:
add_visible_flag:
type: boolean
description: Whether the field is shown in the add product modal. Default is false. Cannot be set to false for the 'name' system field.
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the product details view. Default is true.
default: true
responses:
'200':
description: Create one product 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
- 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)
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 (read-only)
example:
success: true
data:
field_name: Categories
field_code: 946947d1b02fd3ef20798d6112ec5d895a686a21
field_type: set
options:
- id: 1
label: Software
color: blue
- id: 2
label: Hardware
color: green
- id: 3
label: Services
color: orange
subfields: null
is_custom_field: true
is_optional_response_field: false
ui_visibility:
add_visible_flag: true
details_visible_flag: true
'/productFields/{field_code}':
get:
summary: Get one product field
description: Returns metadata about a specific product field.
x-token-cost: 1
operationId: getProductField
tags:
- ProductFields
security:
- api_key: []
- oauth2:
- 'products:read'
- 'products:full'
- 'product-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
responses:
'200':
description: Get one product 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
- 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)
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 (read-only)
example:
success: true
data:
field_name: Product Name
field_code: name
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
patch:
summary: Update one product field
description: Updates a product 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: updateProductField
tags:
- ProductFields
security:
- api_key: []
- oauth2:
- 'products:full'
- 'product-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. Note that products have a simpler visibility model than other entity types.
additionalProperties: true
properties:
add_visible_flag:
type: boolean
description: Whether the field is shown in the add product modal. Default is false. Cannot be set to false for the 'name' system field.
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the product details view. Default is true.
default: true
responses:
'200':
description: Get one product 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
- 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)
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 (read-only)
example:
success: true
data:
field_name: Product Name
field_code: name
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
delete:
summary: Delete one product field
description: Marks a custom field as deleted.
x-token-cost: 3
operationId: deleteProductField
tags:
- ProductFields
security:
- api_key: []
- oauth2:
- 'products:full'
- 'product-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 product 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
- 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)
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
field_type: varchar
options: null
subfields: null
is_custom_field: true
is_optional_response_field: false
'/productFields/{field_code}/options':
post:
summary: Add product field options in bulk
description: Adds new options to a product 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: addProductFieldOptions
tags:
- ProductFields
security:
- api_key: []
- oauth2:
- 'products:full'
- 'product-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: Consulting
additional_data: null
delete:
summary: Delete product field options in bulk
description: Removes existing options from a product 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: deleteProductFieldOptions
tags:
- ProductFields
security:
- api_key: []
- oauth2:
- 'products:full'
- 'product-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: Consulting
additional_data: null
patch:
summary: Update product field options in bulk
description: Updates existing options for a product 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: updateProductFieldOptions
tags:
- ProductFields
security:
- api_key: []
- oauth2:
- 'products:full'
- 'product-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: Consulting
additional_data: null
/leads/search:
get:
summary: Search leads
description: 'Searches all leads by title, notes and/or custom fields. This endpoint is a wrapper of | Item type | Field |
|---|
| Deal | `custom_fields`, `notes`, `title` |
| Person | `custom_fields`, `email`, `name`, `notes`, `phone` |
| Organization | `address`, `custom_fields`, `name`, `notes` |
| Product | `code`, `custom_fields`, `name` |
| Lead | `custom_fields`, `notes`, `title` |
| File | `name` |
| Mail attachment | `name` |
| Project | `custom_fields`, `notes`, `title`, `description` |
| 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 |
'
enum:
- varchar
- text
- double
- phone
- date
- daterange
- time
- timerange
- set
- enum
- varchar_auto
- address
- monetary
- org
- people
- user
options:
type: array
description: Field options (required for enum and set field types)
items:
type: object
required:
- label
properties:
label:
type: string
description: The option label
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 project modal. Default is false.
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the project details view. Default is true.
default: true
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 deal stages. Default is false.'
default: false
stage_ids:
type: array
items:
type: integer
description: 'Array of deal stage IDs where this project field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false.'
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, the field is required when creating or updating projects. Default is false.'
default: false
responses:
'200':
description: Create one project 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
- 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)
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
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 deal 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
example:
success: true
data:
field_name: Category
field_code: 946947d1b02fd3ef20798d6112ec5d895a686a21
field_type: enum
options:
- id: 1
label: Internal
- id: 2
label: External
- id: 3
label: Research
subfields: null
is_custom_field: true
is_optional_response_field: false
ui_visibility:
add_visible_flag: true
details_visible_flag: true
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: false
'/projectFields/{field_code}':
get:
summary: Get one project field
description: Returns metadata about a specific project field.
x-token-cost: 1
operationId: getProjectField
tags:
- ProjectFields
- Beta
security:
- api_key: []
- oauth2:
- 'projects:read'
- 'projects:full'
- 'project-fields:full'
parameters:
- in: path
name: field_code
description: The unique code identifying the field
required: true
schema:
type: string
responses:
'200':
description: Get one project 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
- 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)
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
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 deal 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
example:
success: true
data:
field_name: Project Name
field_code: name
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
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: true
patch:
summary: Update one project field
description: Updates a project 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: updateProjectField
tags:
- ProjectFields
- Beta
security:
- api_key: []
- oauth2:
- 'project-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 project modal. Default is false.
default: false
details_visible_flag:
type: boolean
description: Whether the field is shown in the project details view. Default is true.
default: true
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 deal stages. Default is false.'
default: false
stage_ids:
type: array
items:
type: integer
description: 'Array of deal stage IDs where this project field should be highlighted as important. Must reference valid, active deal stages. Empty array when enabled is false.'
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, the field is required when creating or updating projects. Default is false.'
default: false
responses:
'200':
description: Get one project 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
- 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)
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
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 deal 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
example:
success: true
data:
field_name: Project Name
field_code: name
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
important_fields:
enabled: false
stage_ids: []
required_fields:
enabled: true
delete:
summary: Delete one project field
description: Marks a custom field as deleted.
x-token-cost: 3
operationId: deleteProjectField
tags:
- ProjectFields
- Beta
security:
- api_key: []
- oauth2:
- 'project-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 project 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
- 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)
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, 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
field_type: varchar
options: null
subfields: null
is_custom_field: true
is_optional_response_field: false
'/projectFields/{field_code}/options':
post:
summary: Add project field options in bulk
description: Adds new options to a project 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: addProjectFieldOptions
tags:
- ProjectFields
- Beta
security:
- api_key: []
- oauth2:
- 'project-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: Research & Development
additional_data: null
delete:
summary: Delete project field options in bulk
description: Removes existing options from a project 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: deleteProjectFieldOptions
tags:
- ProjectFields
- Beta
security:
- api_key: []
- oauth2:
- 'project-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: Research & Development
additional_data: null
patch:
summary: Update project field options in bulk
description: Updates existing options for a project 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: updateProjectFieldOptions
tags:
- ProjectFields
- Beta
security:
- api_key: []
- oauth2:
- 'project-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: Research & Development
additional_data: null
/projects:
get:
summary: Get all projects
description: Returns all non-archived projects.
x-token-cost: 10
operationId: getProjects
tags:
- Projects
security:
- api_key: []
- oauth2:
- 'projects:read'
- 'projects:full'
parameters:
- in: query
name: filter_id
schema:
type: integer
description: 'If supplied, only projects matching the specified filter are returned'
- in: query
name: status
schema:
type: string
example: 'open,completed'
description: 'If supplied, includes only projects with the specified statuses. Possible values are `open`, `completed`, `canceled` and `deleted`. By default `deleted` projects are not returned.'
- in: query
name: phase_id
schema:
type: integer
description: 'If supplied, only projects in the specified phase are returned'
- in: query
name: limit
description: '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.'
schema:
type: integer
example: 100
- in: query
name: cursor
required: false
schema:
type: string
description: 'For pagination, the marker (an opaque string value) representing the first item on the next page'
responses:
'200':
description: Get all projects
content:
application/json:
schema:
type: object
title: GetProjectsResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
type: array
description: Projects array
items:
title: Project
type: object
properties:
id:
type: integer
description: The ID of the project
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
health_status:
type: string
nullable: true
description: The health status of the project
add_time:
type: string
description: The creation date and time of the project in ISO 8601 format
update_time:
type: string
description: The last updated date and time of the project in ISO 8601 format
status_change_time:
type: string
description: The date and time of the last status change of the project in ISO 8601 format
archive_time:
type: string
nullable: true
description: 'The date and time the project was archived in ISO 8601 format. If not archived, this field is null.'
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
additional_data:
type: object
description: The additional data of the list
properties:
next_cursor:
type: string
description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
example:
success: true
data:
- id: 3
title: Project
description: Description
status: open
board_id: 1
phase_id: 1
owner_id: 1
start_date: '2026-04-15'
end_date: '2026-04-23'
deal_ids:
- 1
person_ids:
- 1
org_ids:
- 1
label_ids:
- 1
health_status: null
add_time: '2026-04-14T10:45:20.852Z'
update_time: '2026-04-14T10:45:20.852Z'
status_change_time: '2026-04-14T10:45:20.852Z'
archive_time: null
custom_fields: {}
additional_data:
next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
post:
summary: Add a project
description: Adds a new project. Custom fields should be wrapped in the `custom_fields` object.
x-token-cost: 5
operationId: addProject
tags:
- Projects
security:
- api_key: []
- oauth2:
- 'projects:full'
requestBody:
required: true
content:
application/json:
schema:
required:
- title
type: object
properties:
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
template_id:
type: integer
description: The ID of the template the project will be based on. Only used when creating a new project.
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
responses:
'201':
description: Add project
content:
application/json:
schema:
type: object
title: UpsertProjectResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
title: Project
type: object
properties:
id:
type: integer
description: The ID of the project
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
health_status:
type: string
nullable: true
description: The health status of the project
add_time:
type: string
description: The creation date and time of the project in ISO 8601 format
update_time:
type: string
description: The last updated date and time of the project in ISO 8601 format
status_change_time:
type: string
description: The date and time of the last status change of the project in ISO 8601 format
archive_time:
type: string
nullable: true
description: 'The date and time the project was archived in ISO 8601 format. If not archived, this field is null.'
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
example:
success: true
data:
id: 3
title: Project
description: Description
status: open
board_id: 1
phase_id: 1
owner_id: 1
start_date: '2026-04-15'
end_date: '2026-04-23'
deal_ids:
- 1
person_ids:
- 1
org_ids:
- 1
label_ids:
- 1
health_status: null
add_time: '2026-04-14T10:45:20.852Z'
update_time: '2026-04-14T10:45:20.852Z'
status_change_time: '2026-04-14T10:45:20.852Z'
archive_time: null
custom_fields: {}
/projects/archived:
get:
summary: Get all archived projects
description: Returns all archived projects.
x-token-cost: 10
operationId: getArchivedProjects
tags:
- Projects
security:
- api_key: []
- oauth2:
- 'projects:read'
- 'projects:full'
parameters:
- in: query
name: filter_id
schema:
type: integer
description: 'If supplied, only projects matching the specified filter are returned'
- in: query
name: status
schema:
type: string
example: 'open,completed'
description: 'If supplied, includes only projects with the specified statuses. Possible values are `open`, `completed`, `canceled` and `deleted`. By default `deleted` projects are not returned.'
- in: query
name: phase_id
schema:
type: integer
description: 'If supplied, only projects in the specified phase are returned'
- in: query
name: limit
description: '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.'
schema:
type: integer
example: 100
- in: query
name: cursor
required: false
schema:
type: string
description: 'For pagination, the marker (an opaque string value) representing the first item on the next page'
responses:
'200':
description: Get all projects
content:
application/json:
schema:
type: object
title: GetProjectsResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
type: array
description: Projects array
items:
title: Project
type: object
properties:
id:
type: integer
description: The ID of the project
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
health_status:
type: string
nullable: true
description: The health status of the project
add_time:
type: string
description: The creation date and time of the project in ISO 8601 format
update_time:
type: string
description: The last updated date and time of the project in ISO 8601 format
status_change_time:
type: string
description: The date and time of the last status change of the project in ISO 8601 format
archive_time:
type: string
nullable: true
description: 'The date and time the project was archived in ISO 8601 format. If not archived, this field is null.'
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
additional_data:
type: object
description: The additional data of the list
properties:
next_cursor:
type: string
description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
example:
success: true
data:
- id: 3
title: Project
description: Description
status: open
board_id: 1
phase_id: 1
owner_id: 1
start_date: '2026-04-15'
end_date: '2026-04-23'
deal_ids:
- 1
person_ids:
- 1
org_ids:
- 1
label_ids:
- 1
health_status: null
add_time: '2026-04-14T10:45:20.852Z'
update_time: '2026-04-14T10:45:20.852Z'
status_change_time: '2026-04-14T10:45:20.852Z'
archive_time: null
custom_fields: {}
additional_data:
next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
'/projects/{id}':
get:
summary: Get details of a project
description: Returns the details of a specific project. Custom fields appear as keys inside the `custom_fields` object.
x-token-cost: 1
operationId: getProject
tags:
- Projects
security:
- api_key: []
- oauth2:
- 'projects:read'
- 'projects:full'
parameters:
- in: path
name: id
description: The ID of the project
required: true
schema:
type: integer
responses:
'200':
description: Get project
content:
application/json:
schema:
type: object
title: UpsertProjectResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
title: Project
type: object
properties:
id:
type: integer
description: The ID of the project
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
health_status:
type: string
nullable: true
description: The health status of the project
add_time:
type: string
description: The creation date and time of the project in ISO 8601 format
update_time:
type: string
description: The last updated date and time of the project in ISO 8601 format
status_change_time:
type: string
description: The date and time of the last status change of the project in ISO 8601 format
archive_time:
type: string
nullable: true
description: 'The date and time the project was archived in ISO 8601 format. If not archived, this field is null.'
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
example:
success: true
data:
id: 3
title: Project
description: Description
status: open
board_id: 1
phase_id: 1
owner_id: 1
start_date: '2026-04-15'
end_date: '2026-04-23'
deal_ids:
- 1
person_ids:
- 1
org_ids:
- 1
label_ids:
- 1
health_status: null
add_time: '2026-04-14T10:45:20.852Z'
update_time: '2026-04-14T10:45:20.852Z'
status_change_time: '2026-04-14T10:45:20.852Z'
archive_time: null
custom_fields: {}
patch:
summary: Update a project
description: Updates the properties of a project.
x-token-cost: 5
operationId: updateProject
tags:
- Projects
security:
- api_key: []
- oauth2:
- 'projects:full'
parameters:
- in: path
name: id
description: The ID of the project
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
template_id:
type: integer
description: The ID of the template the project will be based on. Only used when creating a new project.
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
responses:
'200':
description: Update project
content:
application/json:
schema:
type: object
title: UpsertProjectResponse
allOf:
- title: baseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
- type: object
properties:
data:
title: Project
type: object
properties:
id:
type: integer
description: The ID of the project
title:
type: string
description: The title of the project
description:
type: string
description: The description of the project
status:
type: string
description: The status of the project
board_id:
type: integer
description: The ID of the board this project is associated with
phase_id:
type: integer
description: The ID of the phase this project is associated with
owner_id:
type: integer
description: The ID of the user who owns the project
start_date:
type: string
format: date
description: 'The start date of the project. Format: YYYY-MM-DD'
end_date:
type: string
format: date
description: 'The end date of the project. Format: YYYY-MM-DD'
deal_ids:
type: array
description: An array of IDs of the deals this project is associated with
items:
type: integer
person_ids:
type: array
description: An array of IDs of the persons this project is associated with
items:
type: integer
org_ids:
type: array
description: An array of IDs of the organizations this project is associated with
items:
type: integer
label_ids:
type: array
description: An array of IDs of the labels this project has
items:
type: integer
health_status:
type: string
nullable: true
description: The health status of the project
add_time:
type: string
description: The creation date and time of the project in ISO 8601 format
update_time:
type: string
description: The last updated date and time of the project in ISO 8601 format
status_change_time:
type: string
description: The date and time of the last status change of the project in ISO 8601 format
archive_time:
type: string
nullable: true
description: 'The date and time the project was archived in ISO 8601 format. If not archived, this field is null.'
custom_fields:
type: object
additionalProperties: true
description: 'An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error.'
example:
success: true
data:
id: 3
title: Project
description: Description
status: open
board_id: 1
phase_id: 1
owner_id: 1
start_date: '2026-04-15'
end_date: '2026-04-23'
deal_ids:
- 1
person_ids:
- 1
org_ids:
- 1
label_ids:
- 1
health_status: null
add_time: '2026-04-14T10:45:20.852Z'
update_time: '2026-04-14T10:45:20.852Z'
status_change_time: '2026-04-14T10:45:20.852Z'
archive_time: null
custom_fields: {}
delete:
summary: Delete a project
description: Marks a project as deleted.
x-token-cost: 3
operationId: deleteProject
tags:
- Projects
security:
- api_key: []
- oauth2:
- 'projects:full'
parameters:
- in: path
name: id
description: The ID of the project
required: true
schema:
type: integer
responses:
'200':
description: Delete project
content:
application/json:
schema:
title: DeleteProjectResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the deleted project
example:
success: true
data:
id: 3
/projectTemplates:
get:
summary: Get all project templates
description: Returns all not deleted project templates.
x-token-cost: 10
operationId: getProjectTemplates
tags:
- ProjectTemplates
security:
- api_key: []
- oauth2:
- 'projects:read'
- 'projects:full'
parameters:
- in: query
name: cursor
required: false
schema:
type: string
description: 'For pagination, the marker (an opaque string value) representing the first item on the next page'
- in: query
name: limit
description: '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.'
schema:
type: integer
example: 100
responses:
'200':
description: A list of project templates.
content:
application/json:
schema:
title: GetProjectTemplatesResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: array
items:
title: ProjectTemplate
type: object
properties:
id:
type: integer
description: The ID of the project template
title:
type: string
description: The title of the project template
description:
type: string
description: The description of the project template
projects_board_id:
type: integer
description: The ID of the project board this template is associated with
owner_id:
type: integer
description: The ID of the owner of the project template
add_time:
type: string
description: The creation date and time of the project template in ISO 8601 format
update_time:
type: string
description: The update date and time of the project template in ISO 8601 format
additional_data:
description: The additional data of the list
type: object
properties:
next_cursor:
type: string
description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
example:
success: true
data:
- id: 1
title: Office Renovation
description: Template for office renovation projects
projects_board_id: 2
owner_id: 3
add_time: '2023-09-14T08:14:40.000Z'
update_time: '2023-09-14T08:14:40.000Z'
additional_data:
next_cursor: eyJhY3Rpdml0aWVzIjoyN30
'/projectTemplates/{id}':
get:
summary: Get details of a template
description: Returns the details of a specific project template.
x-token-cost: 1
operationId: getProjectTemplate
tags:
- ProjectTemplates
security:
- api_key: []
- oauth2:
- 'projects:read'
- 'projects:full'
parameters:
- in: path
name: id
description: The ID of the project template
required: true
schema:
type: integer
responses:
'200':
description: Get a project template.
content:
application/json:
schema:
title: GetProjectTemplateResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
title: ProjectTemplate
type: object
properties:
id:
type: integer
description: The ID of the project template
title:
type: string
description: The title of the project template
description:
type: string
description: The description of the project template
projects_board_id:
type: integer
description: The ID of the project board this template is associated with
owner_id:
type: integer
description: The ID of the owner of the project template
add_time:
type: string
description: The creation date and time of the project template in ISO 8601 format
update_time:
type: string
description: The update date and time of the project template in ISO 8601 format
additional_data:
type: object
nullable: true
example: null
example:
success: true
data:
id: 1
title: Office Renovation
description: Template for office renovation projects
projects_board_id: 2
owner_id: 3
add_time: '2023-09-14T08:14:40.000Z'
update_time: '2023-09-14T08:14:40.000Z'
additional_data: null
/projects/search:
get:
summary: Search projects
description: 'Searches all projects by title, description, notes and/or custom fields. This endpoint is a wrapper of