Skip to content
Docs
CRM & sales

Pipedrive

Let hires find and read deals, people and organisations in Pipedrive, move deals through your pipelines, add notes and activities, and be woken when deals change.

Explore 15 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Pipedrive connected, a hire can:

  • find deals by words, status, pipeline, stage or owner, and read one with the person and organisation it's with, its activities and its latest notes,
  • find people and organisations, and read them with their deals and notes,
  • see your pipelines with their stages, and the people on your Pipedrive account,
  • create deals in a stage, change a deal (value, owner, close date, won or lost, custom fields) and move it to another stage,
  • add people and organisations, add notes, and plan activities (calls, meetings, tasks) for your team.

Activities a hire plans are linked to the deal's person but never invite or email anyone. To set up a meeting with a customer, a hire uses your calendar, which asks you first.

1. Copy your API token

Hires act as the Pipedrive user whose token Roster has: what they create shows as that user's, and they can see what that user can see.

  1. Sign in to Pipedrive as that user, with the company you want selected.
  2. Open Personal preferences → API and copy the token. Each company you belong to has its own token.

If you'd rather Pipedrive showed Roster by name, you can use your own OAuth app instead: make an app in Pipedrive's Developer Hub, give it the deals, contacts and activities scopes (full access), users (read) and search (read), and put the callback address Roster shows on the connection as its callback URL.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Pipedrive and choose it.
  2. How Roster signs in: A user's API token (paste it), or Your own Pipedrive OAuth app (paste its client ID and secret, then Connect).
  3. Company address: the part before .pipedrive.com in your Pipedrive address, like bayt.
  4. Click Connect. Roster checks the token and shows which company and user it belongs to.

3. Give hires access

On the hire's Tools tab, click Give access on Pipedrive:

  • Read only: it can find and read deals, people and organisations, and see pipelines and users. It can't change anything.
  • Read and write: it can also create and change deals, move them, add people, organisations, notes and activities.
  • Pipelines: pipeline names or IDs whose deals it may see and work on. Leave it empty for every pipeline. A deal in any other pipeline is refused, even if the hire knows its ID, and it can't move a deal into a pipeline outside the list.
  • Deal fields it may change: title, value, currency, status, lost_reason, expected_close_date, probability, owner, stage, person, organization, or a custom field's key. Leave it empty to let it change any field. Moving a deal counts as changing stage.

People and organisations aren't divided by pipeline in Pipedrive, so a hire with access sees the ones your user can see. Their emails and phone numbers are shown, since a hire working your deals needs them.

Watching deals

A hire's responsibility can watch Pipedrive: it's woken when a deal in its pipelines or a person is created or changes, with the list. Checking costs nothing when nothing changed.

If something goes wrong

  • "Unauthorized": the token was changed in Pipedrive, or it belongs to another company. Copy the token again with the right company selected.
  • A deal is refused: it's in a pipeline outside the hire's list. Add the pipeline on the hire's Tools tab, or ask someone who can see it.
  • "No stage called…": stage names come from your pipelines; a hire can list them.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Pipedrive and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Pipedrive: your name (top right) → Personal preferences → API. Hires act as that user.

For: How Roster signs in: A user's API token.

OAuth 2.0

From your app in Pipedrive's Developer Hub: its client ID and secret.

For: How Roster signs in: Your own Pipedrive OAuth app.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Pipedrive connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		A token is quickest. An OAuth app of yours lets Pipedrive show Roster by name.

Choices: A user's API token (token); Your own Pipedrive OAuth app (oauth).

Starts with: token.

API token
token
Required · sealed secret		In Pipedrive: your name (top right) → Personal preferences → API. Hires act as that user.

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From your app in Pipedrive's Developer Hub: its client ID and secret.

Shown when signIn: oauth.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

Company address
company
Required		The part before .pipedrive.com in your Pipedrive address.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Pipedrive per-hire limits
FieldWhat to provide
Pipelines
pipelines
Optional		Pipeline names or IDs whose deals it may see and work on. Leave empty for every pipeline.
Deal fields it may change
fields
Optional		title, value, currency, status, lost_reason, expected_close_date, probability, owner, stage, person, organization, or a custom field's key. Leave empty to let it change any field.

Actions

15 actions: 8 only read and 7 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

15 of 15 actions. Open an action for its arguments and full input schema.

search_dealsRead only

Find deals, most recently updated first: by words in the title or notes, status, stage or pipeline, or owner. Only pipelines this hire may use.

