Saltar al contenido principal
API docs by Redocly

Fintesk API v2 (2.0.27)

Download OpenAPI specification:Download

Activities

Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.

Delete multiple activities in bulk

Marks multiple activities as deleted. After 30 days, the activities will be permanently deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all activities assigned to a particular user

Returns all activities assigned to a particular user.

Authorizations:
bearerAuth
query Parameters
user_id
integer

The ID of the user whose activities will be fetched. If omitted, the user associated with the API token will be used. If 0, activities for all company users will be fetched based on the permission sets.

filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

type
string

The type of the activity, can be one type or multiple types separated by a comma. This is in correlation with the key_string parameter of ActivityTypes.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

start_date
string <date>

Use the activity due date where you wish to begin fetching activities from. Insert due date in YYYY-MM-DD format.

end_date
string <date>

Use the activity due date where you wish to stop fetching activities from. Insert due date in YYYY-MM-DD format.

done
number (doneNumberBoolean)
Enum: 0 1

Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted, returns both Done and Not done activities.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add an activity

Adds a new activity. Includes more_activities_scheduled_in_context property in response's additional_data which indicates whether there are more undone activities scheduled with the same deal, person or organization (depending on the supplied data). For more information, see the tutorial for adding an activity.

Authorizations:
bearerAuth
Request Body schema: application/json
person_id
integer

The ID of the person this Item is associated with

deal_id
integer

The ID of the deal this Item is associated with

org_id
integer

The ID of the organization this Item is associated with

due_date
string <date>

"The due date of the activity. Format: YYYY-MM-DD"

due_time
string

"The due time of the activity in UTC. Format: HH:MM"

duration
string

"The duration of the activity. Format: HH:MM"

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

created_by_user_id
integer

The ID of the user who created the item.

add_time
string <date-time>

The creation time in UTC. Format: YYYY-MM-DD HH:MM:SS

update_time
string <date-time>

The last update time in UTC. Format: YYYY-MM-DD HH:MM:SS

last_updated_by_user_id
integer

The ID of the user who created or most recently updated the item.

org_name
string

The name of the organization associated with the entity

person_name
string

The name of the peson associated with the entity

owner_name
string

The name of the owner associated with the entity

deal_name
string

The name of the deal this entity is associated with

company_id
integer

The ID of the company

id
integer

The ID of the activity, generated when the activity was created

done
number (doneNumberBoolean)
Enum: 0 1

Whether the activity is done or not. 0 = Not done, 1 = Done

subject
string

The subject of the activity

type
string

The type of the activity. This is in correlation with the key_string parameter of ActivityTypes.

assigned_to_user_id
integer

The ID of the user to whom the activity is assigned to. Equal to user_id.

user_id
integer

The ID of the user whom the activity is assigned to

participants
Array of objects or null

List of multiple persons (participants) this activity is associated with. It requires a structure as follows: [{"person_id":1,"primary_flag":true}]

marked_as_done_time
string

The date and time this activity was marked as done. Format: YYYY-MM-DD HH:MM:SS.

Responses

Request samples

