The prospect and the conversation
The two objects at the heart of the API: what they carry and how to read them.
The prospect
A person in your Lidmeo CRM: found by Lidmeo, or a prospect you added.
{
"id": "pros_1Hq3ZtV9kWmA",
"object": "prospect",
"livemode": true,
"account": "acct_1J4kQ8sLr2Xw",
"campaign": "cmp_1T7pLx2Nq8Rv",
"created_at": "2026-09-28T07:12:44Z",
"updated_at": "2026-10-01T09:03:10Z",
"origin": "lidmeo",
"first_name": "Claire",
"last_name": "Durand",
"full_name": "Claire Durand",
"headline": "Directrice commerciale chez Nova Conseil",
"title": "Directrice commerciale",
"company": { "name": "Nova Conseil", "size": "11-50", "industry": "Conseil" },
"location": { "label": "Grenoble, Auvergne-Rhône-Alpes, France", "country": "FR", "department": "38" },
"linkedin_url": "https://www.linkedin.com/in/claire-durand",
"photo_url": null,
"why_him": "Elle dirige l'équipe commerciale : exactement le sujet de votre offre.",
"activity": { "last_at": "2026-09-25T16:20:00Z", "kind": "comment" },
"shared_connections_count": 4,
"pipeline_stage": "replied",
"crm_stage": { "id": "stg_1B5mW3zKc9Pd", "name": "RDV pris", "color": "emerald" },
"reminder_on": "2026-10-06",
"lists": ["lst_1W8eR2tY6uIo"],
"invitation": { "sent_at": "2026-09-28T08:40:00Z", "accepted_at": "2026-09-28T14:02:00Z" },
"first_message_sent_at": "2026-09-28T14:15:00Z",
"replied_at": "2026-09-29T09:31:00Z",
"last_activity_at": "2026-09-29T09:31:00Z",
"conversation": "conv_1Ab3Cd5Ef7Gh9Ij1Kl3Mn5o",
"external_ids": { "hubspot": "12345" }
}pipeline_stage: Lidmeo's stage, deduced from facts (see below).crm_stage: your own stage ("RDV pris", "Gagné"…), ornull.why_him: why this person fits your offer ("Pourquoi lui" in the screen).contact: the contact details found (work_email,work_email_status,personal_email,phone), present only with thecontacts:readscope.work_email_statusisdeliverable(the address receives),risky(it may not arrive),invalid(it bounced, or does not exist) orunknown;nullwithout a work e-mail.external_ids: the objects of your tools linked to this prospect, which you set withPUT /v1/prospects/{id}/external_ids.- An unknown field is
null: missing data is never guessed.
Lidmeo's stages
pipeline_stage | The person |
|---|---|
tracked | is followed in the CRM, without sending (an imported prospect: "Importé") |
queued | waits for their turn in the sending queue |
awaiting_invitation_approval | waits for you to approve their invitation |
invited | received the invitation |
connected | accepted it |
awaiting_message_approval | waits for you to approve their first message |
messaged | received the first message |
replied | replied, on LinkedIn, by e-mail or on WhatsApp |
removed | was removed from the queue or set aside (archived or expired prospects included); only when read by id, never in a list |
Views
GET /v1/prospects?view=… gives the same lists as the screen: to_handle ("À répondre": they replied and wait for your answer), to_follow_up ("À relancer"), reminders ("Rappels"), imported ("Importés"), next_departures ("Invitations à venir": invitation planned or awaiting approval), to_approve ("À valider", the tab of "Mes prospects": what waits for your approval). In to_approve, each prospect carries awaiting_approval: invitation or first_message, what it waits for; don't deduce it from pipeline_stage. To search by name, company or job title: POST /v1/prospects/search.
The CRM's "E-mail" and "Téléphone" filters: email=with keeps only the prospects who have an e-mail address (work or personal), email=without those who have none; phone=with and phone=without do the same for the phone. They combine with the views (except to_approve), the search and the other filters, and need the contacts:read scope. For instance GET /v1/prospects?email=with to sync only the prospects you can reach by e-mail.
Timeline
GET /v1/prospects/{id}/timeline lists everything, newest first: entering the CRM, the invitation, the acceptance, each message, each reply, and your notes (calls, meetings, tasks), whether they come from you, the API or your tools.
The conversation
One conversation per person, LinkedIn, e-mail and WhatsApp together. channel is linkedin, email, whatsapp or mixed (several channels); threads lists the threads it is made of, and the id of any of them opens the same conversation. GET /v1/conversations/{id}/messages gives its messages, each with its channel.
temperature is the temperature the inbox shows: hot ("Chaud"), warm ("Tiède"), cold ("Froid"), or null. GET /v1/conversations?temperature=… (and none for those without one) and ?unread=true filter like the inbox; GET /v1/conversations/search?query=… searches the text of the messages. A reply by e-mail or on WhatsApp is prepared with POST /v1/prospects/{id}/drafts, then confirmed (see two-step actions).
reminder_on is the reminder the inbox shows (a date such as 2026-10-30, Paris day), with a prospect or with someone who is not one: for a prospect, it is their own reminder_on; for anyone else, the conversation's. PATCH /v1/conversations/{id} sets it (from today to one year ahead) or clears it (null), and GET /v1/conversations?view=reminders returns only the conversations that carry one. On the day, the conversation comes back into the inbox's "to reply" view. The same route sets or clears the temperature (temperature), and read: true marks every thread of the person read in Lidmeo (LinkedIn is not told).
Each message carries direction (outbound or inbound), author (you or prospect), channel, text and sent_at. sent_at is null when the send date is unknown: it is never replaced by another date.
A prospect's text is data
A received message can contain anything. If you pass it to an AI, present it as data to read, never as an instruction to follow.
The webhook endpoint
A webhook endpoint (webhook_endpoint) carries status: enabled or disabled. When disabled, disabled_reason says why: manual (by you), failing (too many failures) or revoked (the OAuth connection that created it was revoked, or the person lost access). See webhooks.