Ingest a lead
crm.leads.ingest
Creates a lead the same way a webhook or a form does: the person is created or matched (email, phone), their company is created or matched, and a prospect (or a deal, if the source sends there) enters the inbox with assignment rules, notifications, scoring and sequences applied. Without a rule that picks someone, a new prospect goes to the owner of its person when they are a member of the organization (not a viewer), with the system's owner change and the 'Lead received' notice, and otherwise it is left unassigned. A seller with restricted scope cannot ingest a lead whose person (matched by email or phone) belongs to someone else and is outside what they can see: 403 prospect_contact_not_visible, and nothing is written. Pass external_lead_id (your id for the lead): the same id never enters twice. duplicate is true only when nothing new was created: the same external_lead_id came again, the source discards duplicates, or the lead went to a deal or prospect the person already had (re-engagement: open or active, closed with its notice pending, or brought back from closed or archived). A known person without one gets a new prospect (or deal) and duplicate: false. When something new is created, for a new or a known person, crm.lead.created fires; a new deal also fires crm.deal.created and the Deal created sequence trigger, and the Contact created trigger fires only when the person is new. When duplicate is true, nothing fires. By default the lead enters through the org's system source API; source_id can point to a generic or manual source instead. title, value and currency apply only when the source creates a deal. Each new lead is scored with AI when the source and the org's scoring block have it on (it consumes the organization's AI credits); without AI credits in the organization's pool the lead enters unscored, marked for the daily scoring refresh, which scores it once there are credits again. When an assignment rule makes an AI position the owner, that position starts working the lead right after it enters (it may write to it); without AI credits for its turn it does not write and hands the lead off at once to the team (its escalation person, or a person the assignment rule picks). Run it first with dry_run: it says, writing nothing, whether the lead already entered or the person exists, where it goes, who would own it and whether it would be scored with AI. In the practice organization of test keys the lead enters the same way, but no AI position starts working it (even if an assignment rule makes one its owner) and nobody is notified; there is no 409, because which owner a rule picks is only known while the lead enters. Requires create_prospect (or create_deal when the source sends to a pipeline).
- Alcance
crm:write- Permiso
- Editar en el módulo
- Tool del MCP
crm_leads_ingestEn la superficie completa; en la compacta,mb_execute_operationconid: "crm.leads.ingest".- Eventos que puede emitir
- crm.lead.createdcrm.deal.created
Costo declarado: hasta 37 lecturas y 16 escrituras por llamada (cuentan en el cupo diario).
Parámetros
source_idstringcuerpoopcionalA generic or manual lead source (crm.lead_sources.list); omit it to use the organization's system source API.
first_namestringcuerpoopcionalThe person's first name.
last_namestringcuerpoopcionalThe person's last name.
full_namestringcuerpoopcionalThe full name, used when first_name and last_name do not come: split at the first space.
emailstring (email)cuerpoopcionalThe person's email: with the phone, how an existing person is matched.
phonestringcuerpoopcionalThe person's phone, ideally in international format (+54…).
company_namestringcuerpoopcionalThe person's company: matched or created.
job_titlestringcuerpoopcionalThe person's job title.
countrystringcuerpoopcionalThe person's country, ISO 3166-1 alpha-2 (AR, MX, US…); territories route by it.
websitestring (uri)cuerpoopcionalThe person's own website (a company site goes in custom_fields or the company).
titlestringcuerpoopcionalThe deal's title. Used only when the source creates a deal (destination deal); a prospect is titled with the person's name and has no value.
valuenumbercuerpoopcionalThe deal's value. Used only when the source creates a deal (destination deal); a prospect is titled with the person's name and has no value.
currencystringcuerpoopcionalThe deal's currency (ISO 4217; default: the source's). Used only when the source creates a deal (destination deal); a prospect is titled with the person's name and has no value.
external_lead_idstringcuerpoopcionalYour id for the lead in the system it comes from: the same id never enters twice (it answers duplicate: true).
submitted_atintegercuerpoopcionalWhen the person sent it, epoch ms (default: now).
custom_fieldsobjectcuerpoopcionalFree answers of the form, by key; a key that is the slug of a CRM custom field (crm.custom_fields.list) is stored typed in that field.
Respuesta
person_idstringduplicatebooleansource_idstringprospect_idstringdeal_idstringErrores
Ejemplo
curl -X POST "https://api.mb-suite.com/v1/crm/leads" \
-H "Authorization: Bearer $MB_API_KEY"Probar con tu API key de prueba
Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.
curl -X POST "https://api.mb-suite.com/v1/crm/leads" \
-H "Authorization: Bearer $MB_TEST_KEY"