Content type
application/json
{
  • "person_id": 0,
  • "deal_id": 0,
  • "org_id": 0,
  • "due_date": "2019-08-24",
  • "due_time": "string",
  • "duration": "string",
  • "active_flag": true,
  • "created_by_user_id": 0,
  • "add_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "last_updated_by_user_id": 0,
  • "org_name": "string",
  • "person_name": "string",
  • "owner_name": "string",
  • "deal_name": "string",
  • "company_id": 0,
  • "id": 0,
  • "done": 0,
  • "subject": "string",
  • "type": "string",
  • "assigned_to_user_id": 0,
  • "user_id": 0,
  • "participants": [
    ],
  • "marked_as_done_time": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Delete an activity

Marks an activity as deleted. After 30 days, the activity will be permanently deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get details of an activity

Returns the details of a specific activity.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Update an activity

Updates an activity. Includes more_activities_scheduled_in_context property in response's additional_data which indicates whether there are more undone activities scheduled with the same deal, person or organization (depending on the supplied data).

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
person_id
integer

The ID of the person this Item is associated with

deal_id
integer

The ID of the deal this Item is associated with

org_id
integer

The ID of the organization this Item is associated with

due_date
string <date>

"The due date of the activity. Format: YYYY-MM-DD"

due_time
string

"The due time of the activity in UTC. Format: HH:MM"

duration
string

"The duration of the activity. Format: HH:MM"

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

created_by_user_id
integer

The ID of the user who created the item.

add_time
string <date-time>

The creation time in UTC. Format: YYYY-MM-DD HH:MM:SS

update_time
string <date-time>

The last update time in UTC. Format: YYYY-MM-DD HH:MM:SS

last_updated_by_user_id
integer

The ID of the user who created or most recently updated the item.

org_name
string

The name of the organization associated with the entity

person_name
string

The name of the peson associated with the entity

owner_name
string

The name of the owner associated with the entity

deal_name
string

The name of the deal this entity is associated with

company_id
integer

The ID of the company

id
integer

The ID of the activity, generated when the activity was created

done
number (doneNumberBoolean)
Enum: 0 1

Whether the activity is done or not. 0 = Not done, 1 = Done

subject
string

The subject of the activity

type
string

The type of the activity. This is in correlation with the key_string parameter of ActivityTypes.

assigned_to_user_id
integer

The ID of the user to whom the activity is assigned to. Equal to user_id.

user_id
integer

The ID of the user whom the activity is assigned to

participants
Array of objects or null

List of multiple persons (participants) this activity is associated with. It requires a structure as follows: [{"person_id":1,"primary_flag":true}]

marked_as_done_time
string

The date and time this activity was marked as done. Format: YYYY-MM-DD HH:MM:SS.

Responses

Request samples

Content type
application/json
{
  • "person_id": 0,
  • "deal_id": 0,
  • "org_id": 0,
  • "due_date": "2019-08-24",
  • "due_time": "string",
  • "duration": "string",
  • "active_flag": true,
  • "created_by_user_id": 0,
  • "add_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "last_updated_by_user_id": 0,
  • "org_name": "string",
  • "person_name": "string",
  • "owner_name": "string",
  • "deal_name": "string",
  • "company_id": 0,
  • "id": 0,
  • "done": 0,
  • "subject": "string",
  • "type": "string",
  • "assigned_to_user_id": 0,
  • "user_id": 0,
  • "participants": [
    ],
  • "marked_as_done_time": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

ActivityFields

Activity fields represent different fields that an activity has.

Get all activity fields

Returns all activity fields.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

ActivityTypes

Activity types represent different kinds of activities that can be stored. Each activity type is presented to the user with an icon and a name. Additionally, a color can be defined (not implemented in the Fintesk app as of today). Activity types are linked to activities via ActivityType.key_string = Activity.type. The key_string will be generated by the API based on the given name of the activity type upon creation, and cannot be changed. Activity types should be presented to the user in an ordered manner, using the ActivityType.order_nr value.

Delete multiple activity types in bulk

Marks multiple activity types as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all activity types

Returns all activity types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Add new activity type

Adds a new activity type.

Authorizations:
bearerAuth
Request Body schema: application/json
order_nbr
integer

The position (index) of the Item. First order (order_nbr=0) is the default.

name
required
string

The name of the activity type

icon_key
required
string
Enum: "task" "email" "meeting" "deadline" "call" "lunch" "calendar" "downarrow" "document" "smartphone" "camera" "scissors" "cogs" "bubble" "uparrow" "checkbox" "signpost" "shuffle" "addressbook" "linegraph" "picture" "car" "world" "search" "clip" "sound" "brush" "key" "padlock" "pricetag" "suitcase" "finish" "plane" "loop" "wifi" "truck" "cart" "bulb" "bell" "presentation"

Icon graphic to use for representing this activity type

color
string

A designated color for the activity type in 6-character HEX format (e.g. FFFFFF for white, 000000 for black)

Responses

Request samples

Content type
application/json
{
  • "order_nbr": 0,
  • "name": "string",
  • "icon_key": "task",
  • "color": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete an activity type

Marks an activity type as deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an activity type

Updates an activity type.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
order_nbr
integer

The position (index) of the Item. First order (order_nbr=0) is the default.

name
string

The name of the activity type

icon_key
string
Enum: "task" "email" "meeting" "deadline" "call" "lunch" "calendar" "downarrow" "document" "smartphone" "camera" "scissors" "cogs" "bubble" "uparrow" "checkbox" "signpost" "shuffle" "addressbook" "linegraph" "picture" "car" "world" "search" "clip" "sound" "brush" "key" "padlock" "pricetag" "suitcase" "finish" "plane" "loop" "wifi" "truck" "cart" "bulb" "bell" "presentation"

Icon graphic to use for representing this activity type

color
string

A designated color for the activity type in 6-character HEX format (e.g. FFFFFF for white, 000000 for black)

Responses

Request samples

Content type
application/json
{
  • "order_nbr": 0,
  • "name": "string",
  • "icon_key": "task",
  • "color": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Currencies

Supported currencies which can be used to represent the monetary value of a deal, or a value of any monetary type custom field. The Currency.code field must be used to point to a currency. Currency.code is the ISO-4217 format currency code for non-custom currencies. You can differentiate custom and non-custom currencies using the is_custom_flag property.

Get all supported currencies

Returns all supported currencies in given account which should be used when saving monetary values with other objects. The code parameter of the returning objects is the currency code according to ISO 4217 for all non-custom currencies.

Authorizations:
bearerAuth
query Parameters
term
string

Optional search term that is searched for from currency's name and/or code

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

DealFields

Deal fields represent the near-complete schema for a deal in the context of the company of the authorized user. Each company can have a different schema for their deals, with various custom fields. In the context of using deal fields as a schema for defining the data fields of a deal, it must be kept in mind that some types of custom fields can have additional data fields which are not separate deal fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of deal fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one deal and list its keys.

Get all deal fields

Returns data about all deal fields.

Authorizations:
bearerAuth
query Parameters
limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "additional_data": {
    },
  • "data": {
    }
}

Add a new deal field

Adds a new deal field. For more information, see the tutorial for adding a new custom field.

Authorizations:
bearerAuth
Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

field_type
required
string
Enum: "date" "daterange" "double" "enum" "monetary" "org" "person" "phone" "set" "text" "time" "timerange" "user" "varchar"

The type of the field

Value Description
date Date (format YYYY-MM-DD)
daterange Date-range field (has a start date and end date value, both YYYY-MM-DD)
double Numeric value
enum Options field with a single possible chosen option
monetary Monetary field (has a numeric value and a currency value)
org Organization field (contains an organization ID which is stored on the same account)
person Person field (contains a person ID which is stored on the same account)
phone Phone field (up to 255 numbers and/or characters)
set Options field with a possibility of having multiple chosen options
text Long text (up to 65k characters)
time Time field (format HH:MM:SS)
timerange Time-range field (has a start time and end time value, both HH:MM:SS)
user User field (contains a user ID of another Fintesk user)
varchar Text (up to 255 characters)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true,
  • "field_type": "date"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete multiple deal fields in bulk

Marks multiple deal fields as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one deal field

Returns data about a specific deal field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a deal field

Marks a field as deleted. For more information, see the tutorial for deleting a custom field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a deal field

Updates a deal field. For more information, see the tutorial for updating custom fields' values.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Deals

Deals represent ongoing, lost or won sales to an organization or to a person. Each deal has a monetary value and must be placed in a stage. Deals can be owned by a user. Each deal consists of standard data fields but can also contain a number of custom fields. The custom fields can be recognized by long hashes as keys. These hashes can be mapped against DealField.key. The corresponding label for each such custom field can be obtained from DealField.name.

Get all deals

Returns all deals. For more information, see the tutorial for getting all deals.

Authorizations:
bearerAuth
query Parameters
user_id
integer

If supplied, only deals matching the given user will be returned. However, filter_id and owned_by_you takes precedence over user_id when supplied (if any of them apply for this endpoint).

filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

stage_id
integer

If supplied, only deals within the given stage will be returned

status
string
Default: "all_not_deleted"
Enum: "open" "won" "lost" "deleted" "all_not_deleted"

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included. The upper limit of found deals associated with the status is 2000.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

owned_by_you
number (ownedNumberBoolean)
Enum: 0 1

When supplied, only deals owned by you are returned. However, filter_id takes precedence over owned_by_you when both are supplied.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add a deal

Adds a new deal. All deals created through the Pipedrive API will have a origin set to API. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the dealFields and look for key values. For more information, see the tutorial for adding a deal.

Authorizations:
bearerAuth
Request Body schema: application/json
name
string

The name of the deal

origin_id
string or null

The optional ID to further distinguish the origin of the deal - e.g. Which API integration created this deal. If omitted, origin_id will be set to null.

channel
integer or null

The ID of Marketing channel this deal was created from. Provided value must be one of the channels configured for your company. You can fetch allowed values with GET /v1/dealFields If omitted, channel will be set to null.

channel_id
string or null

The optional ID to further distinguish the Marketing channel. If omitted, channel_id will be set to null.

add_time
string

The optional creation date & time of the Item in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

value
string

The value of the deal. If omitted, value will be set to 0.

currency
string

The currency of the deal. Accepts a 3-character currency code. Adding a new Deal: if omitted, currency will be set to the default currency of the authorized user.

user_id
integer

The ID of the user which will be the owner of the created deal. Adding a new Deal: If not provided, the user making the request will be used.

person_id
integer

The ID of a person which this deal will be linked to. If the person does not exist yet, it needs to be created first. Adding a new Deal: This property is required unless org_id is specified.

org_id
integer

The ID of an organization which this deal will be linked to. If the organization does not exist yet, it needs to be created first. Adding a new Deal: This property is required unless person_id is specified.

pipeline_id
integer

The ID of the pipeline this deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.

stage_id
integer

The ID of the stage this deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. Adding a new Deal: If omitted, the deal will be placed in the first stage of the default pipeline.

status
string
Enum: "open" "won" "lost" "deleted"

open = Open, won = Won, lost = Lost, deleted = Deleted. Adding a new Deal: If omitted, status will be set to open.

won_time
string

The optional date and time of changing the deal status as won in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Won. Can not be used together with lost_time.

lost_time
string

The optional date and time of changing the deal status as lost in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Lost. Can not be used together with won_time.

close_time
string or null

The optional date and time of closing the deal in UTC. Format: YYYY-MM-DD HH:MM:SS.

expected_close_date
string <date>

The expected close date of the deal. In ISO 8601 format: YYYY-MM-DD.

probability
number

The success probability percentage of the deal. Used/shown only when deal_probability for the pipeline of the deal is enabled.

lost_reason
string

The optional message about why the deal was lost (to be used when status = lost)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "string",
  • "channel": 0,
  • "channel_id": "string",
  • "add_time": "string",
  • "value": "string",
  • "currency": "string",
  • "user_id": 0,
  • "person_id": 0,
  • "org_id": 0,
  • "pipeline_id": 0,
  • "stage_id": 0,
  • "status": "open",
  • "won_time": "string",
  • "lost_time": "string",
  • "close_time": "string",
  • "expected_close_date": "2019-08-24",
  • "probability": 0,
  • "lost_reason": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Delete multiple deals in bulk

Marks multiple deals as deleted. After 30 days, the deals will be permanently deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Search deals

Searches all deals by title, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found deals can be filtered by the person ID and the organization ID.

Authorizations:
bearerAuth
query Parameters
term
required
string

The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

fields
string
Enum: "custom_fields" "notes" "title"

A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, and phone. Read more about searching by custom fields here

exact_match
boolean

When enabled, only full exact matches against the given term are returned. It is not case sensitive.

person_id
integer

Will filter deals by the provided person ID. The upper limit of found deals associated with the person is 2000.

organization_id
integer

Will filter items by the provided organization ID. The upper limit of found items associated with the organization is 2000.

status
string
Default: "all_not_deleted"
Enum: "open" "won" "lost" "deleted" "all_not_deleted"

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included. The upper limit of found deals associated with the status is 2000.

start
integer
Default: 0

For pagination, the position that represents the first result for the page. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    }
}

Get deals summary

Returns a summary of all the deals.

Authorizations:
bearerAuth
query Parameters
filter_id
integer

user_id will not be considered. Only deals matching the given filter will be returned.

user_id
integer

If supplied, only deals matching the given user will be returned. However, filter_id and owned_by_you takes precedence over user_id when supplied (if any of them apply for this endpoint).

stage_id
integer

If supplied, only deals within the given stage will be returned

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get deals timeline Deprecated

Returns open and won deals, grouped by a defined interval of time set in a date-type dealField (field_key) - e.g. when month is the chosen interval, and 3 months are asked starting from January 1st, 2023, deals are returned grouped into 3 groups - January, February and March - based on the value of the given field_key.

Authorizations:
bearerAuth
query Parameters
start_date
required
string <date>

The date when the first interval starts. Format: YYYY-MM-DD.

interval
required
string
Enum: "day" "week" "month" "quarter"

The type of the interval

ValueDescription
dayDay
weekA full week (7 days) starting from start_date
monthA full month (depending on the number of days in given month) starting from start_date
quarterA full quarter (3 months) starting from start_date

amount
required
integer

The number of given intervals, starting from start_date, to fetch. E.g. 3 (months).

field_key
required
string

The date field key which deals will be retrieved from

user_id
integer

If supplied, only deals matching the given user will be returned. However, filter_id and owned_by_you takes precedence over user_id when supplied (if any of them apply for this endpoint).

pipeline_id
integer

If supplied, only deals matching the given pipeline will be returned

filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

exclude_deals
number (excludeNumberBoolean)
Enum: 0 1

Whether to exclude deals list (1) or not (0). Note that when deals are excluded, the timeline summary (counts and values) is still returned.

totals_convert_currency
string

The 3-letter currency code of any of the supported currencies. When supplied, per_stages_converted is returned inside deals_summary inside additional_data which contains the currency-converted total amounts in the given currency per each stage. You may also set this parameter to default_currency in which case users default currency is used. If get_summary is present in this endpoint, Only works when get_summary parameter flag is enabled.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a deal

Marks a deal as deleted. After 30 days, the deal will be permanently deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get details of a deal

Returns the details of a specific deal. Note that this also returns some additional fields which are not present when asking for all deals – such as deal age and stay in pipeline stages. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of dealFields. For more information, see the tutorial for getting details of a deal.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": { },
  • "related_objects": {
    }
}

