Update a lead (alias of PUT)

curl --request PATCH \
  --url https://devapi.prov.ae/v2/public/leads/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "budgetMin": "1200000",
  "budgetMax": "1800000",
  "areaOfInterest": "Dubai Marina",
  "quiz": {
    "quizKey": "buyer_qualification_v2",
    "quizName": "Buyer qualification",
    "locale": "en",
    "answers": [
      {
        "questionKey": "timeframe",
        "label": "When are you looking to buy?",
        "optionKeys": [
          "3_6_months"
        ]
      },
      {
        "questionKey": "purpose",
        "label": "Purpose",
        "value": "Investment"
      }
    ]
  }
}
'

import requests

url = "https://devapi.prov.ae/v2/public/leads/{id}"

payload = {
    "budgetMin": "1200000",
    "budgetMax": "1800000",
    "areaOfInterest": "Dubai Marina",
    "quiz": {
        "quizKey": "buyer_qualification_v2",
        "quizName": "Buyer qualification",
        "locale": "en",
        "answers": [
            {
                "questionKey": "timeframe",
                "label": "When are you looking to buy?",
                "optionKeys": ["3_6_months"]
            },
            {
                "questionKey": "purpose",
                "label": "Purpose",
                "value": "Investment"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    budgetMin: '1200000',
    budgetMax: '1800000',
    areaOfInterest: 'Dubai Marina',
    quiz: {
      quizKey: 'buyer_qualification_v2',
      quizName: 'Buyer qualification',
      locale: 'en',
      answers: [
        {
          questionKey: 'timeframe',
          label: 'When are you looking to buy?',
          optionKeys: ['3_6_months']
        },
        {questionKey: 'purpose', label: 'Purpose', value: 'Investment'}
      ]
    }
  })
};

fetch('https://devapi.prov.ae/v2/public/leads/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://devapi.prov.ae/v2/public/leads/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'budgetMin' => '1200000',
    'budgetMax' => '1800000',
    'areaOfInterest' => 'Dubai Marina',
    'quiz' => [
        'quizKey' => 'buyer_qualification_v2',
        'quizName' => 'Buyer qualification',
        'locale' => 'en',
        'answers' => [
                [
                                'questionKey' => 'timeframe',
                                'label' => 'When are you looking to buy?',
                                'optionKeys' => [
                                                                '3_6_months'
                                ]
                ],
                [
                                'questionKey' => 'purpose',
                                'label' => 'Purpose',
                                'value' => 'Investment'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://devapi.prov.ae/v2/public/leads/{id}"

	payload := strings.NewReader("{\n  \"budgetMin\": \"1200000\",\n  \"budgetMax\": \"1800000\",\n  \"areaOfInterest\": \"Dubai Marina\",\n  \"quiz\": {\n    \"quizKey\": \"buyer_qualification_v2\",\n    \"quizName\": \"Buyer qualification\",\n    \"locale\": \"en\",\n    \"answers\": [\n      {\n        \"questionKey\": \"timeframe\",\n        \"label\": \"When are you looking to buy?\",\n        \"optionKeys\": [\n          \"3_6_months\"\n        ]\n      },\n      {\n        \"questionKey\": \"purpose\",\n        \"label\": \"Purpose\",\n        \"value\": \"Investment\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://devapi.prov.ae/v2/public/leads/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"budgetMin\": \"1200000\",\n  \"budgetMax\": \"1800000\",\n  \"areaOfInterest\": \"Dubai Marina\",\n  \"quiz\": {\n    \"quizKey\": \"buyer_qualification_v2\",\n    \"quizName\": \"Buyer qualification\",\n    \"locale\": \"en\",\n    \"answers\": [\n      {\n        \"questionKey\": \"timeframe\",\n        \"label\": \"When are you looking to buy?\",\n        \"optionKeys\": [\n          \"3_6_months\"\n        ]\n      },\n      {\n        \"questionKey\": \"purpose\",\n        \"label\": \"Purpose\",\n        \"value\": \"Investment\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://devapi.prov.ae/v2/public/leads/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"budgetMin\": \"1200000\",\n  \"budgetMax\": \"1800000\",\n  \"areaOfInterest\": \"Dubai Marina\",\n  \"quiz\": {\n    \"quizKey\": \"buyer_qualification_v2\",\n    \"quizName\": \"Buyer qualification\",\n    \"locale\": \"en\",\n    \"answers\": [\n      {\n        \"questionKey\": \"timeframe\",\n        \"label\": \"When are you looking to buy?\",\n        \"optionKeys\": [\n          \"3_6_months\"\n        ]\n      },\n      {\n        \"questionKey\": \"purpose\",\n        \"label\": \"Purpose\",\n        \"value\": \"Investment\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "updated": true,
  "updatedFields": [
    "budgetMin",
    "budgetMax",
    "closingAreaId",
    "quizAnswers",
    "comments"
  ],
  "intakeUnresolved": {},
  "needsIntakeReview": true,
  "rerouted": true,
  "assignedTo": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "slug": "sarah-ahmed",
    "name": "Sarah Ahmed",
    "email": "<string>",
    "phone": "<string>",
    "whatsappPhone": "<string>",
    "active": true
  },
  "comments": {
    "added": 3,
    "skipped": 0
  },
  "resume": {
    "status": "pending",
    "error": null
  }
}

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "<string>",
  "errors": [
    "<string>"
  ],
  "details": {},
  "path": "/v2/public/leads",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 401,
  "code": "OAUTH_TOKEN_EXPIRED",
  "message": "OAuth access token expired",
  "path": "/v2/public/projects/filters",
  "timestamp": "2026-07-27T06:31:04.512Z"
}

{
  "statusCode": 403,
  "code": "OAUTH_CLIENT_GRANT_MISSING",
  "message": "This client is not allowed to use this endpoint. It needs the \"client:dncr:check:create\" grant.",
  "details": {
    "requiredGrant": "client:dncr:check:create"
  },
  "path": "/v2/public/dncr/check",
  "timestamp": "2026-10-06T12:00:00.000Z"
}

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "<string>",
  "errors": [
    "<string>"
  ],
  "details": {},
  "path": "/v2/public/leads",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too Many Requests",
  "path": "/v2/public/leads",
  "timestamp": "2026-07-27T06:31:04.512Z"
}

Lead follow-up

Update a lead (alias of PUT)

For the case where you do not have the whole enquiry at once: the name, email and phone go in with POST /public/leads, and the quiz answers, budget and area follow minutes or hours later.

Send only what changed. An omitted field is left alone, an explicit null clears the column, and a value that matches no CRM record leaves the column as it was rather than blanking it — a typo never erases a good value. A field you do send wins over what the lead had, including a value an agent typed, so only send fields you are authoritative about.

leadPhones and leadEmails are APPENDED, never replaced, so re-sending the one number you know is free. Quiz answers supersede the previous answers for the same quizKey, which makes a retry idempotent.

The lead’s workflow is not writable here at all: stage, status, assigned agent, funnel board and the aging clock stay Provident’s, whatever is sent.

New details DO send a lead nobody holds back through the assignment engine (see rerouted); a lead an agent already holds is never taken off them. Every update that changes something also posts a note on the lead’s timeline naming your integration and what changed.

PATCH is accepted as an alias for the same operation — the semantics are PATCH’s either way. This is not a way around the merge window: if the customer enquires again, POST it.

PATCH

public

leads

{id}

Update a lead (alias of PUT)

curl --request PATCH \
  --url https://devapi.prov.ae/v2/public/leads/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "budgetMin": "1200000",
  "budgetMax": "1800000",
  "areaOfInterest": "Dubai Marina",
  "quiz": {
    "quizKey": "buyer_qualification_v2",
    "quizName": "Buyer qualification",
    "locale": "en",
    "answers": [
      {
        "questionKey": "timeframe",
        "label": "When are you looking to buy?",
        "optionKeys": [
          "3_6_months"
        ]
      },
      {
        "questionKey": "purpose",
        "label": "Purpose",
        "value": "Investment"
      }
    ]
  }
}
'

import requests

url = "https://devapi.prov.ae/v2/public/leads/{id}"

payload = {
    "budgetMin": "1200000",
    "budgetMax": "1800000",
    "areaOfInterest": "Dubai Marina",
    "quiz": {
        "quizKey": "buyer_qualification_v2",
        "quizName": "Buyer qualification",
        "locale": "en",
        "answers": [
            {
                "questionKey": "timeframe",
                "label": "When are you looking to buy?",
                "optionKeys": ["3_6_months"]
            },
            {
                "questionKey": "purpose",
                "label": "Purpose",
                "value": "Investment"
            }
        ]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    budgetMin: '1200000',
    budgetMax: '1800000',
    areaOfInterest: 'Dubai Marina',
    quiz: {
      quizKey: 'buyer_qualification_v2',
      quizName: 'Buyer qualification',
      locale: 'en',
      answers: [
        {
          questionKey: 'timeframe',
          label: 'When are you looking to buy?',
          optionKeys: ['3_6_months']
        },
        {questionKey: 'purpose', label: 'Purpose', value: 'Investment'}
      ]
    }
  })
};

