Add one lead
Save one researched company. Read GET /settings first for the research brief and the section keys, then fill name, website, scores, tags and sections with what you found. This never spends SoftSolz AI credits. Duplicates are detected by external_id, then domain, then any contact email; on_duplicate decides what happens (default error, which answers 409 duplicate_lead with existing_id so you can PATCH it instead). Answers 402 free_plan_limit_reached when the free plan cap is hit.
https://app.softsolz.uk/api/v1/services/my-leads/leadsRecent Requests
Kept only in this browserHeaders
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
namestringCompany name. Required unless website is given.
websitestringWebsite URL or bare domain.
external_idstringYour own stable id; matched first for dedupe.
industrystringPrimary industry.
citystringCity.
statestringState or region.
countrystringCountry.
employee_bandstringHeadcount band such as 11-50.
revenue_bandstringRevenue band such as 1M-10M.
fit_scoreintegerFit against the brief, 0-100. Values outside the range are rejected with invalid_score.
lead_scoreintegerReadiness to buy, 0-100.
confidencenumberData confidence, 0-1.
verification_tierstringverified, probable or unverified.
lead_statusstringInitial status; defaults to new.
tagsarray of stringsLabels for segmentation; lower-cased and de-duplicated.
owner_user_idintegerMember id to own the lead.
contact_emailstringShortcut for sections.contact.contact_email. Must be a valid email address.
contact_phonestringShortcut for sections.contact.phone, with a country code.
contact_namestringShortcut for sections.contact.contact_name, the person to reach.
sectionsobjectStructured 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.
on_duplicatestringWhat to do when a lead with the same external_id, domain or contact email already exists: error (409 duplicate_lead with existing_id), merge (fill blanks, merge sections, union tags), skip, or create a second record.
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 \ --header 'Authorization: Bearer sk_live_your_key' \ --header 'Content-Type: application/json' \ --data '{ "name": "Example Bakery", "website": "example.com", "external_id": "crm-1001", "industry": "Food", "city": "Manchester", "state": "Greater Manchester", "country": "United Kingdom", "employee_band": "11-50", "revenue_band": "1M-10M", "fit_score": 87, "lead_score": 64, "confidence": 0.8, "verification_tier": "probable", "lead_status": "new", "tags": [ "manchester" ], "contact_email": "hello@example.com", "contact_phone": "+44 161 000 0000", "contact_name": "Sam Baker", "sections": { "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" }, "on_duplicate": "merge"}'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 · 201
{ "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" }}