Approval: Uses your workspace and hire approval settings.

Arguments for search_deals
ArgumentTypeDetails
wordsOptionalstringSee input schema below.
statusOptional"open" | "won" | "lost"See input schema below.
pipelineOptionalstringa pipeline's name
stageOptionalstringa stage's name
ownerOptionalstringthe owner's email or name
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "words": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "won",
        "lost"
      ]
    },
    "pipeline": {
      "description": "a pipeline's name",
      "type": "string"
    },
    "stage": {
      "description": "a stage's name",
      "type": "string"
    },
    "owner": {
      "description": "the owner's email or name",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}
read_dealRead only

Read a deal: value, pipeline and stage, owner, the person and organisation it's with, its latest notes and its activities.

Approval: Uses your workspace and hire approval settings.

Arguments for read_deal
ArgumentTypeDetails
idRequiredintegerthe deal's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the deal's ID"
    }
  },
  "required": [
    "id"
  ]
}
search_peopleRead only

Find people (contacts) by name, email or phone, with their organisation.

Approval: Uses your workspace and hire approval settings.

Arguments for search_people
ArgumentTypeDetails
wordsRequiredstringSee input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "words": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "words"
  ]
}
search_organizationsRead only

Find organisations (companies) by name or address.

Approval: Uses your workspace and hire approval settings.

Arguments for search_organizations
ArgumentTypeDetails
wordsRequiredstringSee input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "words": {
      "type": "string",
      "minLength": 2,
      "maxLength": 200
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "words"
  ]
}
read_personRead only

Read a person: contact details, organisation, their deals in this hire's pipelines and latest notes.

Approval: Uses your workspace and hire approval settings.

Arguments for read_person
ArgumentTypeDetails
idRequiredintegerthe person's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the person's ID"
    }
  },
  "required": [
    "id"
  ]
}
read_organizationRead only

Read an organisation: address, website, its deals in this hire's pipelines and latest notes.

Approval: Uses your workspace and hire approval settings.

Arguments for read_organization
ArgumentTypeDetails
idRequiredintegerthe organisation's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the organisation's ID"
    }
  },
  "required": [
    "id"
  ]
}
list_pipelinesRead only

The pipelines this hire may use, each with its stages in order.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_usersRead only

The people on the Pipedrive account, who can own deals and activities.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
create_dealRead and write

Create a deal in a stage (by name), optionally with its value, the person and organisation it's with, an owner and an expected close date.

Approval: Uses your workspace and hire approval settings.

Arguments for create_deal
ArgumentTypeDetails
titleRequiredstringSee input schema below.
stageRequiredstringthe stage's name
pipelineOptionalstringthe pipeline's name, when stage names repeat
valueOptionalnumberSee input schema below.
currencyOptionalstringSee input schema below.
personOptionalintegerthe person's ID
organizationOptionalintegerthe organisation's ID
ownerOptionalstringthe owner's email or name; default the connection's user
expected_close_dateOptionalstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "stage": {
      "type": "string",
      "description": "the stage's name"
    },
    "pipeline": {
      "description": "the pipeline's name, when stage names repeat",
      "type": "string"
    },
    "value": {
      "type": "number",
      "minimum": 0
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "person": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the person's ID"
    },
    "organization": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the organisation's ID"
    },
    "owner": {
      "description": "the owner's email or name; default the connection's user",
      "type": "string"
    },
    "expected_close_date": {
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    }
  },
  "required": [
    "title",
    "stage"
  ]
}
update_dealRead and write

Change a deal: its title, value, owner, expected close date, probability, status (won or lost, with the reason) or custom fields by key. To move it to another stage use move_deal.

Approval: Uses your workspace and hire approval settings.

Arguments for update_deal
ArgumentTypeDetails
idRequiredintegerthe deal's ID
titleOptionalstringSee input schema below.
valueOptionalnumberSee input schema below.
currencyOptionalstringSee input schema below.
ownerOptionalstringthe new owner's email or name
statusOptional"open" | "won" | "lost"See input schema below.
lost_reasonOptionalstringSee input schema below.
expected_close_dateOptionalstringSee input schema below.
probabilityOptionalnumberSee input schema below.
personOptionalintegerthe person's ID
organizationOptionalintegerthe organisation's ID
custom_fieldsOptionalobjectcustom fields by their key, e.g. { "a1b2…": "Gold" }
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the deal's ID"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "value": {
      "type": "number",
      "minimum": 0
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "owner": {
      "description": "the new owner's email or name",
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "won",
        "lost"
      ]
    },
    "lost_reason": {
      "type": "string",
      "maxLength": 255
    },
    "expected_close_date": {
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "probability": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "person": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the person's ID"
    },
    "organization": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the organisation's ID"
    },
    "custom_fields": {
      "description": "custom fields by their key, e.g. { \"a1b2…\": \"Gold\" }",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z0-9_]{1,64}$"
      },
      "additionalProperties": {
        "type": [
          "string",
          "number",
          "null"
        ]
      }
    }
  },
  "required": [
    "id"
  ]
}
move_dealRead and write

