API reference · Inbox

CRM

social_inbox · crm · 4 operations

POST/v1/social-inbox/items/{item_id}/crm/sendSend a Social Inbox direct message to the CRM POST/v1/social-inbox/items/{item_id}/crm/linkLink a Social Inbox direct message to an existing CRM record POST/v1/social-inbox/items/{item_id}/crm/unlinkReturn a direct message from the CRM to the Social Inbox POST/v1/social-inbox/items/{item_id}/crm/prospectCreate a CRM prospect from the author of a comment

POST/v1/social-inbox/items/{item_id}/crm/send

Send a Social Inbox direct message to the CRM

social_inbox.crm.send_to_crm

WriteIdempotentSince 2026-11-01

Turns an Instagram, Messenger or TikTok direct message into a CRM prospect or deal and moves its whole conversation to CRM → Messages (it leaves the Inbox AI's hands; reply to it with crm.social_dm.send). The lead source decides the destination, dedup, owner and AI qualification, like any lead: source_id (a direct-message lead source; default the one covering the account, or the system one), pipeline_id and stage_id when they exist, and destination (prospect or deal) only with the system source. owner_id sets the owner of the resulting deal (or prospect) in the same call, exactly as crm.deals.update or crm.prospects.update would (changelog, the new owner's notification, the CRM conversation's owner, crm.deal.updated): it must be a member of the organization (400 owner_not_member) and choosing it needs a CRM Manager: an owner, an admin, a CRM admin or a sales manager (403 crm_action_denied otherwise); both are checked before anything is written. The answer then says owner_id (the owner it ended with) and owner_changed. A record owned by an AI agent (ai-…; the lead source may have just given it one, and that agent starts right after the call) keeps that owner here: hand it over later with crm.prospects.update or crm.deals.update. An existing person with the same social identity is reused. Already linked: returns the current link with already_linked true and changes nothing but the owner when owner_id comes (so a retry finishes the job). A comment is not a conversation (409 crm_not_linkable: use social_inbox.crm.create_prospect). Requires full access to the Social Inbox and to the CRM, the CRM permission to create prospects and, for a credential, the crm:write scope. Optional dry run: with dry_run=true nothing is written (no source, person, prospect, deal, link or message, and the assignment rule's rotation does not move): it runs the same gates and checks and fails with the same errors (crm_not_linkable, crm_invalid_source, owner_not_member, crm_action_denied), or returns a Preview with already_linked and conversation_id; source (id, name, is_system, will_be_created: the system source this call would create the first time); destination; pipeline_id and stage_id where a new deal would land (null for a prospect or a reused record); person (id, existing: a person with the same social identity is reused); record (type prospect or deal, id, existing: the person's open deal or active prospect, or the record this contact got when it came in before, is reused); owner (id, from existing_record, assignment_rule, owner_id, contact_owner — a new prospect of a known person goes to that person's owner when they are a member of the organization — or none, rule_id, approximate: an assignment rule's choice is predicted with the same calculation as the rule's Test button and can change if another lead comes in first; a record that would be handed to an AI agent keeps it even with owner_id); and items_to_move (messages of the conversation that would move to CRM → Messages). Warnings say what the real call would silently ignore (a pipeline or stage that does not exist, destination with a non-system source), when the system source would be created and when the owner comes from a rule, an AI agent or the person's owner.

Scope: social_inbox:write
Permission: Edit in the module · CRM action: create_prospect
MCP tool: social_inbox_crm_send_to_crmOn the full surface; on the compact one, mb_execute_operation with id: "social_inbox.crm.send_to_crm".
Events it can emit: crm.lead.created crm.deal.created crm.deal.updated

Declared cost: up to 15 reads and 214 writes per call (they count against the daily quota).

Parameters

item_idstringpathrequired

The inbox item id (from social_inbox.items.list).

source_idstringbodyoptional

A direct-message lead source (crm.lead_sources.list) or a system one (_ig_dm…). Default: the one of the account that received it.

destinationenumbodyoptional

With a system source only: create a prospect or a deal (an own source decides by its configuration).

Values: prospect, deal

pipeline_idstringbodyoptional

Pipeline for a deal (crm.pipelines.list).

stage_idstringbodyoptional

Stage of that pipeline (crm.pipelines.get).

owner_idstringbodyoptional

The owner of the resulting prospect or deal, set in the same call: a member's user id. Needs a CRM Manager (owner, admin, CRM admin or sales manager).

Response

conversation_idstring

person_idstring

items_linkednumber

chat_data_suggestednumber

already_linkedboolean

prospect_idstring

deal_idstring

owner_idstring | null

Only with owner_id: the owner the deal or prospect has after the call (null when the conversation has no prospect or deal).

