Update a lead Run in API Explorer
A status change sets status_changed_at to now. Changing or removing the source without a sub-source clears the sub-source.
Body
-
Title of the lead.
Maximum length is
25. -
First name of the lead.
Maximum length is
255. -
Last name of the lead.
Maximum length is
255. -
Entity name for non-individual leads.
Maximum length is
255. -
Client type of the lead. One of individual, joint, trust and business.
Value Description individual Individual joint Joint trust Trust business Business Values are
individual,joint,trust, orbusiness. -
Date of birth. The lead must be at least 18 years old.
-
Status of the lead. One of new, contacted, pending_call_back, awaiting_client_action, meeting_booked and uncontactable. A change updates status_changed_at.
Value Description new New contacted Contacted pending_call_back Pending Call Back awaiting_client_action Awaiting Client Action meeting_booked Meeting Booked uncontactable Uncontactable Values are
new,contacted,pending_call_back,awaiting_client_action,meeting_booked, oruncontactable. -
Whether the lead is vulnerable. One of yes, no and possibly.
Value Description yes Yes no No possibly Possibly Values are
yes,no, orpossibly. -
UUID of a lead source in the firm, or null to remove the source. An archived source is only accepted when it is already the lead's source. Changing or removing the source without sending sub_source_uuid clears the sub-source.
-
UUID of a sub-source belonging to the lead's source (or to source_uuid when both are sent). An archived sub-source is only accepted when it is already the lead's sub-source.
-
Campaign the lead came from.
Maximum length is
255. -
UUIDs of lead interests in the firm; replaces the current set. An archived interest is only accepted when it is already attached.
-
Custom field values keyed by the custom field reference. Only references configured for leads are accepted. References left out keep their current value.
Additional properties are allowed.
curl \
--request PUT 'https://api.plannrcrm.com/api/v1/leads/53f22fe4-3731-4cdc-aa12-e65bd0b15e52' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
--data '{
"title": "mr",
"first_name": "Sam",
"last_name": "Patel",
"entity_name": "Acme Holdings",
"client_type": "individual",
"date_of_birth": "1985-04-12",
"status": "new",
"is_vulnerable": "yes",
"source_uuid": "78fdcdb5-5159-4f43-9290-3664a1148b38",
"sub_source_uuid": "821d5406-7c6c-4d36-9edf-e50d2fd795fd",
"campaign": "Spring campaign",
"lead_interest_uuids": [
"a78fb443-7532-4ca5-812f-8d86a9c6b949",
"97176409-13ad-4f04-9983-566383a248f4",
"4ff4cce8-5724-4b4b-a2de-c8496300d3ea"
],
"custom_fields": {
"enquiry_channel": "Phone"
}
}'
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}
# Payload
{
"title": "mr",
"first_name": "Sam",
"last_name": "Patel",
"entity_name": "Acme Holdings",
"client_type": "individual",
"date_of_birth": "1985-04-12",
"status": "new",
"is_vulnerable": "yes",
"source_uuid": "78fdcdb5-5159-4f43-9290-3664a1148b38",
"sub_source_uuid": "821d5406-7c6c-4d36-9edf-e50d2fd795fd",
"campaign": "Spring campaign",
"lead_interest_uuids": [
"a78fb443-7532-4ca5-812f-8d86a9c6b949",
"97176409-13ad-4f04-9983-566383a248f4",
"4ff4cce8-5724-4b4b-a2de-c8496300d3ea"
],
"custom_fields": {
"enquiry_channel": "Phone"
}
}
{
"uuid": "0a4924fe-a6fc-4638-9b53-8e6c515bd913",
"title": "mr",
"first_name": "Sam",
"last_name": "Patel",
"name": "Sam Patel",
"client_type": "individual",
"date_of_birth": "1985-04-12",
"status": "new",
"status_changed_at": "2026-11-18T20:11:43+00:00",
"is_archived": false,
"is_disqualified": false,
"is_pending_disqualified": false,
"is_promoted": false,
"can_promote": true,
"can_update": true,
"can_archive": true,
"can_disqualify": "no",
"can_assign": false,
"can_update_introducer": false,
"can_view_promoted": false,
"source": {
"uuid": "05879ccb-e03f-4f4b-bc34-f0395a21dd32",
"name": "Website",
"description": "Enquiries via the contact page",
"position": 1,
"archived": false,
"sub_sources": {
"uuid": "2e77cfbb-3318-4892-9d33-c9540ece3315",
"name": "Google",
"description": "Paid search on Google",
"position": 1,
"archived": false,
"created_at": "2026-11-18T20:11:50+00:00",
"updated_at": "2026-11-18T20:11:50+00:00"
},
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00"
},
"sub_source": {
"uuid": "e115585a-0df7-41bd-8ecd-52ab4dee0410",
"name": "Google",
"description": "Paid search on Google",
"position": 1,
"archived": false,
"lead_source": {
"uuid": "6cbe8899-5b2c-45f2-9ec7-0da21fa9ce4a",
"name": "Website",
"description": "Enquiries via the contact page",
"position": 1,
"archived": false,
"created_at": "2026-11-18T20:11:50+00:00",
"updated_at": "2026-11-18T20:11:50+00:00"
},
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00"
},
"assigned_account": {
"uuid": "8dd966ef-7b4d-4374-9b2c-6d9394a737d5",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"introduced_by": {
"uuid": "4ec3800e-bd94-49aa-a985-c2e18a0ed3e4",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"created_by": {
"uuid": "de7a2120-5483-48ce-b965-32ff71090107",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"archived_by": {
"uuid": "2ca9a597-35e3-48ee-97d4-523262f58a5e",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"disqualified_by": {
"uuid": "544a063b-5e01-4d47-90c8-036e0250b8ad",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"promoted_by": {
"uuid": "b9b06239-984d-4097-895d-a29d1d81c7b2",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"client_account": {
"uuid": "80784471-f528-463b-ad71-96bb7f5704b8",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
"external_references": {
"uuid": "4bcc9b2d-d5f4-4ea4-9e39-edbdbc538591",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"third_party": "nucleus",
"reference": "AB123456"
}
},
"primary_email": {
"uuid": "90dbff69-4391-4f39-9d2f-7b3bc557f4ce",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "phone_number",
"name": "Work number",
"value": "+443330903630",
"phone_number_meta": {
"country": "GB",
"formatted": "0333 090 3630"
},
"accounts": {
"uuid": "f08f3e8d-23bf-4d4b-b848-af98efb282eb",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
"first_contact_date": "2026-11-18T20:11:49+00:00",
"next_review_date": "2026-11-18T20:11:49+00:00",
"previous_review_date": "2026-11-18T20:11:49+00:00",
"anniversary_review_date": "2026-11-18T20:11:49+00:00",
"terms_of_business_at": "2026-11-18T20:11:49+00:00",
"client_agreement_at": "2026-11-18T20:11:49+00:00",
"with_login": true,
"has_joint_account": true,
"can_be_deleted": "false",
"ownership_percentage": 100.0,
"inactive_at": "2026-11-18",
"last_interaction_at": "2026-11-18 20:11:49",
"referral_code": "ABC12345",
"is_out_of_office": true,
"out_of_office_from": "2026-11-18T20:11:49+00:00",
"out_of_office_until": "2026-11-18T20:11:49+00:00",
"out_of_office_message": "I am away this week. For urgent matters please contact the office.",
"is_pending_fact_find_account": false,
"permissions": {
"firm:read": [
"firm"
],
"network:read": [
"network:uuid"
]
},
"managed_by_head_office": false
}
},
"primary_phone_number": {
"uuid": "f8f33b0d-3786-4540-bdaf-9ed362a79313",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "phone_number",
"name": "Work number",
"value": "+443330903630",
"phone_number_meta": {
"country": "GB",
"formatted": "0333 090 3630"
},
"accounts": {
"uuid": "f08f3e8d-23bf-4d4b-b848-af98efb282eb",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
"first_contact_date": "2026-11-18T20:11:49+00:00",
"next_review_date": "2026-11-18T20:11:49+00:00",
"previous_review_date": "2026-11-18T20:11:49+00:00",
"anniversary_review_date": "2026-11-18T20:11:49+00:00",
"terms_of_business_at": "2026-11-18T20:11:49+00:00",
"client_agreement_at": "2026-11-18T20:11:49+00:00",
"with_login": true,
"has_joint_account": true,
"can_be_deleted": "false",
"ownership_percentage": 100.0,
"inactive_at": "2026-11-18",
"last_interaction_at": "2026-11-18 20:11:49",
"referral_code": "ABC12345",
"is_out_of_office": true,
"out_of_office_from": "2026-11-18T20:11:49+00:00",
"out_of_office_until": "2026-11-18T20:11:49+00:00",
"out_of_office_message": "I am away this week. For urgent matters please contact the office.",
"is_pending_fact_find_account": false,
"permissions": {
"firm:read": [
"firm"
],
"network:read": [
"network:uuid"
]
},
"managed_by_head_office": false
}
},
"primary_address": {
"uuid": "55a60249-6bf5-4802-991f-87f988ff6925",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"name": "Work Address",
"address_1": "Suite E, 5 The Briars",
"address_2": "Waterberry Drive",
"address_3": "The Innovative Centre",
"address_4": "Waterlooville",
"town_city": "Waterlooville",
"county": "Hampshire",
"postcode": "PO7 7YH",
"country": "United Kingdom",
"move_in_date": "2025-11-18",
"accounts": {
"uuid": "f08f3e8d-23bf-4d4b-b848-af98efb282eb",
"created_at": "2026-11-18T20:11:49+00:00",
"updated_at": "2026-11-18T20:11:49+00:00",
"type": "client",
"role": "client",
"first_name": "Gareth",
"last_name": "Thompson",
"name": "Gareth Thompson",
"email": "gareth@codepotato.co.uk",
"photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
"first_contact_date": "2026-11-18T20:11:49+00:00",
"next_review_date": "2026-11-18T20:11:49+00:00",
"previous_review_date": "2026-11-18T20:11:49+00:00",
"anniversary_review_date": "2026-11-18T20:11:49+00:00",
"terms_of_business_at": "2026-11-18T20:11:49+00:00",
"client_agreement_at": "2026-11-18T20:11:49+00:00",
"with_login": true,
"has_joint_account": true,
"can_be_deleted": "false",
"ownership_percentage": 100.0,
"inactive_at": "2026-11-18",
"last_interaction_at": "2026-11-18 20:11:49",
"referral_code": "ABC12345",
"is_out_of_office": true,
"out_of_office_from": "2026-11-18T20:11:49+00:00",
"out_of_office_until": "2026-11-18T20:11:49+00:00",
"out_of_office_message": "I am away this week. For urgent matters please contact the office.",
"is_pending_fact_find_account": false,
"permissions": {
"firm:read": [
"firm"
],
"network:read": [
"network:uuid"
]
},
"managed_by_head_office": false
}
},
"interests": [
{
"uuid": "7c3c084d-b54c-468d-8eb6-bed50a78a85e",
"name": "Wealth",
"description": "Investment and wealth management enquiries",
"position": 1,
"archived": false,
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00"
}
],
"custom_fields": [
{
"uuid": "152291f0-a07e-4ae8-a28d-b62b9b5309b0",
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00",
"type": "string",
"name": "Favourite Drink",
"reference": "favourite_drink",
"is_required": false,
"value": "Coffee",
"selection_options": [
"Coffee",
"Tea",
"Water"
],
"help_text": "This is the client's favourite drink.",
"is_retired": false
}
],
"created_at": "2026-11-18T20:11:43+00:00",
"updated_at": "2026-11-18T20:11:43+00:00"
}
{
"message": "This action is unauthorized."
}
{
"message": "Not Found"
}
{
"message": "This lead has been promoted to a client and is locked."
}
{
"message": "This lead is archived and cannot be changed."
}
{
"message": "This lead is disqualified and cannot be changed."
}
{
"message": "The first name field is required.",
"errors": {
"first_name": [
"The first name field is required."
]
}
}
{
"message": "The lead must be at least 18 years old.",
"errors": {
"date_of_birth": [
"The lead must be at least 18 years old."
]
}
}
{
"message": "The selected lead source is invalid.",
"errors": {
"source_uuid": [
"The selected lead source is invalid."
]
}
}
{
"message": "The lead sub-source does not belong to the chosen lead source.",
"errors": {
"sub_source_uuid": [
"The lead sub-source does not belong to the chosen lead source."
]
}
}