Skip to main content
PATCH
Update a lead (alias of PUT)

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.

Path Parameters

id
string<uuid>
required

Lead id returned by POST /public/leads. A merged id works too — it is the surviving lead.

Body

application/json

Fields to change on an existing lead. Same names, lookups and forgiving matching as CreateLeadRequest; everything is optional, including phone and email — an update carrying nothing but a quiz block is normal. Omit a field and it is left alone. Send an explicit null and the column is cleared. Send a value that matches no CRM record and the column keeps what it had, with the value reported in intakeUnresolved. leadPhones and leadEmails are APPENDED to the lead, never replacing what is there. Quiz answers supersede the previous answers for the same quizKey only. assignedBy, funnel and distributionType are create-only and absent here: an external system does not move a lead between agents, between funnel boards, or onto a different aging clock.

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"

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 (ApartmentsApartment, TownhousesTownhouse), 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"

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"

Response

Applied

id
string<uuid>
updated
boolean

False when the submission changed nothing — every value sent was already the lead's. Not an error.

updatedFields
string[]

Lead columns this submission actually changed, by CRM name (closingAreaId is what areaOfInterest fills). leadPhones/leadEmails appear when a new one was added, quizAnswers when answers were written, metaFacebook when the Meta block was stored.

Example:
intakeUnresolved
object | null

Values sent on THIS submission that matched no CRM record, keyed by the field you sent. Merged with whatever was already unresolved on the lead — an update never clears a flag it did not answer.

needsIntakeReview
boolean

True when intakeUnresolved is non-empty.

rerouted
boolean

True when the new details sent the lead back through the assignment engine. Only ever true for a lead nobody held — an update never moves a lead away from the agent working it. Routing is asynchronous: poll GET /public/leads/{id}/assignment for the outcome.

assignedTo
object | null

The agent holding the lead as this response was written, or null.