Update a deal

Updates the properties of a deal. For more information, see the tutorial for updating a deal.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
name
string

The name of the deal

origin_id
string or null

The optional ID to further distinguish the origin of the deal - e.g. Which API integration created this deal. If omitted, origin_id will be set to null.

channel
integer or null

The ID of Marketing channel this deal was created from. Provided value must be one of the channels configured for your company. You can fetch allowed values with GET /v1/dealFields If omitted, channel will be set to null.

channel_id
string or null

The optional ID to further distinguish the Marketing channel. If omitted, channel_id will be set to null.

add_time
string

The optional creation date & time of the Item in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

value
string

The value of the deal. If omitted, value will be set to 0.

currency
string

The currency of the deal. Accepts a 3-character currency code. Adding a new Deal: if omitted, currency will be set to the default currency of the authorized user.

user_id
integer

The ID of the user which will be the owner of the created deal. Adding a new Deal: If not provided, the user making the request will be used.

person_id
integer

The ID of a person which this deal will be linked to. If the person does not exist yet, it needs to be created first. Adding a new Deal: This property is required unless org_id is specified.

org_id
integer

The ID of an organization which this deal will be linked to. If the organization does not exist yet, it needs to be created first. Adding a new Deal: This property is required unless person_id is specified.

pipeline_id
integer

The ID of the pipeline this deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.

stage_id
integer

The ID of the stage this deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. Adding a new Deal: If omitted, the deal will be placed in the first stage of the default pipeline.

status
string
Enum: "open" "won" "lost" "deleted"

open = Open, won = Won, lost = Lost, deleted = Deleted. Adding a new Deal: If omitted, status will be set to open.

won_time
string

The optional date and time of changing the deal status as won in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Won. Can not be used together with lost_time.

lost_time
string

The optional date and time of changing the deal status as lost in UTC. Format: YYYY-MM-DD HH:MM:SS. Can be set only when deal status is already Lost. Can not be used together with won_time.

close_time
string or null

The optional date and time of closing the deal in UTC. Format: YYYY-MM-DD HH:MM:SS.

expected_close_date
string <date>

The expected close date of the deal. In ISO 8601 format: YYYY-MM-DD.

probability
number

The success probability percentage of the deal. Used/shown only when deal_probability for the pipeline of the deal is enabled.

lost_reason
string

The optional message about why the deal was lost (to be used when status = lost)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "origin_id": "string",
  • "channel": 0,
  • "channel_id": "string",
  • "add_time": "string",
  • "value": "string",
  • "currency": "string",
  • "user_id": 0,
  • "person_id": 0,
  • "org_id": 0,
  • "pipeline_id": 0,
  • "stage_id": 0,
  • "status": "open",
  • "won_time": "string",
  • "lost_time": "string",
  • "close_time": "string",
  • "expected_close_date": "2019-08-24",
  • "probability": 0,
  • "lost_reason": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

List activities associated with a deal

Lists activities associated with a deal.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

done
number (doneNumberBoolean)
Enum: 0 1

Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted, returns both Done and Not done activities.

exclude
string

A comma-separated string of activity IDs to exclude from result

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List updates about a deal

Lists updates about a deal.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

all_changes
string

Whether to show custom field updates or not. 1 = Include custom field changes. If omitted, returns changes without custom field updates.

items
string

A comma-separated string for filtering out item specific updates. (Possible values - activity, note, deal, dealChange, personChange, organizationChange).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List all persons associated with a deal

Lists all persons associated with a deal, regardless of whether the person is the primary contact of the deal, or added as a participant.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List products attached to a deal

Lists products attached to a deal.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

include_product_data
number (queryNumberBoolean)
Enum: 0 1

Whether to fetch product data along with each attached product (1) or not (0, default)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add a product to a deal

Adds a product to a deal, creating a new item called a deal-product.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
product_id
required
integer

The ID of the product

duration_unit
string (dealProductUnitDuration)
Enum: "hourly" "daily" "weekly" "monthly" "yearly"

The unit duration of the product

tax
number
Default: 0

The tax percentage

duration
integer
Default: 1

The duration of the product

discount
number
Default: 0

The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage

discount_type
string
Default: "percentage"
Enum: "percentage" "amount"

The type of the discount's value

product_variation_id
integer or null

The ID of the product variation. When omitted, no variation will be used

tax_method
string
Enum: "exclusive" "inclusive" "none"

The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal

enabled_flag
boolean
Default: true

Whether the product is enabled or not. This makes it possible to add products to a deal with a specific price and discount criteria, but keep them disabled, which refrains them from being included in the deal value calculation. When omitted, the product will be marked as enabled by default

item_price
required
number

The price at which this product will be added to the deal

quantity
required
integer

How many items of this product will be added to the deal

comments
string

A textual comment associated with this product-deal attachment

Responses

Request samples

