Which endpoint do I use?
Two endpoints write people into Klozzo and they are not interchangeable.
Picking the wrong one is the single most common way an integration ends up
losing data, and the failure is quiet: you get a 422, you log it, and nobody
notices that a form submission was thrown away.
| What you are doing | Use | Why |
|---|---|---|
| A person filled in a form on your site | POST /api/leads |
The same person can fill it in ten times. |
| An ad platform calls you back with a lead | POST /api/leads |
Retries and duplicates are expected. |
| An automation forwards somebody who raised their hand | POST /api/leads |
You did not decide they were new — they did. |
| You are migrating a database, or deliberately creating a record | POST /api/contacts |
You already know this person is new. |
| You want to change somebody who already exists | PATCH /api/contacts/{contact_id} |
You already have their id. |
What happens if you pick wrong
POST /api/leads never rejects a returning person. Post the same email
twice and you get the same contact back with contact_created: false.
POST /api/contacts answers 422 and drops everything you sent when the
person already exists. Not part of it — all of it: the new phone number, the
campaign they came from, the thing they asked for this time. There is no partial
save and no way to recover the payload afterwards.
That is the whole difference. Everything else — validation, custom fields,
phone normalisation — behaves the same on both. And it follows directly from
Leads and contacts above: /api/leads can promise never to reject anybody
precisely because a returning person is not a second record.
Sending the same thing twice on purpose
Repeat submissions of the same form, by the same person, for the same thing,
within 30 minutes count as one arrival. Send an Idempotency-Key header to
make that guarantee explicit and unbounded in time — see
Idempotency.