owner_changedboolean

Only with owner_id: whether this call changed the owner.

Errors

inbox_item_not_found crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/send" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/send" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/social-inbox/items/{item_id}/crm/link

Link a Social Inbox direct message to an existing CRM record

social_inbox.crm.link

WriteIdempotentSince 2026-11-01

Links an Instagram, Messenger or TikTok direct message to a prospect, deal or person that already exists in the CRM (entity_type and entity_id): the person keeps the social identity and the whole conversation moves to CRM → Messages. Linking edits that record, so its owner rules (the CRM permission edit_prospect, edit_deal or edit_person on it). 404 crm_entity_not_found if the record does not exist or was merged; 409 crm_not_linkable for a comment. Requires full access to the Social Inbox and to the CRM and, for a credential, the crm:write scope.

Scope: social_inbox:write
Permission: Edit in the module
MCP tool: social_inbox_crm_linkOn the full surface; on the compact one, mb_execute_operation with id: "social_inbox.crm.link".

Declared cost: up to 12 reads and 210 writes per call (they count against the daily quota).

Parameters

item_idstringpathrequired

The inbox item id (from social_inbox.items.list).

entity_typeenumbodyrequired

What to link it to: a prospect, a deal or a person of the CRM.

Values: prospect, deal, person

entity_idstringbodyrequired

Its id (crm.prospects.list, crm.deals.list or crm.persons.list).

Response

conversation_idstring

items_linkednumber

chat_data_suggestednumber

person_idstring

Errors

inbox_item_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/link" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entity_type": "prospect",
  "entity_id": "ENTITY_ID"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/link" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entity_type": "prospect",
  "entity_id": "ENTITY_ID"
}'

POST/v1/social-inbox/items/{item_id}/crm/unlink

Return a direct message from the CRM to the Social Inbox

social_inbox.crm.unlink

WriteIdempotentSince 2026-11-01

Unlinks a direct-message conversation from the CRM and returns it to the Inbox (the Inbox automation and AI can act on it again). The prospect or deal and the messages already copied stay in the CRM; chat data the conversation suggested for the person and still pending is dropped. 404 inbox_item_not_found if the item is not a direct message of this organization. Owner or admin only, with full access to the CRM (and crm:write for a credential).

Scope: social_inbox:write
Permission: Edit in the module · Only owner, admin
MCP tool: social_inbox_crm_unlinkOn the full surface; on the compact one, mb_execute_operation with id: "social_inbox.crm.unlink".

Declared cost: up to 205 reads and 205 writes per call (they count against the daily quota).

Parameters

item_idstringpathrequired

The inbox item id (from social_inbox.items.list).

Response

oktrue

items_unlinkednumber

Errors

inbox_item_not_found role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/unlink" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/unlink" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/social-inbox/items/{item_id}/crm/prospect

Create a CRM prospect from the author of a comment

social_inbox.crm.create_prospect

WriteIdempotentSince 2026-11-01

Creates a CRM prospect (or deal, as the lead source says) for the author of a comment or mention; the public thread stays in the Inbox and the comment becomes the prospect's first note. The person is tagged with the network (the network's direct-message source): source_id, pipeline_id and stage_id are optional. A LinkedIn comment or mention gives 409 crm_not_linkable: LinkedIn's terms don't allow using its members' data to create leads. Idempotent per comment: the same comment returns what it created before (already_created true). A direct message gives 409 crm_not_linkable (use social_inbox.crm.send_to_crm). Requires full access to the Social Inbox and to the CRM, the CRM permission to create prospects and, for a credential, the crm:write scope.

Scope: social_inbox:write
Permission: Edit in the module · CRM action: create_prospect
MCP tool: social_inbox_crm_create_prospectOn the full surface; on the compact one, mb_execute_operation with id: "social_inbox.crm.create_prospect".
Events it can emit: crm.lead.created crm.deal.created

Declared cost: up to 12 reads and 6 writes per call (they count against the daily quota).

Parameters

item_idstringpathrequired

The inbox item id (from social_inbox.items.list).

source_idstringbodyoptional

The lead source to create it with (crm.lead_sources.list). Default: the account's system source.

pipeline_idstringbodyoptional

Pipeline (crm.pipelines.list).

stage_idstringbodyoptional

Stage of that pipeline.

Response

person_idstring

already_createdboolean

prospect_idstring

deal_idstring

Errors

inbox_item_not_found crm_action_denied invalid_input unknown_field authentication_required scope_insufficient idempotency_key_reused rate_limited quota_exceeded

Example

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/prospect" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/social-inbox/items/{item_id}/crm/prospect" \
  -H "Authorization: Bearer $MB_TEST_KEY"