Skip to content
Docs
CRM & sales

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.

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

With HubSpot connected, a hire can:

  • search contacts, companies and deals by name, email, domain or deal name, by deal stage, by owner, or by what changed since a time,
  • read a record with what it's linked to (a deal's contact and company) and its latest notes and tasks,
  • see your deal pipelines and their stages,
  • create contacts, companies and deals, change their details or owner, and move a deal to another stage by the stage's name,
  • add a note to a record's timeline, or a task with a due date for someone on your team.

1. Make an app for Roster in HubSpot

Roster signs in as an app you make in your HubSpot account. Either:

  • A private app, if your account already has one for Roster: Settings → Integrations → Private apps. HubSpot no longer lets you make new private apps, but existing ones keep working.
  • An app with static auth on HubSpot's developer platform, for a new one. Its access token is on the app's Auth tab, under Development → Projects. Once you've typed your Account ID in Roster, the form links straight to your projects.

Give the app these scopes: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.companies.write, crm.objects.deals.read, crm.objects.deals.write and crm.objects.owners.read. For hires that only read, the .write scopes can be left out. Then copy the app's access token (it starts with pat-).

Prefer OAuth? Make an app with OAuth instead, with the same scopes, and add the callback address Roster shows on the connection as its redirect URL.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for HubSpot and choose it.
  2. How Roster signs in: An app's access token, then paste the token. (Or Your own HubSpot OAuth app: paste its client ID and secret, then Connect.)
  3. Account ID (optional): your HubSpot account's ID, shown under your account name. With it, hires include links to the records they mention.
  4. Click Connect. With a token, Roster checks it with HubSpot first, and the connection shows Connected as your HubSpot account's ID. If HubSpot refuses the token (it should start with pat-), Roster says so and saves nothing.

What hires change shows in HubSpot as changed by the app.

3. Give hires access

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

  • Read only: it can search and read records, pipelines and owners, and nothing else.
  • Read and write: it can also create and change records, move deals, and add notes and tasks.
  • Deal pipelines: the pipelines whose deals it may see and work on, by name (Sales Pipeline) or ID. Leave it empty for every pipeline. A deal in any other pipeline is refused, even if the hire knows its ID.
  • Properties it may change: internal property names like dealstage, amount or lifecyclestage. Leave it empty to let it change any property.

Watching deals and contacts

A hire's responsibility can watch HubSpot: it's woken when a deal in its pipelines or a contact is added or changed, with the list. Checking costs nothing when nothing changed.

If something goes wrong

  • "Didn't accept the connection's credential": the token was rotated or the app removed. Paste the new token on the connection.
  • "Doesn't allow this": the app is missing a scope, often a .write one when a hire tried to change something.
  • "No stage called…": the hire is told your stages, and tries again with the right name.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect HubSpot 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

The app's access token (starts with pat-). HubSpot shows it on the app's Auth tab.

For: How Roster signs in: An app's access token.

OAuth 2.0

From your HubSpot app's Auth tab.

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

Requested scopes:

  • oauth
  • crm.objects.contacts.read
  • crm.objects.contacts.write
  • crm.objects.companies.read
  • crm.objects.companies.write
  • crm.objects.deals.read
  • crm.objects.deals.write
  • crm.objects.owners.read

When making a key, use these permissions from the connection guide:

  • crm.objects.contacts.read
  • crm.objects.contacts.write
  • crm.objects.companies.read
  • crm.objects.companies.write
  • crm.objects.deals.read
  • crm.objects.deals.write
  • crm.objects.owners.read

Connection fields

HubSpot connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		Use the value for your account or connection.

Choices: An app's access token (token); Your own HubSpot OAuth app (oauth).

Starts with: token.

Access token
token
Required · sealed secret		The app's access token (starts with pat-). HubSpot shows it on the app's Auth tab.

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From your HubSpot app's Auth tab.

Shown when signIn: oauth.

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

Shown when signIn: oauth.

Account ID
accountId
Optional		Optional, for links to records: shown in HubSpot under your account name (the Hub ID).

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.

HubSpot per-hire limits
FieldWhat to provide
Deal pipelines
pipelines
Optional		Pipeline names or IDs whose deals it may see and work on. Leave empty for every pipeline.
Properties it may change
properties
Optional		Internal property names, like dealstage or lifecyclestage. Leave empty to let it change any property.

Actions

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

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

searchRead only

Search HubSpot contacts, companies or deals by words (name, email, domain, deal name), optionally by deal stage, owner, or changed since a time. Newest changes first.

Approval: Uses your workspace and hire approval settings.

Arguments for search
ArgumentTypeDetails
typeRequired"contacts" | "companies" | "deals"contacts, companies or deals
queryOptionalstringwords to look for; leave out to list the latest
stageOptionalstringdeals only: a stage name, like Contract sent
pipelineOptionalstringdeals only: the pipeline the stage is in, when it's in several
ownerOptionalstringthe owner's email or name
changedSinceOptionalstringISO time: only records changed after it
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "contacts",
        "companies",
        "deals"
      ],
      "description": "contacts, companies or deals"
    },
    "query": {
      "description": "words to look for; leave out to list the latest",
      "type": "string",
      "maxLength": 3000
    },
    "stage": {
      "description": "deals only: a stage name, like Contract sent",
      "type": "string"
    },
    "pipeline": {
      "description": "deals only: the pipeline the stage is in, when it's in several",
      "type": "string"
    },
    "owner": {
      "description": "the owner's email or name",
      "type": "string"
    },
    "changedSince": {
      "description": "ISO time: only records changed after it",
      "type": "string",
      "format": "date-time",
      "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "type"
  ]
}
readRead only

Read one contact, company or deal: its details, what it's linked to, and its latest notes and tasks.

