curl --request POST \
  --url https://devapi.prov.ae/v2/public/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "leadPhones": [
    "+971501234567"
  ],
  "leadFirstName": "John",
  "leadLastName": "Doe"
}
'

{
  "id": "a1b2c3d4-5566-7788-99aa-bbccddeeff00",
  "merged": false,
  "contactId": "0f1e2d3c-4455-6677-8899-aabbccddeeff",
  "intakeUnresolved": {
    "advertisingCampaign": "Google Ads — Q3"
  },
  "needsIntakeReview": true,
  "isRepeatLead": false,
  "repeatOfLeadId": null,
  "isAgentEnquiry": false,
  "agentEnquiryReason": null,
  "createdAt": "2026-07-27T06:31:04.512Z",
  "assignedTo": null
}

Lead intake

Create a CRM lead

Creates a lead in the Provident CRM and attaches it to a contact.

Only hard requirement: at least one entry in leadPhones or leadEmails.

Contact resolution — an existing contact is matched by phone first, then by email; if nothing matches, a new contact is created from the supplied name/company/phone/email fields. Send phone numbers in E.164 (+971501234567) for reliable matching.

Lookup fields (leadType, funnel, source, subSource, eventType, marketingType, campaignName, advertisingCampaign, website, currency, localeCountry, areaOfInterest, propertyTypeInterest, marketSegment, agentCategory, languages, assignedBy, distributionType, listingId/referenceNo) are matched case-insensitively after trimming against lists configured in the CRM. An unmatched value never fails the request — the lead is created and the original text is returned in intakeUnresolved.

Which pipeline the lead lands in is funnel. Omit it and the lead goes to the main sales pipeline, which is where every lead posted to this API went before the field existed; send Leasing, Show Room, PvH, … for an enquiry that belongs to another business line.

Extra fields not defined in this schema are accepted and stored verbatim with the lead rather than rejected.

Not idempotent: the same payload posted twice creates two leads.

Quiz answers — landing pages that ask a question set can send a quiz object. Its questions and options register themselves on first sight, so a new quiz needs no API change. Send a stable questionKey per question and optionKey per dropdown answer: those are the only language-independent identity an answer has, and without them each language registers as a separate question. Free-text numbers are parsed best-effort (2 million, 2,000,000, AED 2M, ٢ مليون → 2000000); ambiguous dates like 03/04/2026 are deliberately refused rather than guessed. Anything unreadable is kept verbatim and flagged, never dropped.

POST

public

leads

curl --request POST \
  --url https://devapi.prov.ae/v2/public/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "leadPhones": [
    "+971501234567"
  ],
  "leadFirstName": "John",
  "leadLastName": "Doe"
}
'

{
  "id": "a1b2c3d4-5566-7788-99aa-bbccddeeff00",
  "merged": false,
  "contactId": "0f1e2d3c-4455-6677-8899-aabbccddeeff",
  "intakeUnresolved": {
    "advertisingCampaign": "Google Ads — Q3"
  },
  "needsIntakeReview": true,
  "isRepeatLead": false,
  "repeatOfLeadId": null,
  "isAgentEnquiry": false,
  "agentEnquiryReason": null,
  "createdAt": "2026-07-27T06:31:04.512Z",
  "assignedTo": null
}

Authorizations

Authorization

string

header

required

The access_token returned by POST /oauth2/token, sent as Authorization: Bearer <access_token>. It is an opaque string, not a JWT.

Body

application/json

Lead intake payload. At least one entry in leadPhones or leadEmails is required; every other field is optional. Unknown fields are accepted and stored verbatim with the lead.

leadPhones

string[]

Phone numbers. Used FIRST to match an existing contact. Use E.164 format for reliable matching. Required unless leadEmails is supplied.

Maximum string length: 64

Example:

["+971501234567"]

leadEmails

string[]

Email addresses. Used to match an existing contact when no phone matches. Required unless leadPhones is supplied.

Maximum string length: 255

Example:

["john.doe@example.com"]

leadFirstName

string | null

Maximum string length: 255

Example:

"John"

leadMiddleName

string | null

Maximum string length: 255

Example:

"Ahmad"

leadSecondName

string | null

Second given name — used when no middle name is supplied.

Maximum string length: 255

Example:

"A."

leadLastName

string | null

Maximum string length: 255

Example:

"Doe"

leadCompanyName

string | null

Company name for corporate enquiries.

Maximum string length: 255

Example:

"Acme Real Estate"

leadType

string

