# Sending leads

## Best practices

Based on our experience, best practices for sending leads to Realpad CRM include:

* Make sure to have a **captcha** on the web to filter out spam at the most opportune moment (nothing down the line has more context than the website itself).
* Always keep a **full log of the leads**, and be ready to replay them to the API in case there is any problem on the first try.
  * In case your call results in an HTTP 2xx, just log the success.
  * If the result is HTTP 4xx, there is a problem with the call, and it makes no sense to retry automatically. Please, get in touch with our support team, and include the information about the time of the request and the response you received. Be ready to re-submit the lead with updated information.
  * In case the result is HTTP 5xx, you can retry sending the lead automatically at a later time.
* If possible include the **name of the enquired unit** in the call (parameter `internalid`). This helps the sales agents to process the lead more efficiently.

## Request

Use **HTTP POST** and the endpoint `https://cms.realpad.eu/ws/v10/create-lead`

{% hint style="danger" %}
Do not send data as JSON in this endpoint. The API expects to receive a URL-encoded form. See the cURL example for guidance.
{% endhint %}

Send the following parameters as a URL-encoded form:

#### Authentication

* `login` - **mandatory** string login obtained from our support.
* `password` - **mandatory** string password obtained from our support.

#### Basic contact information

* `name` - **mandatory** string first name of the lead.
* `surname` - **mandatory** string last name (surname) of the lead.
* `email` - string email address of the lead. Always validate the value provided by the user to a reasonable degree so that it is useful in the CRM.
* `phone` - string phone number of the lead. Always provide it in the [E.164 format](https://en.wikipedia.org/wiki/E.164) including the international prefix (for example, `+420777123456`) for unambiguous representation in the CRM.
  * **Important note: either `email` of `phone` (or both) must be provided.**
* `project` - integer Realpad database ID of the project to assign the lead to.
* `salesman` - integer Realpad database ID of the salesman to assign the lead to, skipping the round-robin algorithm. Only send if instructed so by our support team.

#### **Preference tracking**

* `preferencerooms` - optional string, pipe-separated list of the preferred "rooms" (for example: `1+kk` or `2+1|3+1`).
* `preferencepricemax` - optional integer, maximum indicated price in the project currency for the lead.

{% hint style="info" %}
These are our first steps into structured preference tracking. Reach out to <support@realpadsoftware.com> in case your contact form gathers more detailed structured preference data.
{% endhint %}

* `internalid` - string "internal ID" (sometimes called "number in the project") of the unit that the customer sent the request from.
* `unitid` - integer database ID of the unit that the customer sent the request from.

{% hint style="info" %}
**Please use either `unitid` or `internalid`, not both.**

Using one of these parameters will add the specified unit to the so-called favorites of that customer.
{% endhint %}

#### **Referral and campaign**

* `referral` - optional **but strongly recommended**, integer, **our support team will provide the value to use**.
* `campaign` - string ID of the campaign that attracted the lead to the web of the project.

#### Miscellaneous

* `language` - string, valid [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) code of the customer's preferred language. Examples: sk, cs, en, de.
* `tags` - string, comma-separated list of tags to add to the customer.
* `note` - string free-form note. Often this is used to transport some note field from the contact form, in Realpad it is saved in an event.

{% hint style="info" %}
The `note` parameter, just like the other string parameters, is limited to 5000 characters. If you exceed this limit, the API call will fail.
{% endhint %}

#### Customer consent tracking

* `consentsource` - string free-form text describing the source of the consents being obtained. The original intention for this parameter is to contain the IP address from which the lead submitted the contact form.
* `consents` - string comma-separated list of consent type IDs. Use `list-consent-types` to discover available IDs and their names.
* `updateconsents` - same structure as the previous parameter, but a different semantics: using `consents`, in case the lead already exists in CRM and has some consent records, these will be first cleared before setting up new ones based on the provided values. Using `updateconsents`, any existing consents will be kept, and only the provided ones will be updated.

{% hint style="warning" %}
**Important: `consents` vs `updateconsents` have very different behavior.**

* **`consents`** is **destructive** — it removes **all** existing consents on the customer and replaces them entirely with the provided list. If you send an empty value, all consents are cleared.
* **`updateconsents`** is **additive** — it only updates or adds the specified consent IDs. Any consents not mentioned in the parameter are left unchanged.
* These two parameters are **mutually exclusive**. Sending both in the same request results in a `400 Bad Request` error.

**Recommendation:** Use `updateconsents` unless you intentionally need to reset all of a customer's consents. This avoids accidentally removing consents that were set through other channels (e.g., the Realpad web interface).
{% endhint %}

### Custom attributes

The endpoint can accept additional parameters - attributes. Prior to sending these attributes via the API, they must be configured within the CRM system. Below are the instructions on how to pass various types of attributes to the system:

{% stepper %}
{% step %}

### Boolean

`value` can be `true` or `false`.

* `customer_has_pets=true`
  * To set the boolean attribute to "true" / "on".
* `customer_has_pets=false` or no parameter sent.
  * To keep the boolean attribute as "false" / "off".

*Example call in **cURL:***

```bash
curl \
--data "login=...&password=...&name=John&surname=Doe&phone=...&email=...&customer_has_pets=true" \
https://cms.realpad.eu/ws/v10/create-lead
```

{% endstep %}

{% step %}

### String

Nothing special needed, just provide the whole string (with spaces, comas etc. as a value).

*Example call in **cURL:***

```bash
curl \
--data "login=...&password=...&name=John&surname=Doe&phone=...&email=...&customer_google_campaign_id=summer-2024" \
https://cms.realpad.eu/ws/v10/create-lead
```

{% endstep %}

{% step %}

### Integer

Number **with no thousands separators** must be provided, just the 0-9 digits.

*Example call in **cURL:***

```bash
curl \
--data "login=...&password=...&name=John&surname=Doe&phone=...&email=...&customer_age=42" \
https://cms.realpad.eu/ws/v10/create-lead
```

{% endstep %}

{% step %}

### Decimal

Same as for the **integer**, just use period `.` for the decimal separator.
{% endstep %}

{% step %}

### Date

Date in the ISO format **YYYY-MM-DD** must be provided.

*Example call in **cURL:***

```bash
curl \
--data "login=...&password=...&name=John&surname=Doe&phone=...&email=...&customer_voucher_date=2024-03-17" \
https://cms.realpad.eu/ws/v10/create-lead
```

{% endstep %}

{% step %}

### Single-select (Enumeration)

Usually there are select options configured as 1 (`value`) - first option (`label`), 2 - second option for some attribute with key `customer_ab_test_param`.

So to send a request send an attribute with single value.

*Example call in **cURL:***

```bash
curl \
--data "login=...&password=...&name=John&surname=Doe&phone=...&email=...&customer_ab_test_param=1" \
https://cms.realpad.eu/ws/v10/create-lead
```

{% endstep %}

{% step %}

### Multi-select (Option)

Same as for **single-select,** but extended with option to send multiple values as a comma-separated list.

*Example call in **cURL:***

```bash
curl \
--data "login=...&password=...&name=John&surname=Doe&phone=...&email=...&customer_preferred_dispositions=4,7" \
https://cms.realpad.eu/ws/v10/create-lead
```

{% endstep %}
{% endstepper %}

{% hint style="info" %}
If you don't want to set the attribute - don't include it into the API call.
{% endhint %}

## Response

The response body upon a successful call is an integer in plain text — the internal ID of the lead (or existing customer).

**Status codes:**

* `200 OK` — the response body is the Customer ID (plain integer) — the same for both newly created and previously known Customers.
* `400 BAD REQUEST` — missing or invalid parameters. The response body contains a specific error message.
* `401 NOT AUTHORIZED` — invalid credentials, insufficient permissions, or your account is currently banned.

For additional status codes that apply to all endpoints (415, 429, and banning behavior), see [Authentication & Error Handling](https://dev.realpadsoftware.com/integrations/introduction/authentication-and-error-handling).

## Testing

Please coordinate with the real estate developer and our support team. When it comes to the pricelist testing we'll trigger a change in the CRM data of a unit (or perhaps replace its floor plan) and observe whether the change is correctly shown on the website. In the opposite direction, we'll fill in a few test leads via the contact form and observe whether they are correctly saved to the CRM.

## Verifying submitted leads (`list-leads`)

Use this endpoint to confirm that leads submitted via `create-lead` were received and processed correctly.

### Request

```bash
curl \
  --data "login=...&password=..."
  https://cms.realpad.eu/ws/v10/list-leads
```

No additional parameters are needed. The endpoint automatically returns leads created by your integration account within the last 7 days.

### Response

The response is a **JSON array** of lead objects, ordered by most recent first:

```json
[
  {
    "inquiry_id": 12345,
    "customer_id": 67890,
    "customer_name": "Jane Smith",
    "timestamp": "2026-03-01T14:30:00+01:00",
    "projects": ["Riverside Residences"],
    "campaign": "spring-2026",
    "product_interest": "2-bedroom apartment"
  }
]
```

### Scope and limitations

* Only returns leads created **by your integration account** — you will not see leads created by other accounts, by other integrators, or manually in Realpad
* Limited to the **last 7 days**
* The response intentionally excludes sensitive fields like email, phone, sales agent assignment, and lead status

### Use case

After calling `create-lead`, call `list-leads` to verify the lead appears in the list. This is especially useful during initial integration development and for ongoing monitoring.

For status codes and error handling, see [Authentication & Error Handling](https://dev.realpadsoftware.com/integrations/introduction/authentication-and-error-handling).

## Discovering consent types (`list-consent-types`)

Use this endpoint to discover the available consent type IDs for your tenant. The returned IDs are the values to use in the `consents` and `updateconsents` parameters of `create-lead`, and in `revoke-customer-consent`.

### Request

```bash
curl \
  --data "login=...&password=..." \
  https://cms.realpad.eu/ws/v10/list-consent-types
```

No additional parameters are needed beyond authentication. Credentials must have the `READ_CUSTOMER_DATA` permission.

### Response

The response is a **JSON array** of consent type objects:

```json
[
  { "id": 1, "name": "Marketing consent" },
  { "id": 2, "name": "Data processing consent" }
]
```

## Revoking customer consent (`revoke-customer-consent`)

Use this endpoint to programmatically revoke a specific consent for a customer — for example, when a customer unsubscribes on your side and the revocation needs to be reflected in Realpad CRM.

The consent record is invalidated but not deleted, preserving the audit trail for compliance purposes.

Credentials must have the `WRITE_CUSTOMER_DATA` permission.

### Request

```bash
curl \
  --data "login=...&password=...&email=jan.novak@example.com&consentid=1&notes=Unsubscribed+via+web" \
  https://cms.realpad.eu/ws/v10/revoke-customer-consent
```

### Parameters

* `email` — customer's primary email address. Mutually exclusive with `customerid` — provide exactly one.
* `customerid` — internal CRM customer ID. Mutually exclusive with `email` — provide exactly one.
* `consentid` — **mandatory** consent type ID to revoke (from `list-consent-types`).
* `notes` — optional free-text reason for the revocation. Appended to existing consent notes.

### Response

* `200 OK` — consent revoked successfully. Empty response body.
* `400 BAD REQUEST` — missing or invalid parameters (e.g. neither `email` nor `customerid` provided, or invalid `consentid`).
* `409 CONFLICT` — the provided `email` matches more than one customer. Use `customerid` for precise targeting.

For additional status codes, see [Authentication & Error Handling](https://dev.realpadsoftware.com/integrations/introduction/authentication-and-error-handling).

***

Reach out to our support team in case of trouble.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.realpadsoftware.com/integrations/landing-page/sending-leads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.