Send leads from a property portal to VelBEE.

Before you start

• The customer’s secret address. They get it from their VelBEE workspace and give it to you. You do not need to sign up with VelBEE.
• A way to send an HTTPS POST with JSON or form data.
• Ideally, a unique id for each enquiry, so a repeat delivery never makes a second lead.

How it works

Every VelBEE customer has a secret address for each portal they use. It belongs to that customer's workspace only, so leads can never land in another company's workspace. The customer gives the address to their own portal account manager and asks them to push new enquiries to it. VelBEE does not contact the portal, and the portal does not need an API key, a login or a partnership with VelBEE. The address is the whole interface.

The endpoint

POST https://api.velbee.com/v1/ingest/{source}/{secret}
Content-Type: application/json

• {source} looks like src_xxxxxxxxxxxxxxxxxxxx and {secret} looks like vbu_xxxxxxxxxxxxxxxxxxxx. Both are part of the address the customer gives you. Treat the whole address as a password and do not write it to logs.
• HTTPS only, TLS 1.2 or newer. There is no IP allow-list: requests are accepted from any address, within the limits below.
• Body: JSON (recommended) or form data (application/x-www-form-urlencoded). A JSON body is read as JSON even when the content type says otherwise. UTF-8 please.
• No other header, token or login is needed. One address per customer per portal: do not reuse an address for another customer.
• Largest request: 64 KB. A JSON list may hold up to 100 enquiries; anything after the first 100 is not read.
• Please allow a client timeout of at least 10 seconds. We normally answer within a second or two.

What an enquiry needs

A phone number (at least 6 digits) or a valid email address. Everything else is optional. An enquiry with neither is refused with 422 and nothing is saved.

Field names we recognise

Upper or lower case, dashes, spaces and camelCase are all fine: MobileNo, mobile_no and mobile-no mean the same thing. If a field appears under two recognised names, the first one in the request wins.

One level of wrapping is understood: fields inside data, fields, payload, form_data or values are read as if they were at the top. Other nested objects are flattened to a single text value, so please send flat fields. Lists become comma-separated text.

Anything else the portal sends, such as city, locality, BHK, budget, enquiry time or agent code, is kept in the lead's note (up to 15 extra fields, each cut at 300 characters, the whole note at 2,000). The customer can map those names to real lead fields later. Two things are never kept: fields named key, token, action, submit or starting with an underscore are ignored, and a request with a non-empty field called website is treated as spam and dropped without a lead, so please do not send a field with that name.

Please include, if you have them

• The enquiry id, so a repeat delivery never creates a second lead (up to 120 characters).
• A separate first name and last name, or a full name.
• The project or listing the buyer asked about, the city or locality, BHK or unit type, and budget.
• The enquiry date and time with its time zone.
• A phone number with its country code, for example +919876543210.

Example: one enquiry

{
  "enquiry_id": "PORTAL-20261008-000123",
  "name": "Asha Verma",
  "mobile": "+919876543210",
  "email": "asha@example.com",
  "project_name": "Lakeview Residences, 3 BHK",
  "city": "Hyderabad",
  "budget": "1.2 Cr",
  "enquired_at": "2026-10-08T14:32:10+05:30",
  "message": "Please call after 6 pm"
}

Example: several enquiries in one request

[
  { "enquiry_id": "A1", "name": "Ravi", "mobile": "9811100001" },
  { "enquiry_id": "A2", "name": "Meera", "mobile": "9811100002" }
]

What we answer

A single enquiry gets a small JSON answer. A list gets counts.

{ "ok": true, "duplicate": false, "message": "Thank you. We have received your details and will be in touch." }

{ "ok": true, "received": 2, "created": 2, "duplicate": 0, "refused": 0 }

Retries and duplicates