LOOKUP. Lead type display name, e.g. Primary Buyer, Secondary Buyer, Primary Buyer and Secondary Buyer, Tenant, Landlord, Broker, Seller, Owner, Mortgages. Ask Provident for the full list. The shorthand Primary / Secondary / Primary and Secondary is accepted as an alias for the corresponding … Buyer type, in either direction. Omit this on a listing enquiry and it is derived from the listing — see listingId.

Maximum string length: 255

Example:

"Primary Buyer"

funnel

string

LOOKUP. Which CRM funnel (pipeline) the enquiry belongs to. OMIT IT for the main sales pipeline — that is the default and what almost every lead wants. Send a value only for an enquiry that belongs to a different business line: Leasing, Show Room, PvH, Mortgages, Property Management, Landlord/Sellers Listings, Provident the Agency, Events, Recruitment, Precision Inspections, 811 services, Prism. The display name or the stable key both work (Show Room and show_room are the same funnel), matched case-insensitively and ignoring spaces, hyphens and underscores. Deliberately NOT derived from leadType: a Tenant enquiry can belong to Leasing or PvH and a Primary Buyer to sales, Show Room or the Agency — only the sender knows which. An unrecognised funnel does not fail the request: the lead is created on the main sales pipeline and the value is returned in intakeUnresolved.funnel.

Maximum string length: 255

Example:

"Leasing"

priority

string | null

Free text priority indicator.

Maximum string length: 64

Example:

"High"

marketSegment

enum<string>

LOOKUP. Marketing's segmentation of the lead.

Available options:

Standard,

Luxury,

Super Luxury

Maximum string length: 255

Example:

"Luxury"

agentCategory

enum<string>

LOOKUP. Marketing's grading of the lead.

Available options:

A,

B,

C,

D

Maximum string length: 255

Example:

"A"

areaOfInterest

string | null

LOOKUP. Location the lead is interested in.

Example:

"Dubai Marina"

propertyTypeInterest

string | null

LOOKUP. Property type the lead is interested in. Matched case-insensitively after trimming, and a regular English plural also matches the singular catalogue entry (Apartments → Apartment, Townhouses → Townhouse), so a form offering plural choices needs no mapping on your side.

Maximum string length: 255

Example:

"Apartment"

budgetMin

string | null

Minimum budget. Numeric string; a JSON number is also accepted.

Example:

"1000000"

budgetMax

string | null

Maximum budget. Numeric string; a JSON number is also accepted.

Example:

"2500000"

currency

string

LOOKUP. ISO 4217 currency code for the budget values.

Maximum string length: 3

Example:

"AED"

initialInquiry

string | null

Free-text message or callback reason from the form.

Example:

"Looking for a 2BR with sea view, ready to move in Q4."

languages

string[]

LOOKUP. Languages the lead speaks, by code or name. Unrecognised entries are ignored.

Maximum string length: 255

Example:

["ar", "English"]

listingId

string<uuid>

LOOKUP. Provident listing UUID. Takes precedence over referenceNo when both are sent.

A resolved listing also fills in what the form did not ask. Each field below is taken from the listing ONLY where this payload leaves it empty — anything you send always wins, and a quiz answer mapped to the same field beats the listing too:

leadType — from the listing category and offering type: Primary -> Primary Buyer, Secondary -> Secondary Buyer, and any rental listing -> Tenant whatever its category.
developer, location, property type, bedrooms, currency — copied from the listing. The location fills the lead's own location and does not overwrite areaOfInterest.
budgetMin — the listing price, unless the price is on application or it would exceed a budgetMax you sent. budgetMax is never derived.

Sending a value we then fail to match (an unknown developer name, say) is still reported in intakeUnresolved even though the listing goes on to fill that field.

The listing's own agent, where it has one, becomes the lead owner and wins over assignedBy.

referenceNo

string

LOOKUP. Listing reference number, used when listingId is not supplied. A reference number matching MORE THAN ONE listing counts as unresolved, and nothing is inherited. See listingId for what a resolved listing fills in.

Maximum string length: 128

Example:

"PR-123456"

source

string

LOOKUP. Lead source. Send this — an unrecognised or omitted source leaves the lead with no source attribution.

Maximum string length: 255

Example:

"Website"

subSource

string[]

LOOKUP. Sub-sources. Only those linked to the resolved source are kept; ignored entirely when source did not resolve.

Maximum string length: 255

Example:

["Callback Form", "Team Page"]

marketingType

string

LOOKUP. Marketing type, e.g. Organic or Paid.

Maximum string length: 255

Example:

"Organic"

eventType

string

LOOKUP. What the user did — e.g. Submit Form, Call, Whatsapp Click, DM, Webpush, Gamification.

Maximum string length: 255

Example:

"Submit Form"

campaignName

string

