Conversations · LeadForge docs

Een conversation is een LinkedIn-gesprek met een prospect, zoals je het ook in de Inbox ziet. Met de API lees je gesprekken en hun berichten, en zet je een antwoord klaar dat LeadForge daarna via LinkedIn verstuurt. Alleen LinkedIn-gesprekken komen mee.

Gesprekken ophalen

GET https://leadforge.nl/api/v1/conversations

Vraagt read

LinkedIn-gesprekken van je werkruimte, met het laatste bericht eerst.

Queryparameters

Naam	Type	Standaard	Beschrijving
limit	getal	50	Aantal gesprekken per pagina, hoogstens 200.
cursor	tekst		De nextCursor van de vorige pagina.
since	datum		Alleen gesprekken met lastMessageAt vanaf dit moment, als ISO-datum. Een ongeldige datum wordt genegeerd.
label	tekst		Alleen gesprekken met precies dit label. Zie de waarden hieronder.

De lijst staat op lastMessageAt, laatste eerst. Hoe je doorbladert staat in Paginering en filters.

curl

curl "https://leadforge.nl/api/v1/conversations?label=interested&limit=50" \
  -H "Authorization: Bearer LF_LIVE_SLEUTEL"

JSON Antwoord 200

{
	"data": [
		{
			"id": "<gesprek-id>",
			"name": "Anna Jansen",
			"profileUrl": "https://www.linkedin.com/in/voorbeeld",
			"threadUrl": null,
			"label": "interested",
			"unread": true,
			"lastInbound": true,
			"lastMessageAt": "2026-11-05T13:40:00.000Z",
			"lastSnippet": "Klinkt goed, kun je volgende week bellen?",
			"aiIntent": null,
			"leadId": "<lead-id>",
			"createdAt": "2026-11-02T09:14:00.000Z"
		}
	],
	"hasMore": false,
	"nextCursor": null
}

Velden van een gesprek

Velden

Naam	Type	Beschrijving
id	tekst (uuid)	Het id van het gesprek.
name	tekst of null	De naam van de prospect, anders het onderwerp van het gesprek.
profileUrl	tekst of null	Adres van het LinkedIn-profiel van de prospect.
threadUrl	tekst of null	Adres van het gesprek op LinkedIn, als dat bekend is.
label	tekst of null	Het label van het gesprek. Zie hieronder.
unread	boolean	Of het gesprek ongelezen is.
lastInbound	boolean of null	Of het laatste bericht van de prospect kwam.
lastMessageAt	datum (ISO) of null	Wanneer het laatste bericht is verstuurd.
lastSnippet	tekst of null	Het begin van het laatste bericht.
aiIntent	tekst of null	De bedoeling van het gesprek volgens de AI, als die is vastgesteld.
leadId	tekst (uuid) of null	De lead bij dit gesprek, als die er is.
createdAt	datum (ISO)	Wanneer het gesprek in LeadForge is aangemaakt.

Labelwaarden

Waarde	In de app
`new`	Nieuw
`interested`	Interesse
`meeting`	Afspraak
`not_now`	Later
`not_interested`	Geen interesse
`done`	Afgerond

Goed om te weten

Een gesprek zonder label staat in de app als Nieuw, maar de API geeft dan null. Een filter op label=new vindt alleen gesprekken die echt het label new hebben.

Eén gesprek ophalen

GET https://leadforge.nl/api/v1/conversations/{id}

Vraagt read

Eén LinkedIn-gesprek met zijn berichten.

Padparameters

Naam	Type	Beschrijving
id*(verplicht)	tekst (uuid)	Het id van het gesprek.

* verplicht

Het antwoord heeft alle velden van een gesprek en daarnaast messages: hoogstens 200 berichten, oudste eerst.

Velden

Naam	Type	Beschrijving
messages[].id	tekst (uuid)	Het id van het bericht.
messages[].direction	tekst	inbound voor een bericht van de prospect, outbound voor een bericht van jouw kant.
messages[].text	tekst	De tekst van het bericht.
messages[].sentAt	datum (ISO)	Wanneer het bericht is verstuurd. Bij een antwoord dat je zelf klaarzette is dat het moment van klaarzetten.

JSON Antwoord 200

{
	"data": {
		"id": "<gesprek-id>",
		"name": "Anna Jansen",
		"...": "alle velden van een gesprek",
		"messages": [
			{
				"id": "<bericht-id>",
				"direction": "outbound",
				"text": "Hoi Anna, dank voor je reactie.",
				"sentAt": "2026-11-04T10:02:00.000Z"
			},
			{
				"id": "<bericht-id>",
				"direction": "inbound",
				"text": "Klinkt goed, kun je volgende week bellen?",
				"sentAt": "2026-11-05T13:40:00.000Z"
			}
		]
	}
}

