Iblai API Crm

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 $IBLAI_API_KEY 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, IBLAI_USERNAME, and IBLAI_API_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": [ /* … */ ] }

next_page / previous_page 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 { "primary_id": UUID, "duplicate_ids": [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 primary_email. Body (all optional): is_admin (bool), is_staff (bool), enrollment_config (object, forwarded to auto-enroll the invitee), redirect_to (url). Success returns the invitation_id; 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 { "user_id": int } (required; the user must already be an active member of your org, else 403). Sets platform_user.

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 stage_code (preferred) or stage_id.
• POST /api/crm/deals/{id}/won/ — close the deal as won. Body optional: stage_code to target a specific is_won stage (defaults to the pipeline's first is_won stage by sort_order).
• POST /api/crm/deals/{id}/lost/ — close the deal as lost. Body requires a non-empty lost_reason (≤255; 400 if missing); optional stage_code (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 done_at; see is_done/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 § Tagging):

• POST /api/crm/{host}/{id}/tags/ — attach an existing tag to a host record: body { "tag_id": int } (≥ 1). Returns 201 with { assignment_id, 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": "ada@example.com",
    "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. 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 — field-level request/response shape (Mode req/opt/ro), enums, and the confirmed filter query params for every resource.
• 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 — 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 — 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 — filtering & pagination, the RBAC role/permission matrix (cross-refs /iblai-api-rbac), the error reference, and best practices.