MicroCRM Integration

skill

Read, create, and update MicroCRM records through its REST API using an org Integration row.

Download .md

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.