Status	Code	Wanneer
200		Het gesprek met zijn berichten.
404	not_found	Gesprek niet gevonden. Het id bestaat niet in je werkruimte, is geen LinkedIn-gesprek of is geen geldig id.
401	unauthorized	Geen geldige sleutel.
403	forbidden	De sleutel heeft geen read, of hoort niet bij één werkruimte.
429	rate_limited	Meer dan 120 verzoeken per minuut.

Een antwoord versturen

POST https://leadforge.nl/api/v1/conversations/{id}/reply

Vraagt write

Een antwoord in een LinkedIn-gesprek in de wachtrij zetten.

De API verstuurt niet zelf

Dit adres zet het bericht in de wachtrij. LeadForge verstuurt het daarna via LinkedIn, met de Chrome-extensie of de achtergronddienst, binnen het verzendvenster en de daglimiet van het account. Een 201 betekent dus dat het bericht klaarstaat, niet dat het al bij de prospect is. Zie Limieten en veiligheid.

Padparameters

Naam	Type	Beschrijving
id*(verplicht)	tekst (uuid)	Het id van het gesprek.

* verplicht

Body

Naam	Type	Beschrijving
message*(verplicht)	tekst	De tekst van het antwoord, hoogstens 1000 tekens. Spaties aan het begin en eind worden weggehaald.

* verplicht

Verzoek

curl -X POST https://leadforge.nl/api/v1/conversations/<gesprek-id>/reply \
  -H "Authorization: Bearer LF_LIVE_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{"message": "Dank je, ik bel je dinsdag om 10 uur."}'

const antwoord = await fetch(
	`https://leadforge.nl/api/v1/conversations/${gesprekId}/reply`,
	{
		method: 'POST',
		headers: {
			Authorization: 'Bearer LF_LIVE_SLEUTEL',
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ message: 'Dank je, ik bel je dinsdag om 10 uur.' })
	}
);
const resultaat = await antwoord.json();
if (antwoord.status !== 201) throw new Error(resultaat.error.code + ': ' + resultaat.error.message);

import json
import urllib.error
import urllib.request

body = json.dumps({"message": "Dank je, ik bel je dinsdag om 10 uur."}).encode()
verzoek = urllib.request.Request(
    f"https://leadforge.nl/api/v1/conversations/{gesprek_id}/reply",
    data=body,
    method="POST",
    headers={"Authorization": "Bearer LF_LIVE_SLEUTEL", "Content-Type": "application/json"},
)
try:
    with urllib.request.urlopen(verzoek) as antwoord:
        print(json.load(antwoord))
except urllib.error.HTTPError as fout:
    print(fout.code, json.load(fout)["error"])

JSON Antwoord 201

{
	"data": {
		"jobId": "<taak-id>",
		"status": "queued"
	}
}

Volgorde van fouten

De API controleert in deze volgorde. De eerste controle die faalt bepaalt het antwoord.

Status	Code	Wanneer
401	unauthorized	Geen geldige sleutel.
403	forbidden	Deze sleutel heeft geen 'write'-rechten, of hoort niet bij één werkruimte.
429	rate_limited	Meer dan 120 verzoeken per minuut.
400	empty	Bericht is leeg: message ontbreekt, is leeg of de body is geen geldige JSON.
404	not_found	Gesprek niet gevonden: het id bestaat niet in je werkruimte of is geen LinkedIn-gesprek.
400	too_long	Maximaal 1000 tekens.
404	not_found	LinkedIn-account niet gevonden: er hangt geen gekoppeld LinkedIn-account aan het gesprek.
409	paused	Het LinkedIn-account is gepauzeerd. De melding geeft de reden, of: Je LinkedIn-account is gepauzeerd, vernieuw je sessie op 'LinkedIn koppelen'.
409	duplicate	Er staat al een antwoord klaar voor dit gesprek. Wacht tot dat antwoord verstuurd is.
201		Het antwoord staat in de wachtrij.

Een GET op dit adres geeft 405 zonder body.

Wat er gebeurt na een 201

Het antwoord staat meteen als uitgaand bericht in het gesprek, ook in de app. Het krijgt als sentAt het moment van klaarzetten, ook al is het dan nog niet verstuurd.
Het gesprek staat op gelezen (unread wordt false) en lastInbound wordt false.
De webhook conversation.reply_sent gaat uit met via: "api".

Bij een paused: vernieuw de LinkedIn-sessie. Zie LinkedIn koppelen.

Verder lezen

Inbox
Gebeurtenissen: een seintje bij elk nieuw bericht
Fouten