Skip to main content
POST

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:
leadEmails
string[]

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

Maximum string length: 255
Example:
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"

buyerType
string | null

LOOKUP. Who the enquirer says they are — a form's "I am an Agent / Investor" choice, for example. Matched against Provident's buyer types (Investor, End User, First Time Buyer, Broker, Flipper, …); Agent is accepted and recorded as Broker. Send the choice as the visitor saw it — an unrecognised value comes back in intakeUnresolved and is mapped on our side. Beats a quiz answer that sets the same field.

Maximum string length: 255
Example:

"Investor"

areaOfInterest
string | null

LOOKUP. Area the customer says they are interested in, matched on location name. Kept for existing integrations — new ones should send location / locationId, which fill the lead's location that assignment routes on.

Example:

"Dubai Marina"

location
string | null

LOOKUP. Where the property is — the lead's location, which is what lead assignment routes on. Matched case-insensitively on the location name from GET /public/locations/search. Used only when locationId is omitted or matches no location, so sending both means a stale id still lands the lead on the right location by name. Anything you send here wins over a location taken from listingId or shortLinkId. Location names are NOT unique: prefer locationId, because a name that matches more than one location is unmatched. An unmatched name comes back in intakeUnresolved.location.

Not the same field as areaOfInterest, which is the area the customer says they want and is kept for existing integrations.

Maximum string length: 255
Example:

"Dubai Marina"

locationId
string | null

LOOKUP. Location id — id from GET /public/locations/search or GET /public/projects/filters. Tried before location; a value that is not a uuid is matched as a name instead of being discarded. A value that matches no location (an unknown or retired id) never fails the request: it comes back in intakeUnresolved.locationId, and location, if you sent it, is then tried by name. That report stands even when the name matched, so a stale id you keep sending stays visible.

Maximum string length: 255
Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

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:
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:
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.

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.

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"

comments
object[]

Comments to write onto the lead's thread, OLDEST FIRST — the first entry in the array is the eldest and appears at the bottom of the CRM timeline. Entries sent without a date, and entries sharing the same timestamp, keep the order you sent them in. Maximum 5 per request: anything past the fifth is SKIPPED and reported back as comments.skipped rather than failing the request, because failing it would throw away a real customer enquiry over a comment. Send a longer conversation as consecutive PUTs, five at a time, oldest batch first. On an update these are ADDED to what the lead already has.

Maximum array length: 5
jobPosition
string | null

Recruitment funnel: the job position the applicant applied for, as your form wrote it. Free text — stored as sent, never matched against a list, never reported in intakeUnresolved. Send it with "funnel": "Recruitment". Longer values are cut at 255 characters.

Maximum string length: 255
Example:

"Property Consultant"

resumeUrl
string | null

Recruitment funnel: a link to the applicant's CV FILE. We download it shortly after responding and keep our own private copy on the lead; your link need only stay reachable for a few minutes.

Must be a public http(s) URL on the default port, without credentials, returning the file itself: PDF, Word (.doc/.docx), RTF, OpenDocument text, PNG or JPEG, at most 10 MB. The type is read from the file's bytes, not your headers. A link that returns a web page fails; Google Drive /file/d/<id>/view and Dropbox ?dl=0 links are converted to direct downloads for you. Up to 5 redirects are followed.

A bad link never fails the request — see resume in the response. A new link replaces the lead's CV.

Maximum string length: 2048
Example:

"https://files.example.com/applications/8812/cv.pdf"

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.

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.

id
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.

Example:
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, or a recent lead in a different funnel. 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.

comments
object | null

What became of the comments[] you sent; null when you sent none.

resume
object | null

What became of the resumeUrl you sent; null when you sent none.