Content type
application/json
{
  • "product_id": 0,
  • "duration_unit": "hourly",
  • "tax": 0,
  • "duration": 1,
  • "discount": 0,
  • "discount_type": "percentage",
  • "product_variation_id": 0,
  • "tax_method": "exclusive",
  • "enabled_flag": true,
  • "item_price": 0,
  • "quantity": 0,
  • "comments": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update the product attached to a deal

Updates the details of the product that has been attached to a deal.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

product_attachment_id
required
integer

The ID of the deal-product (the ID of the product attached to the deal)

Request Body schema: application/json
product_id
integer

The ID of the product

duration_unit
string (dealProductUnitDuration)
Enum: "hourly" "daily" "weekly" "monthly" "yearly"

The unit duration of the product

tax
number
Default: 0

The tax percentage

duration
integer
Default: 1

The duration of the product

discount
number
Default: 0

The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage

discount_type
string
Default: "percentage"
Enum: "percentage" "amount"

The type of the discount's value

product_variation_id
integer or null

The ID of the product variation. When omitted, no variation will be used

tax_method
string
Enum: "exclusive" "inclusive" "none"

The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal

enabled_flag
boolean
Default: true

Whether the product is enabled or not. This makes it possible to add products to a deal with a specific price and discount criteria, but keep them disabled, which refrains them from being included in the deal value calculation. When omitted, the product will be marked as enabled by default

item_price
number

The price at which this product will be added to the deal

quantity
integer

How many items of this product will be added to the deal

comments
string

A textual comment associated with this product-deal attachment

Responses

Request samples

Content type
application/json
{
  • "product_id": 0,
  • "duration_unit": "hourly",
  • "tax": 0,
  • "duration": 1,
  • "discount": 0,
  • "discount_type": "percentage",
  • "product_variation_id": 0,
  • "tax_method": "exclusive",
  • "enabled_flag": true,
  • "item_price": 0,
  • "quantity": 0,
  • "comments": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete an attached product from a deal

Deletes a product attachment from a deal, using the product_attachment_id.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

product_attachment_id
required
integer

The ID of the deal-product (the ID of the product attached to the deal)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Filters

Each filter is essentially a set of data validation conditions. A filter of the same kind can be applied when fetching a list of deals, persons, organizations or products in the context of a pipeline. Filters are limited to a maximum of 16 conditions. When applied, only items matching the conditions of the filter are returned. Detailed definitions of filter conditions and additional functionality is not yet available.

Delete multiple filters in bulk

Marks multiple filters as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all filters

Returns data about all filters.

Authorizations:
bearerAuth
query Parameters
type
string
Enum: "deals" "org" "persons" "products" "activity"

The types of filters to fetch

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Add a new filter

Adds a new filter, returns the ID upon success. Note that in the conditions JSON object only one first-level condition group is supported, and it must be glued with 'AND', and only two second level condition groups are supported of which one must be glued with 'AND' and the second with 'OR'. Other combinations do not work (yet) but the syntax supports introducing them in future. For more information, see the tutorial for adding a filter.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the filter

conditions
required
object

The conditions of the filter as a JSON object. Please note that a maximum of 16 conditions is allowed per filter and date values must be supplied in the YYYY-MM-DD format. It requires a minimum structure as follows: {"glue":"and","conditions": [{ "glue":"and", "conditions": [CONDITION_OBJECTS] }, {"glue":"or", "conditions": [CONDITION_OBJECTS] }] }. Replace CONDITION_OBJECTS with JSON objects of the following structure: {"object":"", "field_id":"", "operator":"", "value":"", "extra_value":"" } or leave the array empty. Depending on the object type you should use another API endpoint to get field_id. There are five types of objects you can choose from: "person", "deal", "organization", "product", "activity" and you can use these types of operators depending on what type of a field you have: "IS NOT NULL", "IS NULL", "<=", ">=", "<", ">", "!=", "=", "LIKE '$%'", "LIKE '%$%'", "NOT LIKE '$%'". To get a better understanding of how filters work try creating them directly from the Fintesk application.

type
required
string
Enum: "deals" "org" "persons" "products" "activity"

The type of filter to create

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "conditions": { },
  • "type": "deals"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all filter helpers

Returns all supported filter helpers. It helps to know what conditions and helpers are available when you want to add or update filters. For more information, see the tutorial for adding a filter.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { }
}

Delete a filter

Marks a filter as deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one filter

Returns data about a specific filter. Note that this also returns the condition lines of the filter.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a filter

Updates an existing filter.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
name
string

The name of the filter

conditions
required
object

The conditions of the filter as a JSON object. Please note that a maximum of 16 conditions is allowed per filter and date values must be supplied in the YYYY-MM-DD format. It requires a minimum structure as follows: {"glue":"and","conditions": [{ "glue":"and", "conditions": [CONDITION_OBJECTS] }, {"glue":"or", "conditions": [CONDITION_OBJECTS] }] }. Replace CONDITION_OBJECTS with JSON objects of the following structure: {"object":"", "field_id":"", "operator":"", "value":"", "extra_value":"" } or leave the array empty. Depending on the object type you should use another API endpoint to get field_id. There are five types of objects you can choose from: "person", "deal", "organization", "product", "activity" and you can use these types of operators depending on what type of a field you have: "IS NOT NULL", "IS NULL", "<=", ">=", "<", ">", "!=", "=", "LIKE '$%'", "LIKE '%$%'", "NOT LIKE '$%'". To get a better understanding of how filters work try creating them directly from the Fintesk application.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "conditions": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

ItemSearch

Ordered reference objects, pointing to either deals, persons, organizations, or products.

Perform a search from multiple item types

Performs a search from your choice of item types and fields.

Authorizations:
bearerAuth
query Parameters
item_types
string
Enum: "deal" "person" "organization" "product" "lead" "file" "mail_attachment" "project"

A comma-separated string array. The type of items to perform the search from. Defaults to all.

fields
string
Enum: "address" "code" "custom_fields" "email" "name" "notes" "organization_name" "person_name" "phone" "title" "description"

A comma-separated string array. The fields to perform the search from. Defaults to all. Relevant for each item type are:

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

Only the following custom field types are searchable: `address`, `varchar`, `text`, and `phone`. Read more about searching by custom fields [here](../../kb/getting-started/search-finding-what-you-need#searching-by-custom-fields).
search_for_related_items
boolean

When enabled, the response will include up to 100 newest related leads and 100 newest related deals for each found person and organization and up to 100 newest related persons for each found organization

include_fields
string
Enum: "deal.cc_email" "person.picture" "product.price"

A comma-separated string array. Supports including optional fields in the results which are not provided by default.

term
required
string

The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

exact_match
boolean

When enabled, only full exact matches against the given term are returned. It is not case sensitive.

start
integer
Default: 0

For pagination, the position that represents the first result for the page. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    }
}

Perform a search using a specific field from an item type

Performs a search from the values of a specific field. Results can either be the distinct values of the field (useful for searching autocomplete field values), or the IDs of actual items (deals, leads, persons, organizations or products).

Authorizations:
bearerAuth
query Parameters
field_type
required
string
Enum: "dealField" "personField" "organizationField" "productField"

The type of the field to perform the search from

field_key
required
string

The key of the field to search from. The field key can be obtained by fetching the list of the fields using any of the fields' API GET methods (dealFields, personFields, etc.). Only the following custom field types are searchable: address, varchar, text, and phone. Read more about searching by custom fields here.

return_item_ids
boolean

Whether to return the IDs of the matching items or not. When not set or set to 0 or false, only distinct values of the searched field are returned. When set to 1 or true, the ID of each found item is returned.

term
required
string

The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

exact_match
boolean

When enabled, only full exact matches against the given term are returned. It is not case sensitive.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

OrganizationFields

Organization fields represent the near-complete schema for an organization in the context of the company of the authorized user. Each company can have a different schema for their organizations, with various custom fields. In the context of using organization fields as a schema for defining the data fields of an organization, it must be kept in mind that some types of custom fields can have additional data fields which are not separate organization fields per se. Such is the case with monetary, daterange and timerange fields - each of these fields will have one additional data field in addition to the one presented in the context of organization fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one organization and list its keys.

Get all organization fields

Returns data about all organization fields.

Authorizations:
bearerAuth
query Parameters
limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Add a new organization field

Adds a new organization field. For more information, see the tutorial for adding a new custom field.

Authorizations:
bearerAuth
Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

field_type
required
string
Enum: "date" "daterange" "double" "enum" "monetary" "org" "person" "phone" "set" "text" "time" "timerange" "user" "varchar"

The type of the field

