iblai-api-crm

Manage an organization's CRM from the API: people and organizations, pipelines and their stages, lead sources, deals (with stage-move / won / lost actions), activities, and tags — all the sales and relationship-management records for one organization. Use for lead capture, pipelines, and deal flow.

Auth & conventions

• Base URL: https://api.iblai.app/dm — CRM is a Data Manager (DM)

endpoint, so the /dm prefix is required; the /api/crm/... paths below are appended to it (e.g. https://api.iblai.app/dm/api/crm/persons/).

• Header: Authorization: Api-Token $IBLAIAPIKEY on every request. (The CRM

developer docs phrase this as Authorization: Token <key> — it is the same Platform API Token.)

• Scope: Platform-scoped. Every record belongs to the organization resolved

from the token, so there is no {org} in the path.

• Ids: integers for every resource except Person and Organization, whose

ids are UUID strings.

• Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG,

IBLAIUSERNAME, and IBLAIAPI_KEY.

Resources

Each resource supports standard REST: GET (list), POST (create), GET {id} (read), PATCH {id} (update), DELETE {id} (delete). DELETE is destructive — confirm with the user first.

Useful filters

• owner={user_id} — "my pipeline" / "my accounts".
• owner__isnull=true — unowned records.
• ?is_default=true on pipelines — the seeded pipeline; its response embeds its

stages inline.

Pagination

List GETs are page-numbered. Navigate with ?page={n} and override the page size with ?page_size={n} (default 50). The list envelope is:

{ "count": 137, "next_page": 3, "previous_page": 1, "results": [ /* … */ ] }

nextpage / previouspage are page numbers (or null at the ends), not URLs — a detail different from stock DRF pagination.

Reads

Person

• GET /api/crm/persons/ — list people.
• GET /api/crm/persons/{id}/ — read a person.

Organization

• GET /api/crm/organizations/ — list organizations.
• GET /api/crm/organizations/{id}/ — read an organization.

Pipeline

• GET /api/crm/pipelines/ — list pipelines.
• GET /api/crm/pipelines/{id}/ — read a pipeline.

Stage

• GET /api/crm/pipelines/{pipeline_id}/stages/ — list a pipeline's stages.
• GET /api/crm/pipelines/{pipeline_id}/stages/{id}/ — read a stage.

Lead Source

• GET /api/crm/lead-sources/ — list lead sources.
• GET /api/crm/lead-sources/{id}/ — read a lead source.

Deal

• GET /api/crm/deals/ — list deals.
• GET /api/crm/deals/{id}/ — read a deal.

Activity

• GET /api/crm/activities/ — list activities.
• GET /api/crm/activities/{id}/ — read an activity.

Tag

• GET /api/crm/tags/ — list tags.
• GET /api/crm/tags/{id}/ — read a tag.

Writes

Person

• POST /api/crm/persons/ — create a person.
• PATCH /api/crm/persons/{id}/ — update a person.
• DELETE /api/crm/persons/{id}/ — delete a person. Confirm with the user first.

Person actions:

• POST /api/crm/persons/merge/ — merge duplicates into one: body

{ "primaryid": UUID, "duplicateids": [UUID, …] }; reparents the duplicates' deals / activities / tags onto the primary. Destructive — confirm first.

• POST /api/crm/persons/{id}/invite/ — email an invitation to the person's

primaryemail. Body (all optional): isadmin (bool), isstaff (bool), enrollmentconfig (object, forwarded to auto-enroll the invitee), redirectto (url). Success returns the invitationid; 409 if an active invitation already exists for that email (the response carries the existing invitation_id, so you can track / resend it), 422 if the person is already linked to a platform user. Sends outward — confirm with the user first.

• POST /api/crm/persons/{id}/link-user/ — link the CRM person to an existing

platform user: body { "userid": int } (required; the user must already be an active member of your org, else 403). Sets platformuser.

Organization

• POST /api/crm/organizations/ — create an organization.
• PATCH /api/crm/organizations/{id}/ — update an organization.
• DELETE /api/crm/organizations/{id}/ — delete an organization. Confirm with the user first.

Pipeline

• POST /api/crm/pipelines/ — create a pipeline.
• PATCH /api/crm/pipelines/{id}/ — update a pipeline.
• DELETE /api/crm/pipelines/{id}/ — delete a pipeline. Confirm with the user first.

Stage

• POST /api/crm/pipelines/{pipeline_id}/stages/ — create a stage.
• PATCH /api/crm/pipelines/{pipeline_id}/stages/{id}/ — update a stage.
• DELETE /api/crm/pipelines/{pipeline_id}/stages/{id}/ — delete a stage. Confirm with the user first.

Lead Source

• POST /api/crm/lead-sources/ — create a lead source.
• PATCH /api/crm/lead-sources/{id}/ — update a lead source.
• DELETE /api/crm/lead-sources/{id}/ — delete a lead source. Confirm with the user first.

Deal

• POST /api/crm/deals/ — create a deal.
• PATCH /api/crm/deals/{id}/ — update a deal.
• DELETE /api/crm/deals/{id}/ — delete a deal. Confirm with the user first.

Deal actions (the canonical way to transition deals):

• PATCH /api/crm/deals/{id}/ — reposition stage within a pipeline (allowed).
• POST /api/crm/deals/{id}/move-stage/ — transition stage; body accepts

stagecode (preferred) or stageid.

• POST /api/crm/deals/{id}/won/ — close the deal as won. Body optional:

stagecode to target a specific iswon stage (defaults to the pipeline's first iswon stage by sortorder).

• POST /api/crm/deals/{id}/lost/ — close the deal as lost. Body requires

a non-empty lostreason (≤255; 400 if missing); optional stagecode (defaults to the first is_lost stage).

Activity

• POST /api/crm/activities/ — create an activity.
• PATCH /api/crm/activities/{id}/ — update an activity.
• DELETE /api/crm/activities/{id}/ — delete an activity. Confirm with the user first.
• POST /api/crm/activities/{id}/done/ — mark the activity done (stamps doneat; see isdone/done_at in the schema).

Tag

• POST /api/crm/tags/ — create a tag.
• PATCH /api/crm/tags/{id}/ — update a tag.
• DELETE /api/crm/tags/{id}/ — delete a tag. Cascades — removes every

assignment on every person / organization / deal. Confirm with the user first.

Attach / detach on a host ({host} = persons | organizations | deals; both need Ibl.CRM/Tags/write, a separate RBAC bucket from host-write — see [references/workflows.md](references/workflows.md) § Tagging):

• POST /api/crm/{host}/{id}/tags/ — attach an existing tag to a host record:

body { "tagid": int } (≥ 1). Returns 201 with { assignmentid, tag }; 409 if already attached (idempotent — carries the existing assignment_id, so treat it as success); 404 if the tag isn't in your org.

• DELETE /api/crm/{host}/{id}/tags/{tag_id}/ — detach a tag (removes the

assignment row, not the tag). 204 on success; 404 if it wasn't attached. Not idempotent — a repeat DELETE returns 404; treat that as a no-op success.

Example

Create a person:

curl -X POST \
  "https://api.iblai.app/dm/api/crm/persons/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "primary_email": "[email protected]",
    "lifecycle_stage": "lead"
  }'

Notes

• CRM is served via the DM gateway at https://api.iblai.app/dm/api/crm/

(equivalent to the legacy https://platform.iblai.app/api/crm/ host; skills standardize on the api.iblai.app/dm form).

• Lifecycle stages are lead | qualified | opportunity | customer | churned.
• A CRM Person auto-links to a Platform user when a signup matches by email.
• Stages are nested under a pipeline; deal transitions go through the deal

actions (move-stage/, won/, lost/) rather than ad-hoc edits.

• Every read is scoped to your org (the token's platform), so a record in

another org returns 404, not 403 — existence is never leaked. Treat 404 as "not found or not visible to you".

Schema

Field-level request/response shape (Mode req/opt/ro) for every resource, plus the enums and the confirmed filter query params, live in a reference file to keep this skill scannable: [references/schema.md](references/schema.md). Read it when you need exact field names, types, defaults, or which filters a list GET accepts.

Reference material

The endpoints and field schemas above are the authoritative, code-verified surface. These companion files (ported from the CRM developer guide) preserve the surrounding concepts, workflows, and guidance — read them for depth, not for endpoint truth:

• [references/schema.md](references/schema.md) — field-level request/response shape (Mode req/opt/ro), enums, and the confirmed filter query params for every resource.
• [references/guide.md](references/guide.md) — concepts & data model: system overview, write side-effects, the deal-status state machine, auth/security notes, the object graph, the resource map, and per-resource deletion/cascade behavior.
• [references/quickstart.md](references/quickstart.md) — end-to-end worked walkthrough: capture a lead, find the seeded pipeline, open a deal, move it through stages, and close it won.
• [references/workflows.md](references/workflows.md) — subsystem lifecycles: person onboarding (link / invite / merge / auto-link), deal lifecycle, activity timeline & auto-records, tagging, and CRM notifications (cross-refs /iblai-api-notification).
• [references/operations.md](references/operations.md) — filtering & pagination, the RBAC role/permission matrix (cross-refs /iblai-api-rbac), the error reference, and best practices.