Facebook Pixel
Agentic CRM

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/crm

Authentication

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 on GET /prospects, GET /stages and GET /tags, and a body field on POST /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

StatusBodyWhen
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

MethodPathWhat it does
GET/prospectsList prospects
POST/prospectsAdd a prospect
GET/prospects/{id}Get a prospect
PATCH/prospects/{id}Update a prospect
DELETE/prospects/{id}Delete a prospect
GET/prospects/{id}/notesList notes
POST/prospects/{id}/notesAdd a note
GET/prospects/{id}/reminderGet the open follow-up
PUT/prospects/{id}/reminderSet or move the follow-up
DELETE/prospects/{id}/reminderMark the follow-up done
GET/stagesList pipeline stages
GET/tagsList 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"
}
FieldNotes
linkedinUrlnull for a person added by email only.
email, emailLockedAn 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.
stagenull means the person is in New.
dealCurrencyThe workspace's deal currency, set in the app under Reports. Defaults to USD.
expectedCloseAtA date, YYYY-MM-DD, or null.
outcome"won", "lost", or null for an open deal. Separate from the stage.
nextReminderThe open follow-up, or null.
sourcesWhere 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.

QueryTypeWhat it does
searchstring, up to 200 charactersMatches name or company. Not case sensitive. Emails are not searched.
stageIdstringA stage id, or new for people with no stage.
tagstringOnly people with this exact tag.
tagsstringSeveral tags, separated by commas.
tagsModeany or allWith several tags: match any of them (the default) or all of them.
outcomeactive, won or lostFilter by deal result.
ownerIdstringOnly people assigned to this user id.
sourcestringOne of the sources values above.
hasEmailtrue or falsetrue returns only people with an email.
updatedSinceISO dateOnly people updated at or after this time.
limit1 to 200Page size. The default is 50.
cursorstringThe nextCursor from the previous page.
workspaceIdstringNeeded 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:

FieldNotes
successtrue
prospectsAn array of prospect objects.
hasMoretrue when there is another page.
nextCursorPass 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.

FieldTypeNotes
linkedinUrlstringA personal profile link, like https://www.linkedin.com/in/jane-doe. Company and school pages are rejected.
emailstringAdds a person you have no LinkedIn profile for.
name, company, titlestringUp to 200 characters each.
phonestringUp to 40 characters. Must be a valid phone number.
stageIdstringA stage id from GET /stages.
tagsstring[]
dealValuenumberZero or more.
expectedCloseAtstringYYYY-MM-DD.
ownerUserIdstringMust be a member of the workspace.
notestringA first note, up to 5,000 characters.
workspaceIdstringNeeded 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 201 with "created": true.
  • A person who is already in the workspace returns status 200 with "created": false and 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.

FieldTypeNotes
stagestringA stage name, for example "Interested". Not case sensitive.
stageIdstring or nullA stage id. null moves the person back to New. Send stage or stageId, not both.
ownerUserIdstring or nullMust be a member of the workspace. null unassigns.
addTags, removeTagsstring[]Up to 20 each.
dealValuenumber or nullZero or more.
expectedCloseAtstring or nullYYYY-MM-DD.
outcome"won", "lost" or nullnull reopens the deal and clears the reason. The stage is not changed.
outcomeReasonstring or nullUp to 500 characters.
namestring1 to 200 characters.
company, headlinestring or nullUp to 200 characters.
linkedinUrlstringAttaches 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, company or headline you set is kept when ConnectSafely refreshes the profile from LinkedIn.
  • linkedinUrl returns 409 with This person already has a different LinkedIn profile when 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.

FieldTypeNotes
bodystringRequired. 1 to 5,000 characters.
kindnote, call, meeting or emailDefaults 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.

FieldTypeNotes
dueAtISO date-timeRequired. Must be in the future.
notestringUp to 1,000 characters.
timeZonestringUp 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 }
  ]
}
FieldNotes
systemKeySet 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.
hiddentrue for stages hidden from the board, such as Archived.
orderPosition 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.

On this page