CoSell docs Open CoSell

API reference

Everything the console does goes through the CoSell HTTP API, and your own tools can call it too.

Base URL and authentication

  • Base URL: https://api.cosell.habilelabs.io/api/v1
  • Authentication: Authorization: Bearer <ID token> from a CoSell user (Amazon Cognito). Calls run with that user's role in the workspace.
  • Bodies are JSON. Errors come back as { "error": "…", "details": [...] } with a meaningful status code:
    • 400: the request was malformed
    • 403: not allowed, or AWS refused the action
    • 404: not found
    • 409: a business rule was broken
    • 422: validation failed
    • 413: the body is larger than 1.5 MB
    • 429: too many requests. Each person may make 600 requests a minute and each workspace 3,000; AI requests, support requests and invitations also have hourly and daily allowances per person and per workspace. The message says which one ran out
  • Lists are paged with limit and cursor. The response carries the next cursor when there is more.

All workspace paths below start with /tenants/{tenantId}.

Searching, filtering and sorting lists

The opportunity, invitation, error, notification, audit and bulk job lists can also be searched, filtered and sorted. Add any of q, sort, order or offset to a list request, and it answers with numbered pages instead of a cursor.

Parameter Meaning
q Words to find. Every word must appear somewhere in the item; case does not matter.
sort, order A column from the table below, and asc or desc. Items without a value come last.
offset, limit Where the page starts, and its size (25 unless set, at most 100).
A filter name One or more values, separated by commas, for example syncStatus=failed,needs_information.
List Filters Sort columns
opportunities syncStatus, origin, reviewStatus (none when AWS has not reviewed it), aceStage, awsLinkId, inAws (yes or no) updated, title, company, stage, review, sync, lastSync
invitations status, awsLinkId received, respondBy, expires, title
errors resolution, category created, retries, category, deal
notifications type, read (read or unread) created, type
audit action, actor, entityType created, actor, action
bulk status, kind created, finished, status

The answer is { "items", "total", "offset", "limit", "sort", "order", "facets", "scanLimited" }:

  • facets counts the items each filter value would leave, given the search and the other filters.
  • scanLimited is true when the workspace holds more than 5,000 records of that kind. In that case only the newest 5,000 were searched (for invitations and sync errors, the newest 5,000 of each status).
  • A cursor that this API did not hand out for that list is refused with 400.
GET /tenants/{tenantId}/opportunities?q=acme&syncStatus=failed&sort=updated&order=desc&offset=0&limit=50

Workspace

