Sell Ltd Developers
List a business for sale with the Sell Ltd API or MCP
Use your own software or a connected AI agent to prepare a UK business advert, attach photos and video, and publish. Your first eligible advert gets 14 days of marketplace advertising free from publication.
Create a free Sell Ltd account, then choose your key permissions. No subscription or payment card required to get started.
Quickstart: create your key
- Sign up or sign in to your Sell Ltd account and verify your email.
- Open API account, create a key with
research:readand select the REST audience. For a research-only integration, deselect the other permissions. For a seller integration, keep account read, listing write and media write, and allow all your adverts to create new ones. Confirm publishing authority if the agent will publish. - Creating a key copies it to your clipboard when your browser allows it. Use Copy key in your API account to copy it again. Send it as
Authorization: Bearer <API_KEY>.
Keep the key in a secure environment variable on your server. Never commit it, put it in browser code, or share it in screenshots. You can revoke a key from your API account.
curl "https://sellltd.co.uk/api/v1/companies?q=bakery&limit=5" \ -H "Authorization: Bearer $SELL_API_KEY" \ -H "Idempotency-Key: company-search-001"
Use a different operation key for each new research request. If retrying the same operation, reuse the same key and identical inputs. The operation key is not your API key.
Research pricing and limits
The shared free allowance is up to 600 research requests per rolling hour and 5,000 per rolling 24 hours per account across REST and MCP. Beyond it, successful company searches and lookups cost 1p each and indicative valuations cost 5p each. Searches with no results, valuations with insufficient data and failed requests do not use paid credit. Add prepaid credit from £10 in your API account; there is no subscription or automatic top-up. VAT is not charged. Insufficient credit stops the request. If the outcome is uncertain, reserved credit can remain pending while the operation is reconciled.
Separate transport and abuse-protection limits apply; the current connected limit is 120 requests per minute per IP and connection, plus account and key limits. Upstream limits can also apply. Respect 429 and Retry-After.
Base URL and authentication
Base URL: https://sellltd.co.uk/api/v1. Company research requires a scoped API key with the REST audience and research:read. Other account operations can use a key with the appropriate scopes or an OAuth authorization-code connection with PKCE S256. OAuth REST resource audience is https://sellltd.co.uk/api/v1; MCP tokens have a different audience.
OAuth clients can read authorization server metadata and register exact HTTPS or local-loopback redirects. Mutating account operations and metered research calls require a unique Idempotency-Key header; reuse it only with identical content when retrying. Read-only listing validation does not require one.
Search from your application
The required query accepts 2–120 characters; optional limit is an integer from 1 to 20. Encode the query before sending it.
const url = new URL('https://sellltd.co.uk/api/v1/companies');
url.searchParams.set('q', 'Example Bakery');
url.searchParams.set('limit', '5');
const response = await fetch(url, { headers: {
Authorization: 'Bearer ' + process.env.SELL_API_KEY,
'Idempotency-Key': 'company-search-001'
}});
if (!response.ok) throw new Error('Search failed: ' + response.status);
const result = await response.json();
console.log(result.companies);The JSON result includes companies, source and retrievedAt. An empty list means no matching data was returned. Treat a 503 as a temporary failure and retry using the same operation key.
Calculate a valuation
Supply financial figures you want assessed. The result is indicative, not a verified company valuation.
curl -X POST https://sellltd.co.uk/api/v1/valuations \
-H "Authorization: Bearer $SELL_API_KEY" \
-H "Idempotency-Key: valuation-001" \
-H "Content-Type: application/json" \
-d '{"companyName":"Example Bakery","turnover":180000,"adjustedEbitda":35000}'Endpoints
| Method and path | Purpose |
|---|---|
GET /companies?q=bakery | Company search — API key required |
GET /companies/{number} | Cache-first company information — API key required |
POST /valuations | Indicative valuation — API key required |
GET /marketplace | Public active teasers and filters |
GET /marketplace/{slug} | Teaser or authorized full advert |
GET /listings; GET /listings/{id} | Owned adverts |
POST /listings; PATCH /listings/{id} | Create/patch draft |
POST /listings/{id}/validate | Missing fields and advertising eligibility |
POST /listings/{id}/publish; /pause | Publish with delegated scope; pause |
POST /listings/{id}/media | Reserve signed upload |
POST /listings/{id}/media/{mediaId}/complete | Validate and attach uploaded bytes |
POST /listings/{id}/quote; /checkout | Advertising quote or human payment link |
GET /alerts; POST /alerts | Saved searches and notifications |
Research requests
GET /api/v1/companies?q=bakery&limit=5
GET /api/v1/companies/00000006
POST /api/v1/valuations
Content-Type: application/json
{"companyName":"Example Bakery","turnover":180000,"adjustedEbitda":35000,"periodEnd":"2026-03-31"}Lookup returns the register profile, available officer and significant-controller records, filing history, charge and insolvency information, and up to five cached financial periods. Check the source, retrieval time and section coverage before drawing conclusions. Full filing documents and fresh financial extraction are separate from this lookup. Valuation returns an indicative range, methodology, confidence and missing information from the deterministic engine. It does not run paid enrichment.
Create and edit an advert
Send this fictional example to POST /listings. Only supply owner-approved facts.
{
"company_name": "Example Bakery",
"headline": "Established bakery in the North West",
"teaser_summary": "Independent bakery with a local customer base. Owner retiring.",
"summary": "Seller-approved description of operations, premises and the sale opportunity.",
"categories": [
"Food & Drink"
],
"region": "North West",
"location_type": "fixed",
"business_address": "1 Example Street, Manchester",
"postcode": "M1 1AA",
"asking_price_mode": "exact",
"asking_price": 95000,
"turnover_disclosure": "provided",
"turnover": 180000,
"profit_disclosure": "undisclosed",
"financial_period": "Year ended 31 March 2026",
"confidentiality": "anonymous",
"premises_included": true,
"tenure": "leasehold",
"authority_confirmed": true
}Patch an existing listing with its latest expectedVersion. A conflict requires re-reading and resolving edits. Creation never publishes. Optional fields include company_number, town, asking_price_max, net_profit, ebitda, employees, year_established, highlights, growth_opportunities, reason_for_sale, website and video_url. OpenAPI defines values and limits.
Add media
POST /listings/ID/media
Idempotency-Key: upload-photo-01
{"kind":"image","name":"bakery.jpg","mime":"image/jpeg","size":125000,"visibility":"public"}
PUT the file bytes to returned signedUrl using their MIME type.
POST /listings/ID/media/MEDIA_ID/complete
Idempotency-Key: complete-photo-01
{}Up to 15 JPEG/PNG/WebP photos (10 MiB each), five MP4 videos (100 MiB each) and three PDF/DOCX/XLSX documents (10 MiB each). An advert can also reference a supported YouTube or Vimeo URL. Uploaded videos and documents are NDA-protected. Do not expose identifying imagery in an anonymous public teaser. Validation errors explain type/size failures.
Validate, advertise and publish
POST /listings/ID/validate
{}
POST /listings/ID/quote
{"days":30}
POST /listings/ID/checkout
Idempotency-Key: checkout-01
{"days":30}
POST /listings/ID/publish
Idempotency-Key: publish-01
{}First publication can use the account’s introductory 14-day trial. Other advertising is purchased once for 7–365 days (£4.90/7, £21/30, £57/90, £102/180, £147/270, £194.50/365). Checkout returns a link for the person to pay; only verified payment fulfilment grants time. Publishing requires opt-in listings:publish, verified email and all normal checks.
Scopes and recovery
Scopes: research:read, account:read, listings:write, media:write, alerts:write, listings:publish. Publication authority must be explicitly selected. Keys can be restricted to selected adverts and to REST, MCP or both. Registration permits five requests per minute per IP; upstream limits may also apply.
Errors return error and error_description. Respect 429 and Retry-After. 400 means invalid input; 401 means a valid key or connection is required; 402 means insufficient API credit; 403 means missing scope/access or an account under review; 404 means not found; 409 means version/idempotency conflict or a pending operation; 503 means the service is temporarily unavailable. Never change a pending operation’s key: the action may have completed.
Buyer access and alerts
Search filters: q, sector, region, minPrice, maxPrice, page, pageSize and sort (newest/price_asc/price_desc). A locked advert returns a human NDA-signing link. Marketplace browsing is public; when an authenticated key requests a listing detail it needs account:read. Save alerts with name, criteria, frequency (instant/daily/weekly) and active. Existing account limits apply.
