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
limitandcursor. The response carries the nextcursorwhen 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" }:
facetscounts the items each filter value would leave, given the search and the other filters.scanLimitedistruewhen 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
cursorthat 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 |