Connect HubSpot
You need a HubSpot super admin (or a user with Developer tools access). It takes about five minutes.
The scopes
Whichever way you connect, the key or app needs exactly these nine scopes:
crm.objects.deals.read, crm.objects.deals.write, crm.objects.companies.read, crm.objects.companies.write,
crm.objects.contacts.read, crm.objects.contacts.write, crm.schemas.deals.write, crm.objects.owners.read,
settings.currencies.read.
The deal, company and contact scopes read and write records, their associations and the deal pipeline;
crm.schemas.deals.write lets activation create CoSell's deal properties; crm.objects.owners.read matches deal
owners to your users by email; settings.currencies.read reads the company currency and exchange rates. CoSell also
adds notes to deals. HubSpot's scope reference names no separate scope for notes; if a note is ever refused, the
error names the scope to add.
Service key (recommended)
- In HubSpot, Development → Keys → Service keys → Create service key. Name it CoSell.
- Add new scope for each scope above, then create the key and copy it (it starts with
pat-). - In CoSell, Settings → CRM → HubSpot → Service key or private app, paste the key as the access token and press Connect HubSpot.
The key lives until you rotate or delete it in HubSpot; after a rotation, paste the new key in CoSell. CoSell stores it encrypted and never shows it again. A service key cannot receive HubSpot's app webhooks: use a workflow (below) to tell CoSell about a change at once.
Already have a private app? HubSpot stopped creating new (legacy) private apps on 26 October 2026, and existing ones keep working. Its token is under Development → Legacy apps → your app → Auth → Show token; give the app the scopes above and paste the token the same way.
Public app
If you run your own app with OAuth, give it the same scopes and the redirect URL shown in CoSell, then choose Public app in CoSell and paste the client ID and secret. HubSpot asks you to approve the app and sends you straight back. CoSell keeps the refresh token and renews the 30-minute access tokens itself.
What activation does
- Creates the read-back deal properties (lower-case, as HubSpot names them) in the deal information group:
ace_opportunity_id,ace_partner_central_url,ace_review_status,ace_review_comments,ace_stage,ace_origin,ace_aws_seller,ace_engagement_score,ace_involvement_type,ace_sync_status,ace_last_synced_at,ace_sync_error,ace_expected_spend,ace_marketplace_offers, and the ace_co_sell checkbox that marks a deal for AWS. If the key lackscrm.schemas.deals.write, activation lists the properties it could not create; add the scope and press Re-activate. - Reads the portal's company currency and, where you use several currencies, their exchange rates; and its owners.
Stages, objects and the AWS inputs
- CoSell reads your default deal pipeline. Its stage labels are what you map to ACE stages under Settings → Mapping → Stages, and the submission gate is one of them. A deal CoSell creates lands in that pipeline.
- Deals, companies and contacts are HubSpot's; the company and contact on a deal are its associations.
- A lead in CoSell's sense is a contact at lifecycle stage Lead. HubSpot's separate Leads object needs Sales Hub Professional or Enterprise and hangs each lead off an existing contact, so CoSell does not use it. Converting a lead makes (or joins) the company, makes the deal, associates them, and moves the contact to Opportunity. HubSpot only moves a lifecycle stage forward, so a contact already at Opportunity, Customer or Evangelist counts as converted.
- Dropdowns hold HubSpot's internal values. A company's Industry, a deal's Deal type and a contact's Lead
status accept only their own options, and records carry the option's internal value (
RETAIL,newbusiness), which is what you see under Mapping. When CoSell writes one, it matches the text to an option's label or value; text with no matching option is left out rather than failing the whole record. Add the option in HubSpot if you want it kept. - The default mapping reads the AWS inputs from deal properties named
aws_use_case,aws_delivery_model,aws_primary_needs,aws_sales_activities,customer_aws_account_idandcompetitor. Create the ones sellers fill, or map your own properties under Mapping.
How changes reach CoSell
Every few minutes CoSell reads the deals changed since its last look (a change can take a few moments to appear in HubSpot's search). To hear about a change at once:
- A workflow (Data Hub Professional or Enterprise). Add a deal-based workflow with the action Send a webhook:
method POST, the webhook URL shown in CoSell, authentication type API key with the key name
x-cosell-token, location Request header, and the webhook token CoSell showed when you connected as its value. Choose Customize request body and add the keyobjectIdmapped to the deal's Record ID. (If you would rather not set a header, append?token=<webhook token>to the URL instead.) - A public app's webhooks. Point the app's webhook target at the webhook URL and subscribe to
deal.creation,deal.propertyChangefor the properties you care about, anddeal.associationChange. CoSell checks HubSpot's v3 request signature with the app's client secret, so no token is needed there.