SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester
My Leads

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.

POSThttps://app.softsolz.uk/api/v1/services/my-leads/leads

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

namestring

Company name. Required unless website is given.

websitestring

Website URL or bare domain.

external_idstring

Your own stable id; matched first for dedupe.

industrystring

Primary industry.

citystring

City.

statestring

State or region.

countrystring

Country.

employee_bandstring

Headcount band such as 11-50.

revenue_bandstring

Revenue band such as 1M-10M.

fit_scoreinteger

Fit against the brief, 0-100. Values outside the range are rejected with invalid_score.

lead_scoreinteger

Readiness to buy, 0-100.

confidencenumber

Data confidence, 0-1.

verification_tierstring

verified, probable or unverified.

lead_statusstring

Initial status; defaults to new.

tagsarray of strings

Labels for segmentation; lower-cased and de-duplicated.

owner_user_idinteger

Member id to own the lead.

contact_emailstring

Shortcut for sections.contact.contact_email. Must be a valid email address.

contact_phonestring

Shortcut for sections.contact.phone, with a country code.

contact_namestring

Shortcut for sections.contact.contact_name, the person to reach.

sectionsobject

Structured 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_duplicatestring

What 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"
}
}