fetch('https://devapi.prov.ae/v2/public/leads/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://devapi.prov.ae/v2/public/leads/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'budgetMin' => '1200000',
    'budgetMax' => '1800000',
    'areaOfInterest' => 'Dubai Marina',
    'quiz' => [
        'quizKey' => 'buyer_qualification_v2',
        'quizName' => 'Buyer qualification',
        'locale' => 'en',
        'answers' => [
                [
                                'questionKey' => 'timeframe',
                                'label' => 'When are you looking to buy?',
                                'optionKeys' => [
                                                                '3_6_months'
                                ]
                ],
                [
                                'questionKey' => 'purpose',
                                'label' => 'Purpose',
                                'value' => 'Investment'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://devapi.prov.ae/v2/public/leads/{id}"

	payload := strings.NewReader("{\n  \"budgetMin\": \"1200000\",\n  \"budgetMax\": \"1800000\",\n  \"areaOfInterest\": \"Dubai Marina\",\n  \"quiz\": {\n    \"quizKey\": \"buyer_qualification_v2\",\n    \"quizName\": \"Buyer qualification\",\n    \"locale\": \"en\",\n    \"answers\": [\n      {\n        \"questionKey\": \"timeframe\",\n        \"label\": \"When are you looking to buy?\",\n        \"optionKeys\": [\n          \"3_6_months\"\n        ]\n      },\n      {\n        \"questionKey\": \"purpose\",\n        \"label\": \"Purpose\",\n        \"value\": \"Investment\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://devapi.prov.ae/v2/public/leads/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"budgetMin\": \"1200000\",\n  \"budgetMax\": \"1800000\",\n  \"areaOfInterest\": \"Dubai Marina\",\n  \"quiz\": {\n    \"quizKey\": \"buyer_qualification_v2\",\n    \"quizName\": \"Buyer qualification\",\n    \"locale\": \"en\",\n    \"answers\": [\n      {\n        \"questionKey\": \"timeframe\",\n        \"label\": \"When are you looking to buy?\",\n        \"optionKeys\": [\n          \"3_6_months\"\n        ]\n      },\n      {\n        \"questionKey\": \"purpose\",\n        \"label\": \"Purpose\",\n        \"value\": \"Investment\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://devapi.prov.ae/v2/public/leads/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"budgetMin\": \"1200000\",\n  \"budgetMax\": \"1800000\",\n  \"areaOfInterest\": \"Dubai Marina\",\n  \"quiz\": {\n    \"quizKey\": \"buyer_qualification_v2\",\n    \"quizName\": \"Buyer qualification\",\n    \"locale\": \"en\",\n    \"answers\": [\n      {\n        \"questionKey\": \"timeframe\",\n        \"label\": \"When are you looking to buy?\",\n        \"optionKeys\": [\n          \"3_6_months\"\n        ]\n      },\n      {\n        \"questionKey\": \"purpose\",\n        \"label\": \"Purpose\",\n        \"value\": \"Investment\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "updated": true,
  "updatedFields": [
    "budgetMin",
    "budgetMax",
    "closingAreaId",
    "quizAnswers",
    "comments"
  ],
  "intakeUnresolved": {},
  "needsIntakeReview": true,
  "rerouted": true,
  "assignedTo": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "slug": "sarah-ahmed",
    "name": "Sarah Ahmed",
    "email": "<string>",
    "phone": "<string>",
    "whatsappPhone": "<string>",
    "active": true
  },
  "comments": {
    "added": 3,
    "skipped": 0
  },
  "resume": {
    "status": "pending",
    "error": null
  }
}

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "<string>",
  "errors": [
    "<string>"
  ],
  "details": {},
  "path": "/v2/public/leads",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 401,
  "code": "OAUTH_TOKEN_EXPIRED",
  "message": "OAuth access token expired",
  "path": "/v2/public/projects/filters",
  "timestamp": "2026-07-27T06:31:04.512Z"
}

{
  "statusCode": 403,
  "code": "OAUTH_CLIENT_GRANT_MISSING",
  "message": "This client is not allowed to use this endpoint. It needs the \"client:dncr:check:create\" grant.",
  "details": {
    "requiredGrant": "client:dncr:check:create"
  },
  "path": "/v2/public/dncr/check",
  "timestamp": "2026-10-06T12:00:00.000Z"
}

{
  "statusCode": 400,
  "code": "BAD_REQUEST",
  "message": "<string>",
  "errors": [
    "<string>"
  ],
  "details": {},
  "path": "/v2/public/leads",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too Many Requests",
  "path": "/v2/public/leads",
  "timestamp": "2026-07-27T06:31:04.512Z"
}

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

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:

["+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"

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:

["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"

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"

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

Show child attributes

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. null clears it.

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. null removes the CV.

Maximum string length: 2048

Example:

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

Response

Applied

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 (locationId is what location/locationId fill, 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, comments when at least one comment was posted.

Example:

[
  "budgetMin",
  "budgetMax",
  "closingAreaId",
  "quizAnswers",
  "comments"
]

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.

Show child attributes

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.

Show child attributes

comments

object | null

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

Show child attributes

resume

object | null

What became of the resumeUrl you sent; null when you sent none. resume also appears in updatedFields whenever you sent one.

Show child attributes

Authentication

Lead intake

Reference data

Lead follow-up

Do Not Call Registry

Phone screening

WhatsApp check

Update a lead (alias of PUT)

Authorizations

Path Parameters

Body

Response