• Send the enquiry id. The same enquiry id from the same address creates one lead only, however many times it is delivered. VelBEE remembers ids for the life of the address.
• If we fail with a 5xx, the id is not used up, so your retry can succeed.
• When an enquiry in a list is refused, its id is not used up either, so it can be sent again once fixed.
• A new enquiry id from someone who already has an open lead adds the enquiry to that lead's timeline instead of creating a second lead. The customer can also have a follow-up task created for each such repeat.
• Updates to an enquiry (status changes) are not supported. Only new enquiries are read.

Limits

These count requests, not enquiries, so sending a list uses one request. The defaults are 120 requests a minute per sending IP address (counted across all addresses), 300 a minute per address, and 20,000 a day per address. If a portal sends for many customers from one IP address, use lists and honour Retry-After; the VelBEE team can raise the limits.

What happens to a lead

• The lead is created in the customer's workspace with the portal's name as its source, and the contact is reused if the phone number or email is already known.
• It is given to the person the customer chose for this address, or to the next person by the workspace's assignment rules, and that person is told.
• By default an automatic first callback task is created, due within an hour, so the new enquiry is never left waiting.
• The customer sees every request, accepted or refused, with the reason in plain words on the address's Activity screen. Personal details are never shown there.

Test leads

A test enquiry is a real lead. Please make it obvious, for example with the name TEST, so the customer can delete it.

Downloads and try it

Two files describe the same address, so your developers can try it without writing any code first. Neither file contains a secret: you add the customer's address yourself.

• Postman collection: velbee-lead-intake.postman_collection.json. Six ready requests with tests and example answers: one enquiry, a list of three, a repeat (duplicate), form data, a missing phone and email (422) and a wrong address (404).
• OpenAPI 3.0 file: velbee-lead-intake.openapi.json. The endpoint, the fields, the answers and the Retry-After header, for code generators and API tools.

Try it with curl

Replace SOURCE/SECRET with the customer's address. This creates one real lead named TEST in the customer's workspace, so tell the customer first. Run it twice: the second answer says duplicate: true and no second lead is made.

curl -X POST "https://api.velbee.com/v1/ingest/SOURCE/SECRET" \
  -H "Content-Type: application/json" \
  -d '{"enquiry_id":"TEST-0001","name":"TEST Asha Verma","mobile":"+919876543210","email":"asha@example.com","project_name":"Lakeview Residences, 3 BHK","city":"Hyderabad","budget":"1.2 Cr","enquired_at":"2026-10-08T14:32:10+05:30","message":"Please call after 6 pm"}'

Use the Postman collection

1. Import

   In Postman choose Import and select the downloaded file, or paste the collection link above.

2. Set the address

   Open the collection, go to Variables and set ingest_url to the customer's full address, for example https://api.velbee.com/v1/ingest/src_xxxxxxxxxxxxxxxxxxxx/vbu_xxxxxxxxxxxxxxxxxxxx. Save.

3. Send

   Press Send on a request, or run the whole folder with Run collection. Each request checks the answer it should get and shows a green or red result.

For the customer: how to get your address

You ask your own portal account manager to push your leads to your address. VelBEE does not contact the portal for you.

1. Create the source

   Sign in to your workspace, open Connect, press Add a source, choose Property portal and pick the portal.

2. Copy the secret address

   It is shown once. If you lose it or it leaks, press Make a new address; the old one stops working at once.

3. Send it to your account manager

   The source page writes the message for you, with a sample request, a ready curl command, the answers to expect and links to this page, the Postman collection and the OpenAPI file. Use Copy, or Send by email for a short version with the address and links.

4. Match the field names

   When the first request arrives, open the Activity tab and match any field names VelBEE did not recognise.

More for customers: Property portals guide.

Questions

Do we need an API key or a partnership with VelBEE?

No. The customer’s address is the whole interface.

What if the same enquiry is delivered twice?

Send the enquiry id. The same id from the same address creates one lead only.

What should we do when a request fails?

Retry 429 after the time in Retry-After, and 500 or 503 with back-off. Do not retry 422, 401, 403 or 404: fix the data or tell the customer.