API

Preview

Leads

Create a lead and read its status. A lead is identified by your external_id and by the id Place returns.

RouteScopePurpose
POST /v1/leadsleads:writeCreate a lead, or return the existing one on a repeat.
GET /v1/leads/{id}leads.status:readRead 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_id is required.
  • At least one of phone or email is 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

Sandbox requests are validated, de-duplicated and logged like production requests. They never create a real lead, and their status stays received.

Consent

Leads sent through the API are recorded as unconfirmed. v1 has no field for proof of consent, and Place does not mark API leads as consented.

Duplicates and idempotency

A delivery takes effect once. Place checks two things, in this order:

  1. The Idempotency-Key header, if you send one. Up to 255 printable ASCII characters. If the same key arrives with a different external_id, the request fails with 409 idempotency_key_reused.
  2. 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.

StatusWhenEvent
receivedAccepted, not yet processed.lead.received
validatedOpen and not yet assigned.lead.validated
assignedOpen and assigned to a rep.lead.assigned
contactedReached, callback agreed.lead.contacted
appointmentAppointment booked or confirmed.lead.appointment_created
wonSold.lead.won
lostCancelled.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"
  }
}
HTTPtypecode
401authentication_errorinvalid_api_key, secret_key_required
403permission_errormissing_scope, project_unavailable, production_not_enabled
404not_foundlead_not_found, unknown_route
409idempotency_erroridempotency_key_reused
422validation_errorinvalid_json, invalid_body, unsupported_method, missing_external_id, external_id_too_long, missing_contact, invalid_phone_number, invalid_email, invalid_postal_code
500api_errorlead_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-Key and external_id. A retry can never create a second lead.
  • Do not retry 4xx errors unchanged. Fix the key, the scope or the payload first.
  • Log the request_id of 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.