API
PreviewLeads
Create a lead and read its status. A lead is identified by your external_id and by the id Place returns.
| Route | Scope | Purpose |
|---|---|---|
POST /v1/leads | leads:write | Create a lead, or return the existing one on a repeat. |
GET /v1/leads/{id} | leads.status:read | Read a lead and its current status. |
During the preview, send every call as POST to https://6a6fb10b3ae9e8ded7cd73ef.base44.app/functions/placeApi and put the route into the body. Other HTTP methods are rejected with unsupported_method.
Create a lead
POST /v1/leads
Authorization: Bearer sk_place_test_…
Idempotency-Key: 5f1c9e2a-lead_82716
Content-Type: application/json{
"route": "POST /v1/leads",
"body": {
"external_id": "lead_82716",
"first_name": "Max",
"last_name": "Mustermann",
"phone": "0176 1234 5678",
"email": "max@example.com",
"street": "Hauptstraße 12",
"postal_code": "40789",
"city": "Monheim am Rhein",
"product": "Solar",
"source": "partner"
}
}Fields
Only these fields are read. Any other field is ignored, not stored. Text fields are trimmed, and anything past the length limit is cut off.
| external_id string · max 128required | Your id for this lead. It links the lead to your system and protects against duplicates. Longer ids are rejected, not shortened. |
| phone string | E.164 such as +4917612345678. German formats like 0176 1234 5678 or 0049… are converted. Spaces, dashes, slashes and brackets are removed. |
| email string · max 254 | Stored in lower case. Needs a local part, an @ and a domain with a top-level domain. |
| first_name string · max 80 | First name. |
| last_name string · max 80 | Last name. Without either name, the lead is shown as unknown. |
| street string · max 160 | Street and house number. |
| postal_code string | A five-digit German postal code. |
| city string · max 80 | City. |
| product string · max 60 | What the person is interested in, for example solar. Stored in lower case. |
| source partner | api | Where the lead comes from. Defaults to partner. Any other value also becomes partner. |
Validation rules
external_idis required.- At least one of
phoneoremailis required. A lead nobody can reach is only an address. - A field you send must be valid. An invalid phone number is an error, even when a valid email is present.
- Validation stops at the first problem and names the field in
param.
Response
A new lead returns 201 Created. A repeat of an earlier delivery returns 200 OK with the header Place-Idempotent-Replay: true and the lead as it is now.
{
"id": "pl_lead_8a1f3c",
"object": "lead",
"external_id": "lead_82716",
"status": "received",
"environment": "production",
"created_at": "2026-09-11T09:41:00.000Z"
}| id string | Place's id for the lead, starting with pl_lead_. Stable for the life of the lead. |
| object string | Always lead. |
| external_id string | The id you sent. |
| status string | The public status. See Status. |
| environment sandbox | production | The environment of the key that created the lead. |
| created_at ISO 8601 | When Place first accepted the lead. |
Sandbox
received.Consent
Duplicates and idempotency
A delivery takes effect once. Place checks two things, in this order:
- The
Idempotency-Keyheader, if you send one. Up to 255 printable ASCII characters. If the same key arrives with a differentexternal_id, the request fails with409 idempotency_key_reused. - The
external_id. A second lead with the same id returns the first one.
Both are scoped to the project and the environment. Two partners may use the same external_id, and the same id in sandbox and production are two leads. A repeat does not update the lead. Fields that changed on your side are not applied.
Read a lead
{ "route": "GET /v1/leads/pl_lead_8a1f3c" }The response has the same shape as on creation. A lead from another project or the other environment returns 404 lead_not_found, never 403, so ids cannot be probed.
Status
The public status is derived from the lead's state in Place. Each status has a matching event.
| Status | When | Event |
|---|---|---|
received | Accepted, not yet processed. | lead.received |
validated | Open and not yet assigned. | lead.validated |
assigned | Open and assigned to a rep. | lead.assigned |
contacted | Reached, callback agreed. | lead.contacted |
appointment | Appointment booked or confirmed. | lead.appointment_created |
won | Sold. | lead.won |
lost | Cancelled. | lead.lost |
Statuses can move backwards, for example from appointment to contacted when an appointment is cancelled. v1 does not report payment. There is no paid status yet.
Errors
Errors share one shape. Branch on type and code. The message is for people and may change.
{
"error": {
"type": "validation_error",
"code": "invalid_phone_number",
"message": "phone is not a valid phone number. Use E.164, e.g. +4917612345678.",
"param": "phone",
"request_id": "req_4mT0q9Xb2LkP7sVd1cQe"
}
}| HTTP | type | code |
|---|---|---|
| 401 | authentication_error | invalid_api_key, secret_key_required |
| 403 | permission_error | missing_scope, project_unavailable, production_not_enabled |
| 404 | not_found | lead_not_found, unknown_route |
| 409 | idempotency_error | idempotency_key_reused |
| 422 | validation_error | invalid_json, invalid_body, unsupported_method, missing_external_id, external_id_too_long, missing_contact, invalid_phone_number, invalid_email, invalid_postal_code |
| 500 | api_error | lead_not_created |
Retry strategy
- Retry on network errors, timeouts and
5xx. Wait longer each time, for example 1, 2, 4, 8 and 16 seconds, with some random jitter. - Always retry with the same
Idempotency-Keyandexternal_id. A retry can never create a second lead. - Do not retry
4xxerrors unchanged. Fix the key, the scope or the payload first. - Log the
request_idof every failed call. It is the fastest way to a precise answer from support.
Authentication
Send a secret key as Authorization: Bearer sk_place_…. Keys in the query string are not accepted, because URLs end up in access logs. Publishable keys starting with pk_place_ cannot call these routes. Revoked and expired keys fail with invalid_api_key. Read more in Authentication.