API reference

POST https://app.advision360.de/api/public/leads

Creates a lead on the lead board of the company that owns the lead key, or updates an existing lead (see Duplicate leads).

Authentication: X-API-Key header or _key field (see Authentication).

Content-Type: application/json, application/x-www-form-urlencoded or multipart/form-data.

Fields

Field	Type	Required	Description
firstName	string	yes	First name, max 100 characters.
lastName	string	yes	Last name, max 100 characters.
email	string	email or phone	Valid email address, max 255 characters.
phone	string	email or phone	Phone number, max 50 characters.
source	string	no	Origin of the lead, see allowed values. Unknown values are ignored.
notes	string	no	Free text stored on the lead.
additionalFields	object	no	Custom key-value pairs. In forms as additionalFields.<name>. See Custom fields.
_meta.url	string	no	Address of the page the lead came from. In JSON as "_meta": { "url": "…" }. The JavaScript SDK sets it automatically.
_key	string	without header	Lead key, if no X-API-Key header is set.
_redirect	string	no	Redirect target after success. Allowed domains only, see Redirect.
_test	boolean	no	true, "true" or "1" marks the lead as a test lead.

At least one of email or phone must be provided.

Allowed values for source

website, referral, phone, event, social_media, advertisement, partner, landing_page, registration, other

Responses

201 Created

The lead was created or updated. The body is an empty JSON object.

{}

302 Found

The lead was created and _redirect points to an allowed domain. The Location header contains the redirect target.

HTTP/1.1 302 Found
Location: https://www.example.com/thank-you

400 Bad Request

The data is invalid. violations has one entry per error. If both email and phone are missing, field is empty. Messages follow Accept-Language (de or en).

{
  "error": "Validation failed",
  "violations": [
    { "field": "firstName", "message": "First name is required" },
    { "field": "email", "message": "Email is not valid" },
    { "field": "", "message": "Email or phone is required" }
  ]
}

401 Unauthorized

The lead key is missing, unknown or deactivated.

{
  "error": "Invalid or inactive API key"
}

429 Too Many Requests

The rate limit is reached. retryAfter and the Retry-After header give the wait time in seconds.

{
  "error": "rate_limit_exceeded",
  "retryAfter": 1800
}

Error codes

Status	Meaning	Cause
400	Bad Request	Required fields are missing or values are invalid.
401	Unauthorized	The lead key is missing, unknown or deactivated.
403	Forbidden	The company's license does not include the Leads module.
429	Too Many Requests	The key's rate limit is reached.
500	Server Error	Unexpected error. Retry later, contact support if it persists.

Rate limit

Each lead key allows 100 requests per hour, counted per fixed one-hour window. Once it is used up, the API responds with 429 and a Retry-After header.

If you need more requests, spread the traffic over several keys, e.g. one per website.