Move a lead to a new status
Set lead_status and record why in the history. Statuses called, contacted and follow_up also stamp last_contacted_at. Setting won notifies the owner. Answers 400 invalid_status for an unknown status.
POST
https://app.softsolz.uk/api/v1/services/my-leads/leads/{id}/statusRecent Requests
Kept only in this browserTimeStatusTook
Send a request with Try it to see it here.
Path Params
idstringrequiredHeaders
AuthorizationstringrequiredBearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.
Idempotency-KeystringOptional idempotency key for safe retries.
Body Params
statusstringrequiredThe new status.
reasonstringOptional note kept in the status history.
Response
Response Body
idintegerLead id.run_idinteger | nullResearch run that produced this lead, or null when it was added directly.namestringCompany name.websitestring | nullWebsite URL.domainstring | nullBare domain, lower case.external_idstring | nullYour own stable id for this company.sourcestringHow the lead got here.viastring | nullChannel of the last write: research, api, connected_app, or null for the dashboard.via_labelstring | nullName of the app or key that last wrote the lead.fit_scoreinteger | nullFit against the brief, 0-100.lead_scoreinteger | nullReadiness to buy, 0-100.confidencenumber | nullData confidence, 0-1.verification_tierstring | nullverified, probable or unverified.verified_contact_countintegerHow many contact channels were verified on the official site.lead_statusstringWhere the lead is in your process.industrystring | nullPrimary industry.citystring | nullCity.statestring | nullState or region.countrystring | nullCountry.employee_bandstring | nullHeadcount band.revenue_bandstring | nullRevenue band.source_urlstring | nullPrimary source URL.owner_user_idinteger | nullMember who owns the lead, or null when unassigned.owner_namestring | nullOwner display name.owner_emailstring | nullOwner email.tagsarray of stringsLower-case labels for segmentation.last_contacted_atstring | nullSet whenever the status becomes called, contacted or follow_up.company_idstring | nullCRM company created by convert, if any.contact_idstring | nullCRM contact created by convert, if any.deal_idinteger | nullDeal created by convert, if any.resultobjectStructured research grouped by section. Every key is optional. Use the same keys on create and update; on update, sections merge key by key with what is already stored.created_atstringCreation timestamp.updated_atstringLast update. Round-trip as expected_updated_at on PATCH to refuse stale writes (409 STALE_VERSION).Request
curl --request POST \ --url https://app.softsolz.uk/api/v1/services/my-leads/leads/{id}/status \ --header 'Authorization: Bearer sk_live_your_key' \ --header 'Content-Type: application/json' \ --data '{ "status": "contacted", "reason": "Replied to our email, wants a demo."}'Credentials
Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.
Response · 200
{ "data": { "id": 42, "run_id": null, "name": "Example Bakery", "website": "https://example.com", "domain": "example.com", "external_id": "crm-1001", "source": "api", "via": "connected_app", "via_label": "Claude", "fit_score": 87, "lead_score": 64, "confidence": 0.8, "verification_tier": "verified", "verified_contact_count": 2, "lead_status": "new", "industry": "Food", "city": "Manchester", "state": "Greater Manchester", "country": "United Kingdom", "employee_band": "11-50", "revenue_band": "1M-10M", "source_url": "https://example.com/about", "owner_user_id": 7, "owner_name": "Priya", "owner_email": "priya@example.com", "tags": [ "manchester", "q4" ], "last_contacted_at": null, "company_id": null, "contact_id": null, "deal_id": null, "result": { "description": "Independent bakery chain with four shops in Manchester.", "contact": { "contact_email": "hello@example.com", "phone": "+44 161 000 0000" }, "social": { "linkedin": "https://linkedin.com/company/example" }, "insights": { "why_fit": "Growing fast, still on spreadsheets.", "pain_points": [ "manual invoicing" ] }, "fit_breakdown": { "industry": { "weight": 0.4, "subscore": 90 } }, "analysis": { "what_they_do": "Retail bakery", "decision_maker": "Owner" }, "size_detail": { "years_in_business": 12 }, "tech_stack": { "cms": "Shopify", "technologies": [ "Klaviyo" ] }, "financial_indicators": { "funding": "Bootstrapped" }, "website_intel": { "has_pricing_page": true }, "registry_info": { "legal_name": "Example Bakery Ltd" }, "activity": { "latest_news": [ "Opened a fifth shop in 2026" ] }, "hiring": { "hiring_active": true, "open_roles": [ "Shop manager" ] }, "reviews": { "google_rating": 4.6, "google_review_count": 312 }, "sources": [ "https://example.com/about" ], "employee_estimate": 45, "revenue_estimate_usd": 2500000, "num_locations": 4, "cities_operating": [ "Manchester", "Salford" ], "crm": "HubSpot", "erp": "Odoo" }, "created_at": "2026-09-01T09:00:00.000Z", "updated_at": "2026-09-02T09:00:00.000Z" }}