# MicroCRM Integration

## When to use

Use this skill whenever a task requires reading or writing customer relationship data — contacts, companies, deals, pipelines, campaigns, activities, or messages — that lives in the MicroCRM (customer relationship management) app. Typical triggers: syncing a lead captured elsewhere into the CRM, checking or advancing a deal's pipeline stage, logging an activity against a contact, sending a message tied to a contact, or checking an organization's billing entitlements before performing a gated action.

## Tools

- `http-get` — read-only calls (list/show endpoints)
- `http-post` — create calls (new records)
- `http-request` — update or delete calls (PATCH/PUT/DELETE)
- `write-file` — stage large result sets (e.g. full contact lists) instead of dumping them inline
- `send-message` — escalate to a human when access fails or a decision is needed

All calls target the base URL from the organization's Integration row for MicroCRM (for example `https://crm.newx.app/api/v1/...`). Authentication (the `Authorization: Bearer <token>` header, and optionally `X-Organization: <slug>`) is injected automatically by the Integration row. Never ask for, echo, or hardcode credentials.

## Playbook

1. To find an existing person, use `http-get` on `GET /api/v1/contacts` with a `q` query param (and optionally `status` or `segment`) to search by name/email/phone. Use `page` to paginate large result sets.
2. To inspect one record in detail, use `http-get` on `GET /api/v1/contacts/:id`.
3. To sync a new or updated lead idempotently (the safe default when you are not certain the contact already exists), use `http-post` on `POST /api/v1/contacts/upsert`, matching by email or phone.
4. To create a brand-new contact when you already know it does not exist, use `http-post` on `POST /api/v1/contacts`. To modify an existing one, use `http-request` (PATCH) on `PATCH /api/v1/contacts/:id`.
5. To look up or create company records, use `http-get` on `GET /api/v1/companies` or `http-post` on `POST /api/v1/companies`.
6. Before creating a deal, use `http-get` on `GET /api/v1/pipelines` to confirm the correct pipeline and stage names.
7. To open a new deal, use `http-post` on `POST /api/v1/deals`. To move a deal's stage or update its amount, use `http-request` (PATCH) on `PATCH /api/v1/deals/:id`.
8. To review active outreach context before acting, use `http-get` on `GET /api/v1/campaigns`.
9. To record what happened, use `http-post` on `POST /api/v1/activities`, tying the entry to the relevant contact or deal.
10. To send a message tied to a contact, use `http-post` on `POST /api/v1/messages`.
11. Before any action gated by plan or usage limits, use `http-get` on `GET /api/v1/entitlements` to confirm the organization is entitled; if not, stop and use `send-message` to explain what is blocked.
12. When a list, search, or export produces a large payload (many contacts, deals, or activities), use `write-file` to stage the full result set rather than inlining it, then summarize the key points in your response.

## Failure modes

- A 401 or 403 response means the token is missing, expired, or lacks the required scope (write actions need write scope). Stop immediately — do not retry with altered headers or invent a token. Use `send-message` naming "MicroCRM" and the exact scope needed (e.g. read or write access to contacts/deals).
- A missing or unconfigured Integration row for the organization means there is no base URL to call. Stop and use `send-message` asking a human to configure the MicroCRM integration for that organization.
- A 404 on `:id` lookups means the record does not exist in that organization's scope (check whether `X-Organization` scoping is producing an unexpected organization); do not fabricate a substitute record.
- A 422 on create/update usually means a validation error (e.g. malformed email/phone on upsert); report the validation message back rather than silently retrying with guessed data.

## Done when

The requested contact, company, deal, activity, or message has been created, updated, or retrieved via the correct endpoint and confirmed by the API's response (not assumed), any large result set has been staged with `write-file` and summarized, and any entitlement or authorization failure has been escalated via `send-message` rather than worked around.