CRM API
REST reference for the ConnectSafely Agentic CRM. Endpoints for prospects, notes, follow-up reminders, stages and tags, with fields, filters and errors.
The CRM API lets your own code read and change your CRM. It is included free with your account and needs only your API key.
Basics
Base URL
https://api.connectsafely.ai/crmAuthentication
Send your API key as a bearer token on every request. Get the key from the API Key page.
curl https://api.connectsafely.ai/crm/stages \
-H "Authorization: Bearer YOUR_API_KEY"Workspace
Every call acts on one workspace.
- If your key belongs to one workspace, that workspace is used.
- If it belongs to more than one, pass
workspaceId. It is a query parameter onGET /prospects,GET /stagesandGET /tags, and a body field onPOST /prospects. - Calls with a prospect id in the path use that prospect's workspace. You must be a member of it.
Interactive reference
A Swagger page is at api.connectsafely.ai/crm/docs, and the OpenAPI file is at https://api.connectsafely.ai/crm/openapi.json.
Errors
| Status | Body | When |
|---|---|---|
| 400 | { "success": false, "error": "..." } | The request is not valid. The error text names the problem, for example Unknown stage or dueAt must be in the future. |
| 400 | { "success": false, "error": "workspaceId is required when your key belongs to more than one workspace" } | Your key is in several workspaces and you did not say which. |
| 401 | { "error": "Unauthorized - Invalid credentials" } | The API key is missing or wrong. |
| 403 | { "success": false, "error": "Workspace access denied" } | You are not a member of that workspace. |
| 404 | { "success": false, "error": "Prospect not found" } | No such prospect in a workspace you belong to. |
| 500 | { "success": false, "error": "..." } | Something failed on our side. |
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /prospects | List prospects |
| POST | /prospects | Add a prospect |
| GET | /prospects/{id} | Get a prospect |
| PATCH | /prospects/{id} | Update a prospect |
| DELETE | /prospects/{id} | Delete a prospect |
| GET | /prospects/{id}/notes | List notes |
| POST | /prospects/{id}/notes | Add a note |
| GET | /prospects/{id}/reminder | Get the open follow-up |
| PUT | /prospects/{id}/reminder | Set or move the follow-up |
| DELETE | /prospects/{id}/reminder | Mark the follow-up done |
| GET | /stages | List pipeline stages |
| GET | /tags | List tags in use |
The prospect object
{
"id": "665f1c2e9b1e8a0012ab34cd",
"name": "Jane Doe",
"headline": "Head of Sales",
"company": "Acme",
"avatarUrl": null,
"linkedinUrl": "https://www.linkedin.com/in/jane-doe",
"email": "jane@acme.com",
"emailLocked": false,
"phone": null,
"stage": { "id": "665f1b7a9b1e8a0012ab3401", "name": "Interested" },
"ownerUserId": null,
"tags": ["webinar"],
"dealValue": 5000,
"dealCurrency": "USD",
"expectedCloseAt": "2026-12-31",
"outcome": null,
"outcomeAt": null,
"outcomeReason": null,
"nextReminder": { "id": "6660bb209b1e8a0012abaa01", "dueAt": "2026-11-24T10:00:00.000Z", "note": "Send the proposal" },
"sources": ["MANUAL"],
"createdAt": "2026-11-10T09:12:00.000Z",
"updatedAt": "2026-11-14T16:40:00.000Z",
"lastActivityAt": "2026-11-14T16:40:00.000Z"
}| Field | Notes |
|---|---|
linkedinUrl | null for a person added by email only. |
email, emailLocked | An email found by ConnectSafely's enrichment is masked, like j••••@acme.com, and emailLocked is true until your workspace reveals it. Emails you added or imported are never masked. |
stage | null means the person is in New. |
dealCurrency | The workspace's deal currency, set in the app under Reports. Defaults to USD. |
expectedCloseAt | A date, YYYY-MM-DD, or null. |
outcome | "won", "lost", or null for an open deal. Separate from the stage. |
nextReminder | The open follow-up, or null. |
sources | Where the person came from: INBOX_CONVERSATION, KEYWORD_ACTIVITY, CREATOR_ACTIVITY, LIST_CONTACT, CAMPAIGN_CONTACT or MANUAL. |
List prospects
GET /prospects
Returns people with the newest activity first. Unless you pass stageId, people in hidden stages such as Archived are left out.
| Query | Type | What it does |
|---|---|---|
search | string, up to 200 characters | Matches name or company. Not case sensitive. Emails are not searched. |
stageId | string | A stage id, or new for people with no stage. |
tag | string | Only people with this exact tag. |
tags | string | Several tags, separated by commas. |
tagsMode | any or all | With several tags: match any of them (the default) or all of them. |
outcome | active, won or lost | Filter by deal result. |
ownerId | string | Only people assigned to this user id. |
source | string | One of the sources values above. |
hasEmail | true or false | true returns only people with an email. |
updatedSince | ISO date | Only people updated at or after this time. |
limit | 1 to 200 | Page size. The default is 50. |
cursor | string | The nextCursor from the previous page. |
workspaceId | string | Needed only for a key in more than one workspace. |
curl "https://api.connectsafely.ai/crm/prospects?tag=webinar&hasEmail=true&limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"The response:
| Field | Notes |
|---|---|
success | true |
prospects | An array of prospect objects. |
hasMore | true when there is another page. |
nextCursor | Pass this as cursor to get the next page. null on the last page. |
To read everything, keep calling with cursor set to the last nextCursor until hasMore is false.
Add a prospect
POST /prospects
Send linkedinUrl or email. Everything else is optional.
| Field | Type | Notes |
|---|---|---|
linkedinUrl | string | A personal profile link, like https://www.linkedin.com/in/jane-doe. Company and school pages are rejected. |
email | string | Adds a person you have no LinkedIn profile for. |
name, company, title | string | Up to 200 characters each. |
phone | string | Up to 40 characters. Must be a valid phone number. |
stageId | string | A stage id from GET /stages. |
tags | string[] | |
dealValue | number | Zero or more. |
expectedCloseAt | string | YYYY-MM-DD. |
ownerUserId | string | Must be a member of the workspace. |
note | string | A first note, up to 5,000 characters. |
workspaceId | string | Needed only for a key in more than one workspace. |
curl -X POST https://api.connectsafely.ai/crm/prospects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"linkedinUrl": "https://www.linkedin.com/in/jane-doe",
"tags": ["webinar"],
"note": "Signed up for the November webinar"
}'The response is { "success": true, "created": true, "prospect": { ... } }.
- A new person returns status
201with"created": true. - A person who is already in the workspace returns status
200with"created": falseand the existing record. Only contact details that were empty (email, phone, company, title) are filled in. The stage, owner, tags, deal value and note you sent are not applied. - An email that already belongs to someone in the workspace returns that person.
Common 400 errors: Add a LinkedIn profile URL or an email, Enter a LinkedIn profile URL like linkedin.com/in/name, Enter a valid email, Enter a valid phone number, Unknown stage, Owner is not in this workspace, Enter a valid close date.
Get a prospect
GET /prospects/{id} returns { "success": true, "prospect": { ... } }.
Update a prospect
PATCH /prospects/{id}
Send only the fields you want to change. An empty body returns Nothing to update.
| Field | Type | Notes |
|---|---|---|
stage | string | A stage name, for example "Interested". Not case sensitive. |
stageId | string or null | A stage id. null moves the person back to New. Send stage or stageId, not both. |
ownerUserId | string or null | Must be a member of the workspace. null unassigns. |
addTags, removeTags | string[] | Up to 20 each. |
dealValue | number or null | Zero or more. |
expectedCloseAt | string or null | YYYY-MM-DD. |
outcome | "won", "lost" or null | null reopens the deal and clears the reason. The stage is not changed. |
outcomeReason | string or null | Up to 500 characters. |
name | string | 1 to 200 characters. |
company, headline | string or null | Up to 200 characters. |
linkedinUrl | string | Attaches a LinkedIn profile to a person added by email. |
curl -X PATCH https://api.connectsafely.ai/crm/prospects/PROSPECT_ID \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "stage": "Meeting Booked", "dealValue": 5000, "addTags": ["demo"] }'The response is { "success": true, "prospect": { ... } } with the updated person.
Things to know:
- A stage you set through the API counts as a manual move. The CRM stops moving that person's stage on its own. It also updates the label on their conversation in Unibox.
- A
name,companyorheadlineyou set is kept when ConnectSafely refreshes the profile from LinkedIn. linkedinUrlreturns409withThis person already has a different LinkedIn profilewhen the person already has one.
Delete a prospect
DELETE /prospects/{id} removes the person with their notes and reminders. It returns { "success": true, "id": "..." }.
There is no undo over the API. If the person later replies or a campaign reaches them again, the CRM adds them back.
Notes
GET /prospects/{id}/notes returns { "success": true, "notes": [ ... ] } with up to 200 notes, newest first.
POST /prospects/{id}/notes adds a note written by the owner of the API key.
| Field | Type | Notes |
|---|---|---|
body | string | Required. 1 to 5,000 characters. |
kind | note, call, meeting or email | Defaults to note. |
curl -X POST https://api.connectsafely.ai/crm/prospects/PROSPECT_ID/notes \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "kind": "call", "body": "Wants pricing for 10 seats" }'It returns status 201 and the note:
{
"success": true,
"note": {
"id": "6660aa109b1e8a0012ab9f10",
"kind": "call",
"body": "Wants pricing for 10 seats",
"pinned": false,
"createdAt": "2026-11-14T16:40:00.000Z",
"editedAt": null,
"authorUserId": "665f19009b1e8a0012ab0001"
}
}Notes cannot be edited, pinned or deleted through the API. Do that in the app.
Follow-up reminders
Each person has at most one open follow-up.
GET /prospects/{id}/reminder returns { "success": true, "reminder": { ... } }, or "reminder": null when there is none.
PUT /prospects/{id}/reminder sets it. If one is already open, it is moved to the new time.
| Field | Type | Notes |
|---|---|---|
dueAt | ISO date-time | Required. Must be in the future. |
note | string | Up to 1,000 characters. |
timeZone | string | Up to 64 characters, for example Europe/London. The reminder email shows the due time in this zone. Without it the email shows UTC. |
curl -X PUT https://api.connectsafely.ai/crm/prospects/PROSPECT_ID/reminder \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "dueAt": "2026-11-24T10:00:00Z", "note": "Send the proposal", "timeZone": "Europe/London" }'{
"success": true,
"created": true,
"reminder": {
"id": "6660bb209b1e8a0012abaa01",
"dueAt": "2026-11-24T10:00:00.000Z",
"note": "Send the proposal",
"timeZone": "Europe/London",
"userId": "665f19009b1e8a0012ab0001"
}
}A new reminder returns status 201 with "created": true. Moving an existing one returns 200 with "created": false.
When the reminder is due, an email goes to the owner of the API key that set it. If the person is assigned to someone else, that teammate gets the email too. Due reminders are checked every minute.
DELETE /prospects/{id}/reminder marks the open follow-up done. No email is sent. It returns { "success": true, "done": 1 }, where done is the number of reminders closed.
Stages
GET /stages returns your stages in board order.
{
"success": true,
"stages": [
{ "id": "665f1b7a9b1e8a0012ab3401", "name": "Interested", "color": "bg-emerald-100 text-emerald-800", "systemKey": "INTERESTED", "hidden": false, "order": 4 }
]
}| Field | Notes |
|---|---|
systemKey | Set on built-in stages. A new workspace has INVITE_SENT, CONNECTED, MESSAGED, REPLIED, INTERESTED, BOOKED and ARCHIVED. Older workspaces can also have CONTACTED, WON or LOST. null on stages you created. |
hidden | true for stages hidden from the board, such as Archived. |
order | Position on the board, starting at 0. |
New is not in this list. It is the absence of a stage.
Stages are read-only over the API. Add, reorder, hide and delete them in the app. If the list comes back empty, open the CRM in the app once. Stages are created the first time a workspace opens it.
Tags
GET /tags returns the tags in use and how many people have each, most used first, up to 500.
{ "success": true, "tags": [ { "name": "webinar", "count": 42 } ] }Other ways to call the same API
The MCP tools and the CLI commands are built from this API's OpenAPI file. Each one has the same name as an operation above. They expose the fields in that file, which is slightly fewer than the tables on this page: the tags, tagsMode, outcome, ownerId and source filters, and ownerUserId and expectedCloseAt when adding a person, are REST only.
CRM from the CLI
Use the ConnectSafely CLI to add, find and update people in your Agentic CRM from a terminal, a script or a coding agent.
Webhooks and integrations
How to get data out of the ConnectSafely Agentic CRM and into HubSpot, a spreadsheet or your own tools, including Agentic CRM webhooks and their events.
