LidmeoDevelopers

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é"…), or null.
  • 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 the contacts:read scope. work_email_status is deliverable (the address receives), risky (it may not arrive), invalid (it bounced, or does not exist) or unknown; null without a work e-mail.
  • external_ids: the objects of your tools linked to this prospect, which you set with PUT /v1/prospects/{id}/external_ids.
  • An unknown field is null: missing data is never guessed.

Lidmeo's stages

pipeline_stageThe person
trackedis followed in the CRM, without sending (an imported prospect: "Importé")
queuedwaits for their turn in the sending queue
awaiting_invitation_approvalwaits for you to approve their invitation
invitedreceived the invitation
connectedaccepted it
awaiting_message_approvalwaits for you to approve their first message
messagedreceived the first message
repliedreplied, on LinkedIn, by e-mail or on WhatsApp
removedwas 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.

On this page