Capsule CRM

Manage parties, opportunities, and tasks in Capsule CRM via its REST API v2.

This tool wraps the Capsule Developer API (https://api.capsulecrm.com/api/v2) using only the Python standard library. It reads and writes the three core Capsule record types — parties (people and organisations), opportunities, and tasks.

Operations

Operation	Method / Endpoint	What it does
`list_parties`	`GET /parties`	List parties (contacts), newest page first.
`search_parties`	`GET /parties/search?q=`	Search parties by name, postcode, or phone (requires `query`).
`create_party`	`POST /parties`	Create a person (`firstName`/`lastName`) or an organisation (`organisation`).
`list_opportunities`	`GET /opportunities`	List opportunities.
`create_opportunity`	`POST /opportunities`	Create an opportunity (requires `name`, `partyId`, `milestoneId`).
`list_tasks`	`GET /tasks`	List tasks; optional `status` filter (`open`/`completed`/`pending`).
`create_task`	`POST /tasks`	Create a task (requires `description`).

All read operations accept page (default 1) and perPage (1–100, default 50).

API key setup

Capsule supports a single personal access token so you do not need the full OAuth 2 flow for an internal integration:

Sign in to Capsule.
Go to My Preferences > API Authentication Tokens.
Generate a token and copy it.
Pass it as the apiKey input. The tool sends it as Authorization: Bearer <token> on every request.

No userEmail or app id is needed — the token alone authenticates the request.

Inputs

Input	Required	Notes
`apiKey`	yes	Personal access token (Bearer).
`operation`	yes	One of the operations above.
`query`	for `search_parties`	Search value.
`name`	for `create_opportunity`	Opportunity name (or org name on `create_party`).
`firstName` / `lastName`	for person `create_party`	At least one required.
`organisation`	for org `create_party`	Sets party type to organisation.
`email`	optional	Work email attached on `create_party`.
`description`	for `create_task`	Task summary (optional opportunity description).
`detail`	optional	Longer task note.
`partyId`	for `create_opportunity`	Required; optional on `create_task`.
`milestoneId`	for `create_opportunity`	Pipeline stage id.
`dueOn`	optional	Task due date, `YYYY-MM-DD`.
`status`	optional	`list_tasks` filter.
`page` / `perPage`	optional	Paging for list/search.

Outputs

result — the raw Capsule JSON response body as a string.
status — the HTTP status code as a string (e.g. 200, 201, 401).

The tool never raises on a non-2xx response; it returns the status and body so the caller can branch on them. A transport-level failure (DNS, refused, timeout) emits {"error": ...} and exits non-zero, marking the step FAILED.

Examples

Search for a contact named "Acme":

operation = search_parties
query     = Acme

Create a person with a work email:

operation = create_party
firstName = Scott
lastName  = Spacey
email     = [email protected]

Create an organisation:

operation    = create_party
organisation = Capsule Ltd
email        = [email protected]

Open a new opportunity against party 42 in milestone 3:

operation   = create_opportunity
name        = Website redesign
partyId     = 42
milestoneId = 3
description = Q3 redesign engagement

List open tasks:

operation = list_tasks
status    = open

Create a follow-up task due next week:

operation   = create_task
description  = Follow up on proposal
partyId      = 42
dueOn        = 2026-06-20

Notes

Base URL: https://api.capsulecrm.com/api/v2
Auth: Authorization: Bearer <personal access token>
Standard library only (urllib, json); response bodies capped at ~5 MB.
Grounded in https://developer.capsulecrm.com/.