> ## Documentation Index > Fetch the complete documentation index at: https://docs.prov.ae/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.json patch /public/leads/{id} openapi: 3.0.3 info: title: Provident — Lead Intake API version: 1.4.0 description: >- Server-to-server API for pushing leads into the Provident CRM. Core endpoints: 1. `POST /oauth2/token` — exchange client credentials for a bearer token. 2. `POST /public/leads` — create a CRM lead. 3. `PUT /public/leads/{id}` — add details you did not have when you created it (quiz answers the customer finished afterwards, a budget, an area). Send only what changed; phones and emails are appended, never replaced, and the lead's stage, status, owner and funnel are not writable. Optional read-only reference data, using the same token: locations, developers, projects and project statuses. Use them to send values that match ours, or to show project content on your own pages. They share the lead endpoint's rate limit, so cache them. Authentication is OAuth 2.0 Client Credentials; there is no user login. Note that the `/v2` prefix is part of the server URL and is mandatory. The intake is deliberately forgiving: name-based lookup fields that cannot be matched do NOT fail the request — the lead is still created and the unmatched values are returned in `intakeUnresolved`. The endpoint is not idempotent at the transport level, but intake hygiene runs before the lead is created: a second enquiry from the same phone/email within the merge window (~24h) is MERGED into the existing lead and returns a different, much shorter 201 body — `{ id, merged: true, matchedOn }` — with no contactId, intakeUnresolved, needsIntakeReview or createdAt. Always branch on `merged` before reading anything else. Enquiries from property-portal sources (Property Finder, Bayut, Dubizzle) are exempt and never merge. Retry only on network timeouts, 429 and 5xx. contact: name: Provident API support servers: - url: https://devapi.prov.ae/v2 description: Staging / development — build and test here - url: https://prodapi.prov.ae/v2 description: Production — live leads security: [] tags: - name: Authentication description: OAuth 2.0 client-credentials token issuance - name: Lead intake description: Public lead creation - name: Reference data description: Read-only lookups — locations, developers, projects, project statuses - name: Lead follow-up description: >- Reading back who a lead was assigned to, and recording the agent response time - name: Webhooks description: >- Calls Provident makes to YOUR server. Documented here for the payload shape; these are not endpoints you call. paths: /public/leads/{id}: patch: tags: - Lead follow-up summary: Update a lead (alias of PUT) description: >- 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. parameters: - name: id in: path required: true schema: type: string format: uuid description: >- Lead id returned by POST /public/leads. A merged id works too — it is the surviving lead. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateLeadRequest' example: 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 responses: '200': description: Applied content: application/json: schema: $ref: '#/components/schemas/UpdatedLead' '400': description: Body was not valid JSON, or the id is not a valid UUID content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': $ref: '#/components/responses/Unauthorized' '404': description: No such lead, or it has been deleted content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] components: schemas: UpdateLeadRequest: type: object description: >- 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. properties: leadPhones: type: array items: type: string maxLength: 64 description: >- Phone numbers. Used FIRST to match an existing contact. Use E.164 format for reliable matching. Required unless `leadEmails` is supplied. example: - '+971501234567' leadEmails: type: array items: type: string maxLength: 255 description: >- Email addresses. Used to match an existing contact when no phone matches. Required unless `leadPhones` is supplied. example: - john.doe@example.com leadFirstName: type: string maxLength: 255 nullable: true example: John leadMiddleName: type: string maxLength: 255 nullable: true example: Ahmad leadSecondName: type: string maxLength: 255 nullable: true description: Second given name — used when no middle name is supplied. example: A. leadLastName: type: string maxLength: 255 nullable: true example: Doe leadCompanyName: type: string maxLength: 255 nullable: true description: Company name for corporate enquiries. example: Acme Real Estate leadType: type: string maxLength: 255 description: >- 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`. example: Primary Buyer priority: type: string maxLength: 64 nullable: true description: Free text priority indicator. example: High marketSegment: type: string maxLength: 255 description: LOOKUP. Marketing's segmentation of the lead. enum: - Standard - Luxury - Super Luxury example: Luxury agentCategory: type: string maxLength: 255 description: LOOKUP. Marketing's grading of the lead. enum: - A - B - C - D example: A areaOfInterest: type: string nullable: true description: LOOKUP. Location the lead is interested in. example: Dubai Marina propertyTypeInterest: type: string maxLength: 255 nullable: true description: >- 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. example: Apartment budgetMin: type: string nullable: true description: Minimum budget. Numeric string; a JSON number is also accepted. example: '1000000' budgetMax: type: string nullable: true description: Maximum budget. Numeric string; a JSON number is also accepted. example: '2500000' currency: type: string maxLength: 3 description: LOOKUP. ISO 4217 currency code for the budget values. example: AED initialInquiry: type: string nullable: true description: Free-text message or callback reason from the form. example: Looking for a 2BR with sea view, ready to move in Q4. languages: type: array items: type: string maxLength: 255 description: >- LOOKUP. Languages the lead speaks, by code or name. Unrecognised entries are ignored. example: - ar - English listingId: type: string format: uuid description: >- 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: type: string maxLength: 128 description: >- 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. example: PR-123456 source: type: string maxLength: 255 description: >- LOOKUP. Lead source. Send this — an unrecognised or omitted source leaves the lead with no source attribution. example: Website subSource: type: array items: type: string maxLength: 255 description: >- LOOKUP. Sub-sources. Only those linked to the resolved `source` are kept; ignored entirely when `source` did not resolve. example: - Callback Form - Team Page marketingType: type: string maxLength: 255 description: LOOKUP. Marketing type, e.g. Organic or Paid. example: Organic eventType: type: string maxLength: 255 description: >- LOOKUP. What the user did — e.g. Submit Form, Call, Whatsapp Click, DM, Webpush, Gamification. example: Submit Form campaignName: type: string maxLength: 255 description: LOOKUP. CRM campaign name. example: Spring 2026 Landing Page advertisingCampaign: type: string maxLength: 255 description: >- 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. example: Google Ads — Q3 developerName: type: string maxLength: 255 description: >- LOOKUP. Developer the enquiry is about, matched on name or slug — `Sobha Realty` or `sobha-realty`. Values come from `GET /public/developers`. example: Sobha Realty developerId: type: string description: >- 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: type: string maxLength: 255 description: >- 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. example: provident.ae pageUrl: type: string nullable: true description: Full URL of the page the submission originated from. example: https://prov.ae/en/dubai-marina?utm_source=google pathLocale: type: string maxLength: 32 nullable: true description: Locale segment of the URL path, e.g. `en`. example: en gclid: type: string maxLength: 512 nullable: true description: Google Ads click id. fbclid: type: string maxLength: 512 nullable: true description: Facebook click id. utmSource: type: string maxLength: 512 nullable: true example: google utmMedium: type: string maxLength: 512 nullable: true example: cpc utmCampaign: type: string maxLength: 512 nullable: true example: spring-2026 utmTerm: type: string maxLength: 512 nullable: true example: dubai marina apartments utmContent: type: string maxLength: 512 nullable: true example: hero-cta formName: type: string maxLength: 255 nullable: true description: >- Name of the web form the visitor submitted. Falls back to `metaFacebook.formName` (truncated to 255) when omitted. example: contact-popup-form adsetName: type: string maxLength: 255 nullable: true description: >- 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. example: test ww referrer: type: string nullable: true description: Referring URL the visitor arrived from. example: https://sobha-city.provident.ae/?utm_source=Google+Ads ipAddress: type: string maxLength: 64 nullable: true description: Submitter IP. IPv4, IPv6 and proxy chains all fit. example: 217.165.113.16 userAgent: type: string nullable: true description: Browser user-agent string captured at submission. example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 submittedAt: type: string format: date-time nullable: true description: >- 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: type: string maxLength: 255 description: >- 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`. example: AE metaFacebook: $ref: '#/components/schemas/MetaFacebookPayload' quiz: $ref: '#/components/schemas/QuizSubmission' integrationRef: type: string maxLength: 128 nullable: true description: >- 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. example: make:meta-leadgen-eu additionalProperties: true UpdatedLead: type: object properties: id: type: string format: uuid updated: type: boolean description: >- False when the submission changed nothing — every value sent was already the lead's. Not an error. updatedFields: type: array items: type: string description: >- 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: - budgetMin - budgetMax - closingAreaId - quizAnswers intakeUnresolved: type: object nullable: true additionalProperties: type: string description: >- 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: type: boolean description: True when intakeUnresolved is non-empty. rerouted: type: boolean description: >- 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: allOf: - $ref: '#/components/schemas/Agent' nullable: true description: The agent holding the lead as this response was written, or null. ApiError: type: object description: Common error envelope used by every endpoint. properties: statusCode: type: integer example: 400 code: type: string description: >- Stable machine-readable error code — branch on this, not on `message`. example: BAD_REQUEST message: type: string description: Human-readable description. errors: type: array items: type: string description: 'Present on 422 only: one entry per field that failed validation.' details: type: object additionalProperties: true description: Optional structured extras attached by the failing handler. path: type: string example: /v2/public/leads timestamp: type: string format: date-time MetaFacebookPayload: type: object description: >- 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. properties: metaLeadId: type: string maxLength: 64 description: Meta-issued lead id. Required for this block to be stored. example: '7636865386872307975' metaCreatedAt: type: string format: date-time description: Submission time reported by Meta (ISO-8601). example: '2026-05-06T19:38:09.000Z' platform: type: string maxLength: 32 description: >- Source platform. The short forms `fb` and `ig` are accepted and normalised to `facebook` / `instagram`, so a sender forwarding Meta verbatim needs no translation; anything else is stored lowercased rather than rejected. enum: - facebook - instagram - tiktok - fb - ig example: facebook adId: type: string maxLength: 64 adName: type: string maxLength: 512 example: Marina Launch — Video adType: type: string maxLength: 64 example: Video adgroupId: type: string maxLength: 64 adgroupName: type: string maxLength: 255 example: TARGETED description: >- Ad set / ad group name. Also fills the lead's `adsetName` when you send no top-level one. metaCampaignId: type: string maxLength: 64 description: >- Meta's own campaign id — NOT the CRM campaign (use `campaignName` for that). metaCampaignName: type: string maxLength: 512 example: Marina Q2 formId: type: string maxLength: 64 formName: type: string maxLength: 512 example: Marina Callback description: >- Meta lead-form name. Also fills the lead's `formName` when you send no top-level one. adAccountId: type: string maxLength: 64 example: act_123456789 businessAccountId: type: string maxLength: 64 sourceAction: type: string maxLength: 64 example: Form finalPageName: type: string maxLength: 255 example: Thank You description: The Facebook/Instagram page the ad ran under. Copied onto the lead. customFields: type: object additionalProperties: true description: >- Per-form custom question/answer pairs and any other ad-platform-only fields. Keys are preserved verbatim (non-ASCII safe). example: هل ترغب في حضور هذا المعرض الحصري؟: نعم Preferred call time: Evening QuizSubmission: type: object description: >- 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. properties: quizKey: type: string maxLength: 128 description: >- Stable identifier for the quiz. REQUIRED — without it the whole `quiz` object is ignored. Keys are scoped to the quiz, so `budget` in quiz A and `budget` in quiz B are independent; you do not need globally unique question keys. example: off-plan-investor-2026 quizName: type: string maxLength: 255 description: Display name. Used the first time this `quizKey` is seen. example: Off-plan investor quiz locale: type: string maxLength: 16 description: >- Language the quiz was answered in. Labels are stored per locale so the CRM shows what the visitor actually saw. example: ar version: type: string maxLength: 32 description: Your version identifier for the quiz, recorded on each answer. example: '3' answers: type: array items: $ref: '#/components/schemas/QuizAnswer' maxItems: 60 description: >- The answers, in the order the questions were asked. Up to 60 per submission register new questions; anything beyond is still recorded and flagged for review, but does not extend the catalogue. A quiz is capped at 100 questions and a question at 200 options. additionalProperties: false Agent: type: object description: >- An agent, as returned anywhere in this API. Work contacts only — personal numbers are never published. required: - id - slug - name - email - phone - whatsappPhone - active properties: id: type: string format: uuid description: >- Portal user id. The stable, immutable identifier for an agent — key your records on this. slug: type: string nullable: true description: >- Website profile segment (/team//), or null if not published. Human-readable but admin-editable; `id` is not. example: sarah-ahmed name: type: string nullable: true description: Display name. Safe to say to a customer. example: Sarah Ahmed email: type: string nullable: true description: Work email. phone: type: string nullable: true description: Work phone. whatsappPhone: type: string nullable: true description: >- The number to open a WhatsApp chat on. Read this field rather than reusing `phone` — they differ for some agents. active: type: boolean description: False for a deactivated account. Do not route work to them. QuizAnswer: type: object description: >- One answer to one quiz question. `questionKey` (and `optionKey` for dropdowns) are the contract: they are the only language-independent identity an answer has. Labels are display text and change with language and copy edits, so they are never used for matching when a key is present. properties: questionKey: type: string maxLength: 128 description: >- Stable machine key for the question, unique within the quiz. Must be the SAME across languages and stable over time — do not regenerate it when you edit the wording. Without it the answer is keyed off a hash of its label and will not merge with the same question in another language. example: budget questionLabel: type: string maxLength: 512 description: The question as shown to the visitor, in the quiz locale. example: ما هي ميزانيتك؟ optionKey: description: >- Stable machine key of the chosen option, for select questions. Send an ARRAY for multi-select — each option becomes its own answer record. oneOf: - type: string maxLength: 128 - type: array items: type: string maxLength: 128 example: 2m-5m answerLabel: description: >- The answer as shown to the visitor. For a select answer this is the option label; for free text it is the answer itself. Array form pairs positionally with an array `optionKey`. oneOf: - type: string maxLength: 512 - type: array items: type: string maxLength: 512 example: ٢-٥ مليون value: description: >- Machine value when you have one — a number, boolean, or ISO-8601 date string. TRUSTED OVER THE LABEL: sending 2000000 removes any dependence on our parsing of "٢-٥ مليون". Free-text numbers are parsed best-effort instead ("2 million", "2,000,000", "AED 2M", "٢ مليون" all resolve to 2000000); an unparseable value is kept verbatim and flagged for review rather than dropped. oneOf: - type: string - type: number - type: boolean example: 2000000 currency: type: string maxLength: 3 description: >- ISO 4217 currency for a monetary answer, when the value does not imply it. example: AED additionalProperties: false responses: Unauthorized: description: Missing, invalid, revoked or expired bearer token. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 401 code: OAUTH_TOKEN_EXPIRED message: OAuth access token expired path: /v2/public/projects/filters timestamp: '2026-07-27T06:31:04.512Z' RateLimited: description: >- Request quota for this client exceeded. Wait `Retry-After` seconds, then resume. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 429 code: RATE_LIMITED message: Too Many Requests path: /v2/public/leads timestamp: '2026-07-27T06:31:04.512Z' headers: XRateLimitLimit: description: Requests allowed in the current window. schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window. schema: type: integer XRateLimitReset: description: Seconds until the counter resets (end of the UTC day). schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Opaque description: >- The `access_token` returned by `POST /oauth2/token`, sent as `Authorization: Bearer `. It is an opaque string, not a JWT. ````