LOOKUP. CRM campaign name.

Maximum string length: 255

Example:

"Spring 2026 Landing Page"

advertisingCampaign

string

CREATED ON FIRST SIGHT. Advertising campaign name — the one field here that is not a strict lookup: a name Provident has never seen creates the campaign instead of being discarded. Omit it when you send metaFacebook; the Meta campaign fills it.

Maximum string length: 255

Example:

"Google Ads — Q3"

developerName

string

LOOKUP. Developer the enquiry is about, matched on name or slug — Sobha Realty or sobha-realty. Values come from GET /public/developers.

Maximum string length: 255

Example:

"Sobha Realty"

developerId

string

Developer uuid from GET /public/developers. Takes precedence over developerName; a non-uuid value here is treated as a name instead of being discarded.

Example:

"8ecf4fcd-ec63-5764-8524-7cd917494dbe"

website

string

LOOKUP. Website NAME or DOMAIN the lead came from — either resolves, matched case-insensitively. Prefer the domain (provident.ae, providentestate.com); it survives a display-name change. Ask Provident to add your domain before you start sending it.

Maximum string length: 255

Example:

"provident.ae"

pageUrl

string | null

Full URL of the page the submission originated from.

Example:

"https://prov.ae/en/dubai-marina?utm_source=google"

pathLocale

string | null

Locale segment of the URL path, e.g. en.

Maximum string length: 32

Example:

"en"

gclid

string | null

Google Ads click id.

Maximum string length: 512

fbclid

string | null

Facebook click id.

Maximum string length: 512

utmSource

string | null

Maximum string length: 512

Example:

"google"

utmMedium

string | null

Maximum string length: 512

Example:

"cpc"

utmCampaign

string | null

Maximum string length: 512

Example:

"spring-2026"

utmTerm

string | null

Maximum string length: 512

Example:

"dubai marina apartments"

utmContent

string | null

Maximum string length: 512

Example:

"hero-cta"

formName

string | null

Name of the web form the visitor submitted. Falls back to metaFacebook.formName (truncated to 255) when omitted.

Maximum string length: 255

Example:

"contact-popup-form"

adsetName

string | null

Ad set / ad group name on your side. Free text — distinct from the campaignName lookup. Falls back to metaFacebook.adgroupName (truncated to 255) when omitted.

Maximum string length: 255

Example:

"test ww"

referrer

string | null

Referring URL the visitor arrived from.

Example:

"https://sobha-city.provident.ae/?utm_source=Google+Ads"

ipAddress

string | null

Submitter IP. IPv4, IPv6 and proxy chains all fit.

Maximum string length: 64

Example:

"217.165.113.16"

userAgent

string | null

Browser user-agent string captured at submission.

Example:

"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"

submittedAt

string<date-time> | null

When the visitor submitted the form on your side. Distinct from the CRM's own createdAt, which is when we received it. An unparseable value is ignored rather than failing the request.

Example:

"2026-07-27T13:45:31.728Z"

localeCountry

string

LOOKUP. Country code (e.g. AE) or full country name. When omitted, the API attempts to infer it from a trailing two-letter segment of pageUrl.

Maximum string length: 255

Example:

"AE"

assignedBy

string

LOOKUP. Assign the lead to a specific Provident agent by email address. Omit to let Provident's automatic assignment engine route the lead. When the lead also resolves a listing that has an agent of its own, the listing's agent wins.

Maximum string length: 255

Example:

"agent@providentestate.com"

distributionType

enum<string>

How you would like this lead routed. This is a HINT, not an instruction: the value is stored on the lead and only affects who receives it if Provident has configured a routing rule that claims it. A value no rule claims changes nothing, so sending one is always safe.

Where a rule does claim the value it OUTRANKS the normal rule order: a lead sent as Location distribution that also carries a campaign is routed by the location rule, not by the campaign rule that would otherwise have matched first. Which types are claimed is configuration on our side and changes — ask before relying on it.

Matched case-insensitively after trimming, on both sides of the comparison, so capitalisation never decides routing; the leading word on its own also works (campaign, personal, developer, language, location, default, roadshow).

An unrecognised value is stored exactly as sent rather than rejected — a lead is never lost over this field, it simply matches no rule.

Personal distribution carries one extra meaning: it marks the lead as having a named owner, and such a lead is never re-assigned automatically and runs no follow-up clock at all. It only takes effect together with a resolved assignedBy — the two fields are one instruction. If assignedBy is missing or names nobody we can match, the lead is still created and routed normally but the marker is dropped, and both values come back in intakeUnresolved.