Value Description
date Date (format YYYY-MM-DD)
daterange Date-range field (has a start date and end date value, both YYYY-MM-DD)
double Numeric value
enum Options field with a single possible chosen option
monetary Monetary field (has a numeric value and a currency value)
org Organization field (contains an organization ID which is stored on the same account)
person Person field (contains a person ID which is stored on the same account)
phone Phone field (up to 255 numbers and/or characters)
set Options field with a possibility of having multiple chosen options
text Long text (up to 65k characters)
time Time field (format HH:MM:SS)
timerange Time-range field (has a start time and end time value, both HH:MM:SS)
user User field (contains a user ID of another Fintesk user)
varchar Text (up to 255 characters)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true,
  • "field_type": "date"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete multiple organization fields in bulk

Marks multiple fields as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one organization field

Returns data about a specific organization field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "additional_data": {
    },
  • "data": {
    }
}

Delete an organization field

Marks a field as deleted. For more information, see the tutorial for deleting a custom field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update an organization field

Updates an organization field. For more information, see the tutorial for updating custom fields' values.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

OrganizationRelationships

Organization relationships represent how different organizations are related to each other. The relationship can be hierarchical (parent-child companies) or lateral as defined by the type field - either parent or related.

Organizations

Organizations are companies and other kinds of organizations you are making deals with. Persons can be associated with organizations so that each organization can contain one or more persons.

Delete multiple organizations in bulk

Marks multiple organizations as deleted. After 30 days, the organizations will be permanently deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all organizations

Returns all organizations.

Authorizations:
bearerAuth
query Parameters
user_id
integer

If supplied, only organizations owned by the given user will be returned. However, filter_id takes precedence over user_id when both are supplied.

filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

first_char
string

If supplied, only entities whose name starts with the specified letter will be returned (case-insensitive)

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add an organization

Adds a new organization. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the organizationFields and look for key values. For more information, see the tutorial for adding an organization.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the organization

add_time
string

The optional creation date & time of the organization in UTC. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

allOf
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "add_time": "string",
  • "allOf": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Search organizations

Searches all organizations by name, address, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.

Authorizations:
bearerAuth
query Parameters
term
required
string

The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

fields
string
Enum: "address" "custom_fields" "notes" "name"

A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, and phone. Read more about searching by custom fields here.

exact_match
boolean

When enabled, only full exact matches against the given term are returned. It is not case sensitive.

start
integer
Default: 0

For pagination, the position that represents the first result for the page. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    }
}

Delete an organization

Marks an organization as deleted. After 30 days, the organization will be permanently deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get details of an organization

Returns the details of an organization. Note that this also returns some additional fields which are not present when asking for all organizations. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of organizationFields.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Update an organization

Updates the properties of an organization.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
name
string

The name of the organization

allOf
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "allOf": null
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

List activities associated with an organization

Lists activities associated with an organization.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

done
number (doneNumberBoolean)
Enum: 0 1

Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted, returns both Done and Not done activities.

exclude
string

A comma-separated string of activity IDs to exclude from result

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

List deals associated with an organization

Lists deals associated with an organization.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

status
string
Default: "all_not_deleted"
Enum: "open" "won" "lost" "deleted" "all_not_deleted"

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included. The upper limit of found deals associated with the status is 2000.

sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List files attached to an organization Deprecated

Lists files associated with an organization.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, product_id, add_time, update_time, comment.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

List updates about an organization

Lists updates about an organization.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

all_changes
string

Whether to show custom field updates or not. 1 = Include custom field changes. If omitted, returns changes without custom field updates.

items
string

A comma-separated string for filtering out item specific updates. (Possible values - activity, note, deal).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List persons of an organization

Lists persons associated with an organization.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

PersonFields

Person fields represent the near-complete schema for a person in the context of the company of the authorized user. Each company can have a different schema for their persons, with various custom fields. In the context of using person fields as a schema for defining the data fields of a person, it must be kept in mind that some types of custom fields can have additional data fields which are not separate person fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of person fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one person and list its keys.

Get all person fields

Returns data about all person fields.
If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

Authorizations:
bearerAuth
query Parameters
limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "additional_data": {
    },
  • "data": {
    }
}

Add a new person field

Adds a new person field. For more information, see the tutorial for adding a new custom field.

Authorizations:
bearerAuth
Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

field_type
required
string
Enum: "date" "daterange" "double" "enum" "monetary" "org" "person" "phone" "set" "text" "time" "timerange" "user" "varchar"

The type of the field

Value Description
date Date (format YYYY-MM-DD)
daterange Date-range field (has a start date and end date value, both YYYY-MM-DD)
double Numeric value
enum Options field with a single possible chosen option
monetary Monetary field (has a numeric value and a currency value)
org Organization field (contains an organization ID which is stored on the same account)
person Person field (contains a person ID which is stored on the same account)
phone Phone field (up to 255 numbers and/or characters)
set Options field with a possibility of having multiple chosen options
text Long text (up to 65k characters)
time Time field (format HH:MM:SS)
timerange Time-range field (has a start time and end time value, both HH:MM:SS)
user User field (contains a user ID of another Fintesk user)
varchar Text (up to 255 characters)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true,
  • "field_type": "date"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete multiple person fields in bulk

Marks multiple fields as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one person field

Returns data about a specific person field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a person field

Marks a field as deleted. For more information, see the tutorial for deleting a custom field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a person field

Updates a person field. For more information, see the tutorial for updating custom fields' values.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Persons

Persons are your contacts, the customers you are doing deals with. Each person can belong to an organization. Persons should not be confused with users.

Delete multiple persons in bulk

Marks multiple persons as deleted. After 30 days, the persons will be permanently deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all persons

Returns all persons.

Authorizations:
bearerAuth
query Parameters
user_id
integer

If supplied, only persons owned by the given user will be returned. However, filter_id takes precedence over user_id when both are supplied.

filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

first_char
string

If supplied, only entities whose name starts with the specified letter will be returned (case-insensitive)

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add a person

Adds a new person. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys. To determine which custom fields exists, fetch the personFields and look for key values.
If a company uses the Campaigns product, then this endpoint will also accept and return the data.marketing_status field.

Authorizations:
bearerAuth
Request Body schema: application/json
Array of objects (s_person_item_phone_array)

A phone number supplied as a string or an array of phone objects related to the person. The structure of the array is as follows: [{ "value": "12345", "primary": "true", "label": "mobile" }]. Please note that only value is required.

Array of objects (s_person_item_email_array)

An email address as a string or an array of email objects related to the person. The structure of the array is as follows: [{ "value": "mail@example.com", "primary": "true", "label": "main" }]. Please note that only value is required.

name
string

The name of the person

add_time
string

The optional creation date & time of the Item in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

org_id
integer

The ID of the organization this Item is associated with

owner_id
integer

The ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.

Responses

Request samples

Content type
application/json
{
  • "phone": [
    ],
  • "email": [
    ],
  • "name": "string",
  • "add_time": "string",
  • "org_id": 0,
  • "owner_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Search persons

Searches all persons by name, email, phone, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found persons can be filtered by organization ID.

Authorizations:
bearerAuth
query Parameters
term
required
string

The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

fields
string
Enum: "custom_fields" "email" "notes" "phone" "name"

A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, and phone. Read more about searching by custom fields here.

exact_match
boolean

When enabled, only full exact matches against the given term are returned. It is not case sensitive.

organization_id
integer

Will filter items by the provided organization ID. The upper limit of found items associated with the organization is 2000.

include_fields
string
Value: "person.picture"

Supports including optional fields in the results which are not provided by default

start
integer
Default: 0

For pagination, the position that represents the first result for the page. Note that the pagination is based on main results and does not include related items when using search_for_related_items parameter.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    }
}

Delete a person

Marks a person as deleted. After 30 days, the person will be permanently deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get details of a person

Returns the details of a person. Note that this also returns some additional fields which are not present when asking for all persons. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the key value of personFields.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": { },
  • "related_objects": {
    }
}

Update a person

Updates the properties of a person. For more information, see the tutorial for updating a person.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
Array of objects (s_person_item_phone_array)

A phone number supplied as a string or an array of phone objects related to the person. The structure of the array is as follows: [{ "value": "12345", "primary": "true", "label": "mobile" }]. Please note that only value is required.

Array of objects (s_person_item_email_array)

An email address as a string or an array of email objects related to the person. The structure of the array is as follows: [{ "value": "mail@example.com", "primary": "true", "label": "main" }]. Please note that only value is required.