Move a deal to another stage, by the stage's name (in its pipeline, or another pipeline this hire may use).

Approval: Uses your workspace and hire approval settings.

Arguments for move_deal
ArgumentTypeDetails
idRequiredintegerthe deal's ID
stageRequiredstringthe stage's name
pipelineOptionalstringanother pipeline's name, to move it there
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the deal's ID"
    },
    "stage": {
      "type": "string",
      "description": "the stage's name"
    },
    "pipeline": {
      "description": "another pipeline's name, to move it there",
      "type": "string"
    }
  },
  "required": [
    "id",
    "stage"
  ]
}
create_personRead and write

Add a person (contact), optionally with their email, phone, job title and organisation.

Approval: Uses your workspace and hire approval settings.

Arguments for create_person
ArgumentTypeDetails
nameRequiredstringSee input schema below.
emailOptionalstringSee input schema below.
phoneOptionalstringSee input schema below.
job_titleOptionalstringSee input schema below.
organizationOptionalintegerthe organisation's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "phone": {
      "type": "string",
      "maxLength": 50
    },
    "job_title": {
      "type": "string",
      "maxLength": 255
    },
    "organization": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the organisation's ID"
    }
  },
  "required": [
    "name"
  ]
}
create_organizationRead and write

Add an organisation (company), optionally with its website and address.

Approval: Uses your workspace and hire approval settings.

Arguments for create_organization
ArgumentTypeDetails
nameRequiredstringSee input schema below.
websiteOptionalstringSee input schema below.
addressOptionalstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "website": {
      "type": "string",
      "format": "uri"
    },
    "address": {
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "name"
  ]
}
add_noteRead and write

Add a note to a deal, a person or an organisation (give one). Notes are for the team only.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
textRequiredstringSee input schema below.
dealOptionalintegerthe deal's ID
personOptionalintegerthe person's ID
organizationOptionalintegerthe organisation's ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    },
    "deal": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the deal's ID"
    },
    "person": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the person's ID"
    },
    "organization": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the organisation's ID"
    }
  },
  "required": [
    "text"
  ]
}
add_activityRead and write

Plan an activity for the team (a call, meeting, task, deadline, email or lunch) on a deal, person or organisation, optionally done already. Nobody outside the team is invited or emailed.

Approval: Uses your workspace and hire approval settings.

Arguments for add_activity
ArgumentTypeDetails
subjectRequiredstringSee input schema below.
typeOptionalstringSee input schema below.Default: "task"
due_dateOptionalstringSee input schema below.
due_timeOptionalstringSee input schema below.
durationOptionalstringSee input schema below.
dealOptionalintegerthe deal's ID
personOptionalintegerthe person it's with (linked, not invited)
organizationOptionalintegerthe organisation's ID
ownerOptionalstringwhose it is, by email or name; default the connection's user
noteOptionalstringSee input schema below.
doneOptionalbooleanSee input schema below.Default: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "type": {
      "default": "task",
      "type": "string",
      "pattern": "^[a-z0-9_]{1,40}$"
    },
    "due_date": {
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "due_time": {
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "duration": {
      "type": "string",
      "pattern": "^\\d{2}:\\d{2}$"
    },
    "deal": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the deal's ID"
    },
    "person": {
      "description": "the person it's with (linked, not invited)",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "organization": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the organisation's ID"
    },
    "owner": {
      "description": "whose it is, by email or name; default the connection's user",
      "type": "string"
    },
    "note": {
      "type": "string",
      "maxLength": 10000
    },
    "done": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "subject"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

HubSpot

Let hires find and update contacts, companies and deals in HubSpot, move deals through your pipeline, add notes and tasks, and be woken when deals or contacts change.

Salesforce

Leads, accounts, opportunities and cases in Salesforce.

On this page

1. Copy your API token2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference