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).
- Escopo
crm:write- Permissão
- Editar no módulo
- Tool do MCP
crm_leads_ingestNa superfície completa; na compacta,mb_execute_operationcomid: "crm.leads.ingest".- Eventos que pode emitir
- crm.lead.createdcrm.deal.created
Custo declarado: até 37 leituras e 16 escritas por chamada (contam na cota diária).
Parâmetros
source_idstringcorpoopcionalA generic or manual lead source (crm.lead_sources.list); omit it to use the organization's system source API.
first_namestringcorpoopcionalThe person's first name.
last_namestringcorpoopcionalThe person's last name.
full_namestringcorpoopcionalThe full name, used when first_name and last_name do not come: split at the first space.
emailstring (email)corpoopcionalThe person's email: with the phone, how an existing person is matched.
phonestringcorpoopcionalThe person's phone, ideally in international format (+54…).
company_namestringcorpoopcionalThe person's company: matched or created.
job_titlestringcorpoopcionalThe person's job title.
countrystringcorpoopcionalThe person's country, ISO 3166-1 alpha-2 (AR, MX, US…); territories route by it.
websitestring (uri)corpoopcionalThe person's own website (a company site goes in custom_fields or the company).
titlestringcorpoopcionalThe 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.
valuenumbercorpoopcionalThe 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.
currencystringcorpoopcionalThe 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_idstringcorpoopcionalYour id for the lead in the system it comes from: the same id never enters twice (it answers duplicate: true).
submitted_atintegercorpoopcionalWhen the person sent it, epoch ms (default: now).
custom_fieldsobjectcorpoopcionalFree 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.
Resposta
person_idstringduplicatebooleansource_idstringprospect_idstringdeal_idstringErros
Exemplo
curl -X POST "https://api.mb-suite.com/v1/crm/leads" \
-H "Authorization: Bearer $MB_API_KEY"Testar com a sua API key de teste
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.
curl -X POST "https://api.mb-suite.com/v1/crm/leads" \
-H "Authorization: Bearer $MB_TEST_KEY"