name
string

The name of the person

add_time
string

The optional creation date & time of the Item in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

org_id
integer

The ID of the organization this Item is associated with

owner_id
integer

The ID of the user who will be marked as the owner of this person. When omitted, the authorized user ID will be used.

Responses

Request samples

Content type
application/json
{
  • "phone": [
    ],
  • "email": [
    ],
  • "name": "string",
  • "add_time": "string",
  • "org_id": 0,
  • "owner_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

List activities associated with a person

Lists activities associated with a person.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

done
number (doneNumberBoolean)
Enum: 0 1

Whether the activity is done or not. 0 = Not done, 1 = Done. If omitted, returns both Done and Not done activities.

exclude
string

A comma-separated string of activity IDs to exclude from result

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

List deals associated with a person

Lists deals associated with a person.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

status
string
Default: "all_not_deleted"
Enum: "open" "won" "lost" "deleted" "all_not_deleted"

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included. The upper limit of found deals associated with the status is 2000.

sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List updates about a person

Lists updates about a person.
If a company uses the Campaigns product, then this endpoint's response will also include updates for the marketing_status field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

all_changes
string

Whether to show custom field updates or not. 1 = Include custom field changes. If omitted, returns changes without custom field updates.

items
string

A comma-separated string for filtering out item specific updates. (Possible values - activity, note, deal).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

List products associated with a person

Lists products associated with a person.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Pipelines

Pipelines are essentially ordered collections of stages.

Get all pipelines

Returns data about all pipelines.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Add a new pipeline

Adds a new pipeline.

Authorizations:
bearerAuth
Request Body schema: application/json
order_nbr
integer

The position (index) of the Item. First order (order_nbr=0) is the default.

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

created_by_user_id
integer

The ID of the user who created the item.

add_time
string <date-time>

The creation time in UTC. Format: YYYY-MM-DD HH:MM:SS

update_time
string <date-time>

The last update time in UTC. Format: YYYY-MM-DD HH:MM:SS

last_updated_by_user_id
integer

The ID of the user who created or most recently updated the item.

deal_probability
number (numberBoolean)
Enum: 0 1

Whether deal probability is disabled or enabled for this pipeline

name
required
string

The name of the pipeline

Responses

Request samples

Content type
application/json
{
  • "order_nbr": 0,
  • "active_flag": true,
  • "created_by_user_id": 0,
  • "add_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "last_updated_by_user_id": 0,
  • "deal_probability": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a pipeline

Marks a pipeline as deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one pipeline

Returns data about a specific pipeline. Also returns the summary of the deals in this pipeline across its stages.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
totals_convert_currency
string

The 3-letter currency code of any of the supported currencies. When supplied, per_stages_converted is returned inside deals_summary inside additional_data which contains the currency-converted total amounts in the given currency per each stage. You may also set this parameter to default_currency in which case users default currency is used. If get_summary is present in this endpoint, Only works when get_summary parameter flag is enabled.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a pipeline

Updates the properties of a pipeline.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
order_nbr
integer

The position (index) of the Item. First order (order_nbr=0) is the default.

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

created_by_user_id
integer

The ID of the user who created the item.

add_time
string <date-time>

The creation time in UTC. Format: YYYY-MM-DD HH:MM:SS

update_time
string <date-time>

The last update time in UTC. Format: YYYY-MM-DD HH:MM:SS

last_updated_by_user_id
integer

The ID of the user who created or most recently updated the item.

deal_probability
number (numberBoolean)
Enum: 0 1

Whether deal probability is disabled or enabled for this pipeline

name
string

The name of the pipeline

Responses

Request samples

Content type
application/json
{
  • "order_nbr": 0,
  • "active_flag": true,
  • "created_by_user_id": 0,
  • "add_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "last_updated_by_user_id": 0,
  • "deal_probability": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get deals in a pipeline

Lists deals in a specific pipeline across all its stages.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

user_id
integer

If supplied, filter_id will not be considered and only deals owned by the given user will be returned. If omitted, deals owned by the authorized user will be returned.

everyone
number (numberBoolean)
Enum: 0 1

If supplied, filter_id and user_id will not be considered – instead, deals owned by everyone will be returned

stage_id
integer

If supplied, only deals within the given stage will be returned

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

get_summary
number (numberBoolean)
Enum: 0 1

Whether to include a summary of the pipeline in the additional_data or not

totals_convert_currency
string

The 3-letter currency code of any of the supported currencies. When supplied, per_stages_converted is returned inside deals_summary inside additional_data which contains the currency-converted total amounts in the given currency per each stage. You may also set this parameter to default_currency in which case users default currency is used. If get_summary is present in this endpoint, Only works when get_summary parameter flag is enabled.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

ProductFields

Product fields represent the near-complete schema for a product in the context of the company of the authorized user. Each company can have a different schema for their products, with various custom fields. In the context of using product fields as a schema for defining the data fields of a product, it must be kept in mind that some types of custom fields can have additional data fields which are not separate product fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of product fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one product and list its keys.

Delete multiple product fields in bulk

Marks multiple fields as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all product fields

Returns data about all product fields.

Authorizations:
bearerAuth
query Parameters
limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Add a new product field

Adds a new product field. For more information, see the tutorial for adding a new custom field.

Authorizations:
bearerAuth
Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
required
string

The name of the field

add_visible_flag
boolean
Default: true

Whether the field is available in the 'add new' modal or not (in the web app)

field_type
required
string
Enum: "date" "daterange" "double" "enum" "monetary" "org" "person" "phone" "set" "text" "time" "timerange" "user" "varchar"

The type of the field

Value Description
date Date (format YYYY-MM-DD)
daterange Date-range field (has a start date and end date value, both YYYY-MM-DD)
double Numeric value
enum Options field with a single possible chosen option
monetary Monetary field (has a numeric value and a currency value)
org Organization field (contains an organization ID which is stored on the same account)
person Person field (contains a person ID which is stored on the same account)
phone Phone field (up to 255 numbers and/or characters)
set Options field with a possibility of having multiple chosen options
text Long text (up to 65k characters)
time Time field (format HH:MM:SS)
timerange Time-range field (has a start time and end time value, both HH:MM:SS)
user User field (contains a user ID of another Fintesk user)
varchar Text (up to 255 characters)

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string",
  • "add_visible_flag": true,
  • "field_type": "date"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a product field

Marks a product field as deleted. For more information, see the tutorial for deleting a custom field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one product field

Returns data about a specific product field.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a product field

Updates a product field. For more information, see the tutorial for updating custom fields' values.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity Field we want to retrieve.

Request Body schema: application/json
options
Array of objects or null

The options of the field. When there are no options, null is returned. When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}]

name
string

The name of the field

Responses

Request samples

Content type
application/json
{
  • "options": [
    ],
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Products

Products are the goods or services you are dealing with. Each product can have N different price points - firstly, each product can have a price in N different currencies, and secondly, each product can have N variations of itself, each having N prices in different currencies.

Note that only one price per variation per currency is supported. Products can be instantiated to deals. In the context of instatiation, a custom price, quantity, duration and discount can be applied.

Get all products

Returns data about all products.

Authorizations:
bearerAuth
query Parameters
user_id
integer

If supplied, only products owned by the given user will be returned

filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

ids
Array of integers

An array of integers with the IDs of the products that should be returned in the response

first_char
string

If supplied, only entities whose name starts with the specified letter will be returned (case-insensitive)

get_summary
boolean

If supplied, the response will return the total numbers of products in the additional_data.summary.total_count property

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add a product

Adds a new product to the Products inventory. For more information, see the tutorial for adding a product.

Authorizations:
bearerAuth
Request Body schema: application/json
code
string

The product code

prices
Array of objects

An array of objects, each containing: currency (string), price (number), cost (number, optional), overhead_cost (number, optional). Note that there can only be one price per product per currency. When prices is omitted altogether, a default price of 0 and a default currency based on the company's currency will be assigned.

unit
string

The unit in which this product is sold

tax
number
Default: 0

The tax percentage

selectable
boolean
Default: true

Whether this product is selected in deals or not

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

owner_id
integer

The ID of the user who will be marked as the owner of this product. When omitted, the authorized user ID will be used

name
string

The name of the product

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "prices": [
    ],
  • "unit": "string",
  • "tax": 0,
  • "selectable": true,
  • "active_flag": true,
  • "owner_id": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Delete a product

Marks a product as deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one product

Returns data about a specific product.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Update a product

Updates product data.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
code
string

The product code

prices
Array of objects

An array of objects, each containing: currency (string), price (number), cost (number, optional), overhead_cost (number, optional). Note that there can only be one price per product per currency. When prices is omitted altogether, a default price of 0 and a default currency based on the company's currency will be assigned.

unit
string

The unit in which this product is sold

tax
number
Default: 0

The tax percentage

selectable
boolean
Default: true

Whether this product is selected in deals or not

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

owner_id
integer

The ID of the user who will be marked as the owner of this product. When omitted, the authorized user ID will be used

name
string

The name of the product

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "prices": [
    ],
  • "unit": "string",
  • "tax": 0,
  • "selectable": true,
  • "active_flag": true,
  • "owner_id": 0,
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "related_objects": {
    }
}

Get deals where a product is attached to

Returns data about deals that have a product attached to it.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

status
string
Default: "all_not_deleted"
Enum: "open" "won" "lost" "deleted" "all_not_deleted"

Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included. The upper limit of found deals associated with the status is 2000.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Recents

Recent changes across all item types in Fintesk (deals, persons, etc).

Get recents Deprecated

Returns data about all recent changes occurred after the given timestamp.

Authorizations:
bearerAuth
query Parameters
since_timestamp
required
string

The timestamp in UTC. Format: YYYY-MM-DD HH:MM:SS.

items
string
Enum: "activity" "activityType" "deal" "filter" "note" "person" "organization" "pipeline" "product" "stage" "user"

Multiple selection of item types to include in the query (optional)

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Roles

Roles are a part of the Visibility groups’ feature that allow the admin user to categorize other users and dictate what items they will be allowed access to see.

Get all roles

Returns all the roles within the company.

Authorizations:
bearerAuth
query Parameters
limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Add a role

Adds a new role.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the role

parent_role_id
integer

The ID of the parent role

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent_role_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a role

Marks a role as deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one role

Returns the details of a specific role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "additional_data": {
    }
}