Approval: Uses your workspace and hire approval settings.

Arguments for read
ArgumentTypeDetails
typeRequired"contacts" | "companies" | "deals"contacts, companies or deals
idRequiredstringthe record's HubSpot ID
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "contacts",
        "companies",
        "deals"
      ],
      "description": "contacts, companies or deals"
    },
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the record's HubSpot ID"
    }
  },
  "required": [
    "type",
    "id"
  ]
}
list_pipelinesRead only

The deal pipelines this hire may use, with their 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_ownersRead only

The HubSpot users records can be assigned to, with their emails.

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": {}
}
createRead and write

Create a contact, company or deal. Deals need a stage (and the pipeline when the stage name is in several). Optionally link it to existing records.

Approval: Uses your workspace and hire approval settings.

Arguments for create
ArgumentTypeDetails
typeRequired"contacts" | "companies" | "deals"contacts, companies or deals
propertiesOptionalobjectHubSpot properties by internal name, like { lifecyclestage: 'customer' } or { amount: '12500' }Default: {}
stageOptionalstringdeals: the stage to start in
pipelineOptionalstringdeals: the pipeline, when the stage is in several
ownerOptionalstringthe owner's email or name
linkToOptionalobject[]existing records to link it to: a deal to its contact and company, a contact to its companyDefault: []
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "contacts",
        "companies",
        "deals"
      ],
      "description": "contacts, companies or deals"
    },
    "properties": {
      "default": {},
      "description": "HubSpot properties by internal name, like { lifecyclestage: 'customer' } or { amount: '12500' }",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "stage": {
      "description": "deals: the stage to start in",
      "type": "string"
    },
    "pipeline": {
      "description": "deals: the pipeline, when the stage is in several",
      "type": "string"
    },
    "owner": {
      "description": "the owner's email or name",
      "type": "string"
    },
    "linkTo": {
      "default": [],
      "description": "existing records to link it to: a deal to its contact and company, a contact to its company",
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "contacts",
              "companies",
              "deals"
            ],
            "description": "contacts, companies or deals"
          },
          "id": {
            "type": "string",
            "pattern": "^\\d{1,20}$",
            "description": "the record's HubSpot ID"
          }
        },
        "required": [
          "type",
          "id"
        ]
      }
    }
  },
  "required": [
    "type"
  ]
}
updateRead and write

Change properties of a contact, company or deal, or its owner. Use move_deal to change a deal's stage.

Approval: Uses your workspace and hire approval settings.

Arguments for update
ArgumentTypeDetails
typeRequired"contacts" | "companies" | "deals"contacts, companies or deals
idRequiredstringthe record's HubSpot ID
propertiesOptionalobjectHubSpot properties by internal name, like { lifecyclestage: 'customer' } or { amount: '12500' }Default: {}
ownerOptionalstringa new owner's email or name
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "contacts",
        "companies",
        "deals"
      ],
      "description": "contacts, companies or deals"
    },
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the record's HubSpot ID"
    },
    "properties": {
      "default": {},
      "description": "HubSpot properties by internal name, like { lifecyclestage: 'customer' } or { amount: '12500' }",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "owner": {
      "description": "a new owner's email or name",
      "type": "string"
    }
  },
  "required": [
    "type",
    "id"
  ]
}
move_dealRead and write

Move a deal to another stage, by the stage's name, within the pipelines this hire may use.

Approval: Uses your workspace and hire approval settings.

Arguments for move_deal
ArgumentTypeDetails
idRequiredstringthe record's HubSpot ID
stageRequiredstringthe stage's name, like Closed won
pipelineOptionalstringonly to move it to another pipeline
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the record's HubSpot ID"
    },
    "stage": {
      "type": "string",
      "minLength": 1,
      "description": "the stage's name, like Closed won"
    },
    "pipeline": {
      "description": "only to move it to another pipeline",
      "type": "string"
    }
  },
  "required": [
    "id",
    "stage"
  ]
}
add_noteRead and write

Add a note to a contact, company or deal's timeline.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
typeRequired"contacts" | "companies" | "deals"contacts, companies or deals
idRequiredstringthe record's HubSpot ID
textRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "contacts",
        "companies",
        "deals"
      ],
      "description": "contacts, companies or deals"
    },
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the record's HubSpot ID"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "type",
    "id",
    "text"
  ]
}
add_taskRead and write

Add a to-do task on a contact, company or deal, with a due date and optionally an owner.

Approval: Uses your workspace and hire approval settings.

Arguments for add_task
ArgumentTypeDetails
typeRequired"contacts" | "companies" | "deals"contacts, companies or deals
idRequiredstringthe record's HubSpot ID
subjectRequiredstringSee input schema below.
bodyOptionalstringSee input schema below.
dueRequiredstring | stringwhen it's due, ISO date or time
priorityOptional"low" | "medium" | "high"See input schema below.Default: "medium"
ownerOptionalstringwho should do it: their email or name
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "contacts",
        "companies",
        "deals"
      ],
      "description": "contacts, companies or deals"
    },
    "id": {
      "type": "string",
      "pattern": "^\\d{1,20}$",
      "description": "the record's HubSpot ID"
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "body": {
      "type": "string",
      "maxLength": 10000
    },
    "due": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "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])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        {
          "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])))$"
        }
      ],
      "description": "when it's due, ISO date or time"
    },
    "priority": {
      "default": "medium",
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ]
    },
    "owner": {
      "description": "who should do it: their email or name",
      "type": "string"
    }
  },
  "required": [
    "type",
    "id",
    "subject",
    "due"
  ]
}

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

folk

A light CRM for contacts, companies and deals.

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.

On this page

1. Make an app for Roster in HubSpot2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference