Sending leads

Send each lead with POST /leads/intake. See the reference for every field.

curl -X POST https://crm.tropicalrealty.com.mx/api/leads/intake \
-H "x-api-key: $CRM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "idempotencyKey": "website-form-48213",
  "channel": "form",
  "email": "ana@example.com",
  "firstName": "Ana",
  "utmSource": "google",
  "utmCampaign": "fall-launch",
  "fields": { "budget": "2-3M", "preferredContact": "WhatsApp" }
}'

Required fields

Send email, phone or both. Everything else is optional. Empty strings are treated as not sent.

Fields with no matching property go in fields. They are stored with the lead and shown in the CRM’s leads inbox.

What happens to a lead

The CRM stores the lead exactly as it was received, then processes it right away:

1. Find the contact. It looks for a contact with the same email, then the same phone. If there’s none, it creates one and assigns it to the next advisor in turn.
2. Add it to a deal. If the contact already has an open deal, the lead joins it. Otherwise a new deal is opened, owned by the contact’s advisor. If you sent productId or productSku, the product is added to the deal.
3. Add a note to the deal with the message and the other fields.

The status in the response is the result:

status	Meaning
processed	The lead was added to a deal. personId and dealId are set.
pending	The lead needs a review in the CRM’s Leads inbox, e.g. its email and phone belong to two different contacts. Someone on the team decides.
rejected	The contact is one of your partners, so no deal was opened.

All three are successful responses: the lead was received and you don’t need to send it again.

Avoid duplicates with an idempotency key

If your tool retries requests (after a timeout, for example), send an idempotencyKey: any string up to 200 characters that is unique for each lead, like the form submission ID.

• The first request with a key returns 201 Created.
• Any later request with the same key returns 200 OK and the first lead, without creating another.

Keys are unique per organization and don’t expire.

Attribution

Send the UTM parameters of the page the visitor arrived on, and the CRM attributes the lead to a campaign and a source for you:

1. In the CRM, give each campaign a UTM code (Campaigns) and each source one too (Settings → Sources). Codes are lowercase and unique in your organization.
2. Tag your ad URLs with the same values, e.g. https://example.com/?utm_source=facebook&utm_campaign=cumbres-nov26.
3. Send them in utmSource and utmCampaign. Case doesn’t matter.

The CRM then picks:

• The campaign whose UTM code is utmCampaign.
• The source of that campaign or, if it has none, the source whose UTM code is utmSource.

campaignId and sourceId, when sent, take precedence. An ID that doesn’t exist in your organization returns 400 Bad Request. A UTM value that matches nothing is not an error: the lead is stored with its UTMs, and the inbox shows that no campaign has that code. Add the code to the campaign so the next leads are attributed, and choose the campaign on that lead’s deal. A lead waiting in the inbox picks up the new code when it’s processed.

Every utm* field is stored as sent and added to the deal’s note.