Replace, add or remove tags on a lead
Send tags to replace the whole set, or add and remove to change it incrementally. Tags are lower-cased and de-duplicated.
POST
https://app.softsolz.uk/api/v1/services/my-leads/leads/{id}/tagsRecent 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
tagsarray of stringsFull replacement set. When present, add and remove are ignored.
addarray of stringsTags to add.
removearray of stringsTags to remove.
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}/tags \ --header 'Authorization: Bearer sk_live_your_key' \ --header 'Content-Type: application/json' \ --data '{ "tags": [ "manchester", "q4" ], "add": [ "hot" ], "remove": [ "cold" ]}'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" }}