Method and path Purpose
GET /me The caller and their workspaces
GET /install CoSell installed in your own AWS account only: its version, licence state, last check-in and incentive figures (the workspace's admins)
GET /install/support-bundle CoSell installed in your own AWS account only: the support bundle, with no deal content, contacts or secrets (the workspace's admins; each download is audited)
GET /tenants/{tenantId} Workspace settings and plan, your roles there, and scope: whose deals you see (all, team or own)
PATCH /tenants/{tenantId}/settings Update preferences ({ "name", "settings": { … } }; admins, and alliance managers when only submissionMode, autoAcceptInvitations, invitationSlaHours, importAwsOpportunities and agentWrites change). settings.recordAccess: everyone (default) or own, where sales reps see their own deals and sales managers their team's
GET /tenants/{tenantId}/dashboard Counts by status, invitations, errors, Zoho budget
GET /tenants/{tenantId}/sales The sales dashboard's figures: open pipeline, won and lost, win rate, what is due, the pipeline by stage and by month, AWS co-sell figures, the largest and next-closing opportunities, owners, and leads on CoSell CRM. ?period=month|quarter|year (default quarter); ?owner=me counts only the caller's opportunities
GET /tenants/{tenantId}/sales/leads The Leads list: CoSell CRM's leads, and the AWS leads CoSell put in the workspace's external CRM (page: "invitation", opened by the invitation id), within the caller's view: { items } with name, company, email, status, source, owner and crm
GET /tenants/{tenantId}/sales/accounts The Accounts list: CoSell CRM's accounts, and one row per company of the opportunities CoSell tracks elsewhere (page: "company", with opportunities counting them), within the caller's view: { items }
GET /tenants/{tenantId}/sales/account?kept=&key= One account's page: CoSell CRM's account (kept=cosell, key = its id), or a company of the opportunities CoSell tracks elsewhere (kept = the CRM, or aws; key = the company's name). The account with its details, its people (contacts), its opportunities (open first), the leads that name it, its activities (notes, calls, meetings, emails and tasks, the most recent first), and the currency its totals count in, within the caller's view; 404 when the caller sees none of it
POST /tenants/{tenantId}/sales/account/activities?kept=&key= Logs a note, call, meeting, email or task on an account (named as for its page), for people with records:write on an account they can see. Body: { kind: "note" | "call" | "meeting" | "email" | "task", subject?, body?, at? (ISO time a call, meeting or email happened), due? (YYYY-MM-DD, tasks) }; a note needs body, the others subject, a task due. CoSell keeps it; an external CRM does not see it: 201 { id }
PATCH /tenants/{tenantId}/sales/account/activities/{id}?kept=&key= Changes an activity: subject, body, at, due only by whoever logged it (a field sent empty is cleared, and the result must still be complete for its kind); done (tasks) by anyone with records:write. Answers the activity
DELETE /tenants/{tenantId}/sales/account/activities/{id}?kept=&key= Removes an activity: whoever logged it, or someone with records:reassign: 204
GET /tenants/{tenantId}/sales/contact?kept=&key= One contact's page: CoSell CRM's contact (kept=cosell, key = its id), or a customer contact of the opportunities CoSell tracks elsewhere (key = email, else name). The person, their account as the Accounts list holds it, the opportunities they are the contact of, and their activities (as on an account's page), within the caller's view; 404 when the caller sees none of it
POST, PATCH /{id}, DELETE /{id} on /tenants/{tenantId}/sales/contact/activities?kept=&key= A contact's notes, calls, meetings, emails and tasks, the contact named as for their page: the same bodies, answers and rules as an account's activities above. What is logged on a person is not on their company
GET /tenants/{tenantId}/sales/contacts The Contacts list: CoSell CRM's contacts, and one row per customer contact of the opportunities CoSell tracks elsewhere, as AWS holds it (page: "person", key = email, else name, which the opportunities' contact carries, with opportunities counting them), within the caller's view: { items }
GET /tenants/{tenantId}/sales/deals Every opportunity the dashboard counts, wherever it is kept: { items, currency, asOf, stageOrder }. Each item has its stage, state (open, won, lost), amount and currency, close date, owner, crm (where it is kept; absent when only Partner Central has it), its Partner Central id and review status, and mine
GET, POST /tenants/{tenantId}/members List members, each with account: invited, active, reset_required, disabled, missing or unknown; or invite one ({ "email", "roles" })
POST /tenants/{tenantId}/members/{userId}/password Send a new temporary password to an invited member, or a reset code to an active one (admins, and alliance managers for the roles they may give); answers { "sent": "invitation" | "reset", "email" }
PATCH /tenants/{tenantId}/members/{userId} Change a member's roles, and a sales rep's sales manager ({ "roles": ["sales_rep"], "managerId": "<user id>" | null }; admins, and alliance managers for alliance_manager, sales_manager, sales_rep and viewer). Roles: tenant_admin, alliance_manager, sales_manager, sales_rep, sales_ops, viewer
DELETE /tenants/{tenantId}/members/{userId} Remove a member

Connections

Method and path Purpose
GET /tenants/{tenantId}/connections/zoho Zoho connection state, redirect and webhook URLs
POST /tenants/{tenantId}/connections/zoho/authorize Start the Zoho consent flow
POST /tenants/{tenantId}/connections/zoho/activate Re-run activation (fields, channel, currency)
GET /tenants/{tenantId}/connections/zoho/fields Deal fields usable in filters and routing rules
GET /tenants/{tenantId}/onboarding-template The CloudFormation template for your AWS account
GET /tenants/{tenantId}/onboarding-template/launch CloudFormation links that create (launchUrl) or update (updateUrl) the stack with that template, and a link to the template itself (templateUrl); each works for an hour
GET, POST /tenants/{tenantId}/aws-links List or link AWS accounts
POST /tenants/{tenantId}/aws-links/{linkId}/verify Check the link again
POST /tenants/{tenantId}/aws-links/{linkId}/default Make the link the default
GET /tenants/{tenantId}/aws-links/own-account CoSell installed in your own AWS account only: that account's link, with what to do when Partner Central refused it
POST /tenants/{tenantId}/aws-links/own-account/check Check Partner Central from that account again (admins)

Mapping

Method and path Purpose
GET, PUT /tenants/{tenantId}/mapping Read or save the mapping (a new version per save)
GET /tenants/{tenantId}/mapping/check Is a deal at the gate ready to submit, and why not
POST /tenants/{tenantId}/mapping/deal-filter/preview Try one rule's conditions on recent deals
POST /tenants/{tenantId}/mapping/rules/preview Try rules not saved yet on recent deals ({ "rules", "otherDeals" }): how many each rule takes, and where each recent deal would go

Opportunities and referrals

Method and path Purpose
GET /tenants/{tenantId}/opportunities Tracked deals and their ACE opportunities
GET /tenants/{tenantId}/opportunities/{crmRecordId} One deal with its sync history
POST /tenants/{tenantId}/opportunities/{crmRecordId}/actions { "action": "sync" | "submit" | "refresh" | "retry" }
GET, POST /tenants/{tenantId}/opportunities/{crmRecordId}/assistant Ask Partner Central ({ "question" }) and read the answers (people who see every deal: refused with 403 to sales reps and managers where they see only their own)
POST /tenants/{tenantId}/opportunities/{crmRecordId}/drafts Draft next steps and a summary ({ "meetingNotes" }, optional)
POST /tenants/{tenantId}/opportunities/{crmRecordId}/agent-refresh/draft Draft a customer business problem and next steps for the Partner Central agent to set
POST /tenants/{tenantId}/opportunities/{crmRecordId}/agent-refresh Ask the agent to set both ({ "businessProblem", "nextSteps" }); its proposal waits in Ask Partner Central
GET /tenants/{tenantId}/aws-import/preview?scope=live Opportunities that can be imported into Zoho
POST /tenants/{tenantId}/aws-import Import them ({ "opportunityIds", "awsLinkId" }). "links": { "<opportunity id>": "<deal id>" } links an opportunity to a deal the CRM already has instead of making one
POST /tenants/{tenantId}/aws-import/all Import every opportunity of a scope the CRM does not hold yet, in the background ({ "scope": "live" | "all_open" | "year", "awsLinkId" }, both optional; the last 12 months when no scope is named); answers { "status": "started" } and the work appears under /bulk
GET /tenants/{tenantId}/invitations?status=pending AWS referrals
PUT /tenants/{tenantId}/invitations/{invitationId}/assignee Give an AWS referral or lead to a member to work ({ "userId": "<user id>" | null }; alliance managers and admins)
POST /tenants/{tenantId}/invitations/{invitationId}/decision { "decision": "accept" | "reject", "reason", "awsLinkId" }
POST /tenants/{tenantId}/invitations/{invitationId}/import Finish the import of an accepted referral now
POST /tenants/{tenantId}/invitations/refresh Check AWS for invitations CoSell missed; answers { "ingested", "removed" }, with "continuing": true when the rest are being pulled in the background

Bulk operations, private offers and partners

Method and path Purpose
GET /tenants/{tenantId}/bulk/csv-template The CSV template for your mapping
POST /tenants/{tenantId}/bulk/csv/check Check a CSV ({ "csv" }) without writing anything
POST /tenants/{tenantId}/bulk/csv Import it as a bulk job
POST /tenants/{tenantId}/bulk/update { "crmRecordIds", "changes": [{ "field", "value" }], "runAt" }; fields include stage and lostReason
POST /tenants/{tenantId}/bulk/assign { "crmRecordIds", "assignee": { "name", "email" }, "runAt" }
GET /tenants/{tenantId}/bulk, GET /tenants/{tenantId}/bulk/{jobId} Bulk jobs, and one job's rows
POST /tenants/{tenantId}/bulk/cancel { "jobId" }
GET /tenants/{tenantId}/opportunities/{crmRecordId}/offers Linked private offers, their agreements and drafts
POST /tenants/{tenantId}/opportunities/{crmRecordId}/offers/link { "offer" } (ID or ARN)
POST /tenants/{tenantId}/opportunities/{crmRecordId}/offers/draft { "productId", "name", "buyerAccountId" }
GET /tenants/{tenantId}/marketplace/offers, GET /tenants/{tenantId}/marketplace/products Your private offers and products, to link or draft one (opportunities:sync: admins, alliance managers, sales operations)
GET /tenants/{tenantId}/partners Partners you are connected with, to invite one (opportunities:sync): name is your workspace's name for the partner, else Partner Central's (nameFrom: workspace or aws; awsName is Partner Central's)
PUT /tenants/{tenantId}/partners/{accountId}/name Name a connected partner for your workspace ({ "name": "…" }, up to 80 characters; empty removes it; admins)
GET /tenants/{tenantId}/opportunities/{crmRecordId}/engagement The opportunity's partners and invitations sent
POST /tenants/{tenantId}/opportunities/{crmRecordId}/partner-invitations { "receiverAccountId", "responsibilities", "message" }
POST /tenants/{tenantId}/partners/snapshot-role Use CoSell's snapshot job role (admins)

AI: assistant, proposals and pipeline health

Method and path Purpose
GET, POST /tenants/{tenantId}/assistant/conversations Your conversations; start one with { "message" }
GET /tenants/{tenantId}/assistant/conversations/{conversationId} A conversation, its messages, its proposals and the deals its answers name (deals, left out while it answers; conversation.progress holds the steps so far)
POST /tenants/{tenantId}/assistant/conversations/{conversationId}/messages Send { "message" }; the answer arrives asynchronously
PATCH /tenants/{tenantId}/assistant/conversations/{conversationId} Rename your conversation ({ "title" })
DELETE /tenants/{tenantId}/assistant/conversations/{conversationId} Delete your conversation and its messages (409 while it is answering)
PUT /tenants/{tenantId}/assistant/conversations/{conversationId}/messages/{messageId}/feedback Rate an answer: { "rating": "helpful" | "not_helpful" | null, "note"? }
GET /tenants/{tenantId}/proposals?status=pending Proposals, filtered by status, crmRecordId or conversationId
POST /tenants/{tenantId}/proposals/decision { "proposalId", "decision": "approve" | "reject" | "override", "text", "note" }
GET /tenants/{tenantId}/risks Pipeline health findings (?crmRecordId= for one deal)
POST /tenants/{tenantId}/risks/dismiss { "key", "snoozeDays" }; without snoozeDays, until the facts change
POST /tenants/{tenantId}/risks/restore { "key" }

Errors, notifications and audit

Method and path Purpose
GET /tenants/{tenantId}/errors?resolution=open Sync errors
POST /tenants/{tenantId}/errors/actions { "errorId", "action": "retry" | "resolve" }
GET /tenants/{tenantId}/notifications Notifications. Each has a path: the console page it is about, relative to the workspace (for example opportunities/{crmRecordId})
POST /tenants/{tenantId}/notifications/read Mark one read ({ "notificationId" })
POST /tenants/{tenantId}/notifications/read-all Mark every unread notification read; answers { "marked" }
DELETE /tenants/{tenantId}/notifications Delete them all (admins); answers { "deleted" } and is audited
GET /tenants/{tenantId}/audit The audit log

Endpoints without a user

Method and path Purpose
POST https://api.cosell.habilelabs.io/webhooks/zoho/{tenantId} Zoho workflow webhook; send the webhook token in x-cosell-token
POST https://api.cosell.habilelabs.io/marketplace/register CoSell's old AWS Marketplace fulfilment URL: answers 307 to the HabileLabs Marketplace signup, https://marketplace.habilelabs.io/api/marketplace/register
GET https://api.cosell.habilelabs.io/health Service health