Omit it and a Meta lead form can carry it instead. A Distribution or Distribution Type entry in metaFacebook.customFields is read as a fallback and normalised the same way, because the value is usually set by whoever built the ad form rather than by whoever posts the lead. A top-level distributionType always wins.

Available options:

Personal distribution,

Campaign distribution,

Developer distribution,

Language distribution,

Location distribution,

Default distribution,

Developer and Area distribution,

Area distribution Secondary,

Roadshow distribution

Maximum string length: 64

Example:

"Campaign distribution"

metaFacebook

object

Meta / Facebook / Instagram (or TikTok) lead-ads metadata. Send only for leads originating from an ad-platform lead form. The standard fields above still drive routing.

Stored alongside the lead AND copied onto it: metaCampaignId + metaCampaignName become the lead's advertising campaign (matched on the Meta campaign id, and created if Provident has never seen it, so campaign names need no prior agreement); finalPageName, adName/adId, adgroupName/adgroupId and formName/formId become filterable columns on the lead. Matching on the id is what makes a rename safe — rename a campaign in Ads Manager and its leads stay on one campaign in the CRM. campaignName is a different, strictly-matched field: the CRM's own campaign, which drives routing.

The whole object is discarded when metaLeadId is absent. metaLeadId is unique across the CRM: it prevents the metadata being attached twice, but it does NOT prevent a duplicate lead — de-duplicate on your side.

Show child attributes

quiz

object

A dynamic quiz / survey submitted with the lead — for landing pages that ask a set of questions. Unlike every other field in this API, the questions do NOT have to be agreed with Provident in advance: questions and options register themselves the first time they arrive, so a new quiz starts capturing answers with no API change on either side. Answers are searchable in the CRM, shown on the lead, and — for questions Provident maps to a CRM field — used to fill that field on the lead itself.

Show child attributes

integrationRef

string | null

Your handle for the specific automation behind this lead — a Make scenario name, a webhook id, a form build. Free text: stored verbatim, never matched against anything, and never reported in intakeUnresolved.

It identifies an INTEGRATION, not a submission, so keep it stable across every lead that automation sends; a per-lead unique id makes it useless for grouping. Values are only distinguished within one sender, so two partners can both use scenario-1.

Do NOT put your own name here. The submitting OAuth client is recorded automatically from the access token — there is no field for it, because attribution a sender can write is not attribution.

Maximum string length: 128

Example:

"make:meta-leadgen-eu"

Response

Accepted. EITHER a new lead (CreatedLead) OR an enquiry merged into an existing one (MergedLead) — branch on merged before reading any other field. A CreatedLead body carries many further fields that are not part of this contract.

Option 1
Option 2

A newly created lead (merged is false). The response actually carries the whole lead record; only the properties listed here are contractual and safe to depend on.

string<uuid>

UUID of the created lead. Store this against your own submission record.

contactId

string<uuid>

UUID of the contact the lead was attached to (matched or newly created).

intakeUnresolved

object | null

Map of field name → the original value you sent, for every lookup value that could not be matched. null when everything resolved. Quiz answers that could not be read appear namespaced as quiz.<quizKey>.<questionKey> — unlike a failed lookup, the answer IS still stored on the lead, and a Provident admin can map the value once so every future submission of it resolves automatically.

Show child attributes

Example:

{
  "source": "Web-Site",
  "quiz.off-plan-investor-2026.free_budget": "somewhere around a lot"
}

needsIntakeReview

boolean

true when intakeUnresolved is non-empty.

merged

enum<boolean>

Always false here. true means the enquiry was folded into an existing lead — see MergedLead.

Available options:

false

isRepeatLead

boolean

True when this person already had a lead older than the merge window. The lead is routed and worked normally; this is a marker, not a routing instruction.

repeatOfLeadId

string<uuid> | null

The earlier lead's id when isRepeatLead is true, otherwise null.

isAgentEnquiry

boolean

True when the enquiry was recognised as coming from a competing agent rather than a buyer. The lead is still created and worked; the flag keeps it out of lead-volume and cost-per-lead reporting.

agentEnquiryReason

enum<string> | null

Why, when isAgentEnquiry is true; null otherwise.

Available options:

known_agent,

prior_lead,

competitor_domain,

manual,

null

createdAt

string<date-time>

assignedTo

object | null

The agent the lead landed on. NULL means 'not decided yet' — the routing engine runs after this response is sent — NOT 'nobody'. Reliable only when you sent referenceNo/listingId or assignedBy; otherwise use GET /public/leads/{id}/assignment or the lead.assigned webhook.

Show child attributes

Authentication

Lead intake

Reference data

Lead follow-up

Create a CRM lead

Authorizations

Body

Response