Update role details

Updates the parent role and/or the name of a specific role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
name
string

The name of the role

parent_role_id
integer

The ID of the parent role

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent_role_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a role assignment Deprecated

Removes the assigned user from a role and adds to the default role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
user_id
required
string

The ID of the user

Responses

Request samples

Content type
application/json
{
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List role assignments Deprecated

Returns all users assigned to a role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Add role assignment Deprecated

Assigns a user to a role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
user_id
required
string

The ID of the user

Responses

Request samples

Content type
application/json
{
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List role settings Deprecated

Returns the visibility settings of a specific role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Add or update role setting Deprecated

Adds or updates the visibility setting for a role.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
setting_key
required
string
Enum: "deal_default_visibility" "org_default_visibility" "person_default_visibility" "product_default_visibility"
value
required
integer
Enum: 1 3 5 7

Possible values for the default_visibility setting depending on the subscription plan:

Essential / Advanced plan
Value Description
1 Owner & Followers
3 Entire company

Professional / Enterprise plan
Value Description
`1` Owner only
`3` Owner's visibility group
`5` Owner's visibility group and sub-groups
`7` Entire company

Read more about visibility groups here.

Responses

Request samples

Content type
application/json
{
  • "setting_key": "deal_default_visibility",
  • "value": 1
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List pipeline visibility for a role Deprecated

Returns the list of either visible or hidden pipeline IDs for a specific role. For more information on pipeline visibility, please refer to the Visibility groups article.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
visible
boolean
Default: true

Whether to return the visible or hidden pipelines for the role

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update pipeline visibility for a role Deprecated

Updates the specified pipelines to be visible and/or hidden for a specific role. For more information on pipeline visibility, please refer to the Visibility groups article.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
visible_pipeline_ids
object

The pipeline IDs to make the pipelines visible (add) and/or hidden (remove) for the specified role. It requires the following JSON structure: { "add": "[1]", "remove": "[3,4]" }.

Responses

Request samples

Content type
application/json
{
  • "visible_pipeline_ids": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Stages

Stage is a logical component of a pipeline, and essentially a bucket that can hold a number of deals. In the context of the pipeline a stage belongs to, it has an order number which defines the order of stages in that pipeline.

Delete multiple stages in bulk

Marks multiple stages as deleted.

Authorizations:
bearerAuth
query Parameters
ids
required
string

The comma-separated IDs that will be deleted

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all stages

Returns data about all stages.

Authorizations:
bearerAuth
query Parameters
pipeline_id
integer

The ID of the pipeline to fetch stages for. If omitted, stages for all pipelines will be fetched.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Add a new stage

Adds a new stage, returns the ID upon success.

Authorizations:
bearerAuth
Request Body schema: application/json
pipeline_id
required
integer

The ID of the pipeline associated with the deal

deal_probability
integer

The success probability percentage of the deal. Used/shown when the deal weighted values are used.

name
required
string

The name of the stage

rotten_flag
boolean

Whether deals in this stage can become rotten

rotten_days
integer

The number of days the deals not updated in this stage would become rotten. Applies only if the rotten_flag is set.

Responses

Request samples

Content type
application/json
{
  • "pipeline_id": 0,
  • "deal_probability": 0,
  • "name": "string",
  • "rotten_flag": true,
  • "rotten_days": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a stage

Marks a stage as deleted.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one stage

Returns data about a specific stage.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
everyone
number (stageNumberBoolean)
Enum: 0 1

If everyone=1 is provided, deals summary will return deals owned by every user

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update stage details

Updates the properties of a stage.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
pipeline_id
integer

The ID of the pipeline associated with the deal

deal_probability
integer

The success probability percentage of the deal. Used/shown when the deal weighted values are used.

name
string

The name of the stage

rotten_flag
boolean

Whether deals in this stage can become rotten

rotten_days
integer

The number of days the deals not updated in this stage would become rotten. Applies only if the rotten_flag is set.

order_nbr
integer

An order number for this stage. Order numbers should be used to order the stages in the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipeline_id": 0,
  • "deal_probability": 0,
  • "name": "string",
  • "rotten_flag": true,
  • "rotten_days": 0,
  • "order_nbr": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get deals in a stage Deprecated

Lists deals in a specific stage.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
filter_id
integer

The ID of the filter to use (will narrow down results if used together with user_id parameter)

user_id
integer

If supplied, filter_id will not be considered and only deals owned by the given user will be returned. If omitted, deals owned by the authorized user will be returned.

everyone
number (numberBoolean)
Enum: 0 1

If supplied, filter_id and user_id will not be considered – instead, deals owned by everyone will be returned

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}

Users

Users are people with access to your Fintesk account. A user may belong to one or many Fintesk accounts, so deleting a user from one Fintesk account will not remove the user from the data store if he/she is connected to multiple accounts. Users should not be confused with persons.

Get all users

Returns data about all users within the company.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Add a new user

Adds a new user to the company, returns the ID upon success.

Authorizations:
bearerAuth
Request Body schema: application/json
Array of objects
email
required
string

The user email

active_flag
boolean

Whether the entity is active or not. false = Not activated, true = Activated

Responses

Request samples

Content type
application/json
{
  • "access": [
    ],
  • "email": "string",
  • "active_flag": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Find users by name

Finds users by their name.

Authorizations:
bearerAuth
query Parameters
term
required
string

The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded.

search_by_email
number (numberBooleanDefault0)
Default: 0
Enum: 0 1

When enabled, the term will only be matched against email addresses of users. Default: false.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Get current user data

Returns data about an authorized user within the company with bound company data: company ID, company name, and domain. Note that the locale property means 'Date/number format' in the Pipedrive account settings, not the chosen language.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one user

Returns data about a specific user within the company.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update user details

Updates the properties of a user. Currently, only active_flag can be updated.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
active_flag
required
boolean

Whether the entity is active or not. false = Not activated, true = Activated

created_by_user_id
integer

The ID of the user who created the item.

add_time
string <date-time>

The creation time in UTC. Format: YYYY-MM-DD HH:MM:SS

update_time
string <date-time>

The last update time in UTC. Format: YYYY-MM-DD HH:MM:SS

last_updated_by_user_id
integer

The ID of the user who created or most recently updated the item.

Responses

Request samples

Content type
application/json
{
  • "active_flag": true,
  • "created_by_user_id": 0,
  • "add_time": "2019-08-24T14:15:22Z",
  • "update_time": "2019-08-24T14:15:22Z",
  • "last_updated_by_user_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Oauth

Requesting authorization Deprecated

Authorize a user by redirecting them to the Pipedrive OAuth authorization page and request their permissions to act on their behalf. This step is necessary to implement only when you allow app installation outside of the Marketplace.

query Parameters
client_id
required
string

The client ID provided to you by the Pipedrive Marketplace when you register your app

redirect_uri
required
string

The callback URL you provided when you registered your app. Authorization code will be sent to that URL (if it matches with the value you entered in the registration form) if a user approves the app install. Or, if a customer declines, the corresponding error will also be sent to this URL.

state
string

You may pass any random string as the state parameter and the same string will be returned to your app after a user authorizes access. It may be used to store the user's session ID from your app or distinguish different responses. Using state may increase security; see RFC-6749.

Responses

Response samples

Content type
text/html
As a result of the request, the customer will see a page with the confirmation dialog, which will present the details of your app (title, company name, icon) and explain the permission scopes that you have set for the app. Customers should confirm their wish to install the app by clicking "Allow and install" or deny authorization by clicking "Cancel".

Getting the tokens Deprecated

After the customer has confirmed the app installation, you will need to exchange the authorization_code to a pair of access and refresh tokens. Using an access token, you can access the user's data through the API.

Authorizations:
None
header Parameters
Authorization
required
string

Base 64 encoded string containing the client_id and client_secret values. The header value should be Basic <base64(client_id:client_secret)>.

Request Body schema: application/x-www-form-urlencoded
grant_type
string
Default: "authorization_code"
Enum: "authorization_code" "refresh_token"

Since you are trying to exchange an authorization code for a pair of tokens, you must use the value "authorization_code"

code
string

The authorization code that you received after the user confirmed app installation

redirect_uri
string

The callback URL you provided when you registered your app

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "scope": "string",
  • "expires_in": 0,
  • "api_domain": "string"
}

Refreshing the tokens Deprecated

The access_token has a lifetime. After a period of time, which was returned to you in expires_in JSON property, the access_token will be invalid, and you can no longer use it to get data from our API. To refresh the access_token, you must use the refresh_token.

Authorizations:
None
header Parameters
Authorization
required
string

Base 64 encoded string containing the client_id and client_secret values. The header value should be Basic <base64(client_id:client_secret)>.

Request Body schema: application/x-www-form-urlencoded
grant_type
string
Default: "refresh_token"
Enum: "authorization_code" "refresh_token"

Since you are to refresh your access_token, you must use the value "refresh_token"

refresh_token
string

The refresh token that you received after you exchanged the authorization code

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "scope": "string",
  • "expires_in": 0,
  • "api_domain": "string"
}

Notes

Get all notes Deprecated

Returns all notes.

Authorizations:
bearerAuth
query Parameters
user_id
integer

The ID of the user whose notes to fetch. If omitted, notes by all users will be returned.

deal_id
integer

The ID of the deal which notes to fetch. If omitted, notes about all deals will be returned.

person_id
integer

The ID of the person whose notes to fetch. If omitted, notes about all persons will be returned.

org_id
integer

The ID of the organization which notes to fetch. If omitted, notes about all organizations will be returned.

limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

sort
string

The field names and sorting mode separated by a comma (field_name_1 ASC, field_name_2 DESC). Only first-level field keys are supported (no nested keys). Supported fields: id, user_id, deal_id, person_id, org_id, content, add_time, update_time.

start_date
string <date>

The date in format of YYYY-MM-DD from which notes to fetch

end_date
string <date>

The date in format of YYYY-MM-DD until which notes to fetch to

pinned_to_deal_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to deal pinning state

pinned_to_organization_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to organization pinning state

pinned_to_person_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to person pinning state

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    },
  • "related_objects": {
    }
}

Add a note Deprecated

Adds a new note.

Authorizations:
bearerAuth
Request Body schema: application/json
content
string

The content of the note in HTML format. Subject to sanitization on the back-end.

deal_id
integer

The ID of the deal the note will be attached to. This property is required unless one of (person_id/org_id) is specified.

person_id
integer

The ID of the person the note will be attached to. This property is required unless one of (deal_id/org_id) is specified.

org_id
integer

The ID of the organization the note will be attached to. This property is required unless one of (deal_id/person_id) is specified.

add_time
string

The optional creation date & time of the Item in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

pinned_to_deal_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to deal pinning state (deal_id is also required)

pinned_to_organization_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to organization pinning state (org_id is also required)

pinned_to_person_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to person pinning state (person_id is also required)

user_id
integer

The ID of the user who will be marked as the author of the note. Only an admin can change the author.

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "deal_id": 0,
  • "person_id": 0,
  • "org_id": 0,
  • "add_time": "string",
  • "pinned_to_deal_flag": 0,
  • "pinned_to_organization_flag": 0,
  • "pinned_to_person_flag": 0,
  • "user_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a note Deprecated

Deletes a specific note.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": true
}

Get one note Deprecated

Returns details about a specific note.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a note Deprecated

Updates a note.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
content
string

The content of the note in HTML format. Subject to sanitization on the back-end.

deal_id
integer

The ID of the deal the note will be attached to. This property is required unless one of (person_id/org_id) is specified.

person_id
integer

The ID of the person the note will be attached to. This property is required unless one of (deal_id/org_id) is specified.

org_id
integer

The ID of the organization the note will be attached to. This property is required unless one of (deal_id/person_id) is specified.

add_time
string

The optional creation date & time of the Item in UTC. Can be set in the past or in the future. Requires admin user API token. Format: YYYY-MM-DD HH:MM:SS

pinned_to_deal_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to deal pinning state (deal_id is also required)

pinned_to_organization_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to organization pinning state (org_id is also required)

pinned_to_person_flag
number (numberBoolean)
Enum: 0 1

If set, the results are filtered by note to person pinning state (person_id is also required)

user_id
integer

The ID of the user who will be marked as the author of the note. Only an admin can change the author.

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "deal_id": 0,
  • "person_id": 0,
  • "org_id": 0,
  • "add_time": "string",
  • "pinned_to_deal_flag": 0,
  • "pinned_to_organization_flag": 0,
  • "pinned_to_person_flag": 0,
  • "user_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get all comments for a note Deprecated

Returns all comments associated with a note.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

query Parameters
limit
integer <int32> >= 1
Default: 100
Example: limit=100

Limits the number of returned results. If not provided, 100 items will be returned.

start
integer
Default: 0

For pagination, the position that represents the first result for the page.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "related_objects": {
    },
  • "additional_data": {
    }
}

Add a comment to a note Deprecated

Adds a new comment to a note.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

Request Body schema: application/json
content
required
string

The content of the note in HTML format. Subject to sanitization on the back-end.

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get one comment Deprecated

Returns the details of a comment.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

commentId
required
string <uuid>

The ID of the comment

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Update a comment related to a note Deprecated

Updates a comment related to a note.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

commentId
required
string <uuid>

The ID of the comment

Request Body schema: application/json
content
required
string

The content of the note in HTML format. Subject to sanitization on the back-end.

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Delete a comment related to a note Deprecated

Deletes a comment.

Authorizations:
bearerAuth
path Parameters
id
required
integer

The ID of the Entity we want to retrieve.

commentId
required
string <uuid>

The ID of the comment

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": true
}

NoteFields

Get all note fields Deprecated

Returns data about all note fields.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "additional_data": {
    }
}