{"openapi":"3.1.0","info":{"title":"Sell Ltd Marketplace API","version":"1.0.0","description":"Company research with a scoped API key and usage allowance; scoped owner listings, media and buyer alerts. Payment and NDA signatures require the human to open returned links."},"servers":[{"url":"https://sellltd.co.uk/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Sell Ltd scoped API key"},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://sellltd.co.uk/oauth/authorize","tokenUrl":"https://sellltd.co.uk/oauth/token","scopes":{"research:read":"research:read","account:read":"account:read","listings:write":"listings:write","media:write":"media:write","alerts:write":"alerts:write","listings:publish":"listings:publish"}}}}},"schemas":{"ListingInput":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"expectedVersion":{"type":"integer","minimum":0},"company_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"company_number":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}]},"business_address":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"postcode":{"anyOf":[{"type":"string","maxLength":12},{"type":"null"}]},"headline":{"anyOf":[{"type":"string","maxLength":280},{"type":"null"}]},"title":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"teaser_summary":{"anyOf":[{"type":"string","maxLength":1500},{"type":"null"}]},"summary":{"anyOf":[{"type":"string","maxLength":12000},{"type":"null"}]},"sector":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"categories":{"type":"array","items":{"type":"string","enum":["Retail","Food & Drink","Hospitality","Services","Professional Services","Technology","E-commerce","Manufacturing","Construction","Health & Beauty","Education","Transport","Leisure","Other"]},"maxItems":3},"region":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"town":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"location_type":{"type":"string","enum":["fixed","online","relocatable"]},"asking_price_mode":{"type":"string","enum":["exact","range","request"]},"asking_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"asking_price_max":{"anyOf":[{"type":"number"},{"type":"null"}]},"asking_price_from":{"type":"boolean"},"turnover":{"anyOf":[{"type":"number"},{"type":"null"}]},"net_profit":{"anyOf":[{"type":"number"},{"type":"null"}]},"ebitda":{"anyOf":[{"type":"number"},{"type":"null"}]},"turnover_disclosure":{"type":"string","enum":["provided","undisclosed","unknown"]},"profit_disclosure":{"type":"string","enum":["provided","undisclosed","unknown"]},"financial_period":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"premises_included":{"type":"boolean"},"tenure":{"type":"string","enum":["freehold","leasehold","both","other","na"]},"employees":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"year_established":{"anyOf":[{"type":"integer","minimum":1600,"maximum":2100},{"type":"null"}]},"highlights":{"anyOf":[{"type":"string","maxLength":6000},{"type":"null"}]},"growth_opportunities":{"anyOf":[{"type":"string","maxLength":6000},{"type":"null"}]},"reason_for_sale":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"buyer_profile":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"confidentiality":{"type":"string","enum":["anonymous","named"]},"authority_confirmed":{"type":"boolean"},"website":{"anyOf":[{"type":"string","format":"uri","maxLength":500},{"type":"null"}]},"video_url":{"anyOf":[{"type":"string","format":"uri","maxLength":500},{"type":"null"}]},"cover_media_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"media_order":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":19}},"additionalProperties":false},"Browse":{"type":"object","properties":{"q":{"type":"string","maxLength":120},"sector":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"minPrice":{"type":"number","minimum":0},"maxPrice":{"type":"number","minimum":0},"sort":{"type":"string","enum":["newest","price_asc","price_desc"]},"page":{"type":"integer","minimum":1,"maximum":10000},"pageSize":{"type":"integer","minimum":1,"maximum":60},"limit":{"type":"integer","minimum":1,"maximum":60}},"additionalProperties":true}}},"paths":{"/companies":{"get":{"operationId":"searchCompanies","summary":"UK company search","security":[{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Unique operation ID. Reuse with identical input when retrying."}]}},"/companies/{number}":{"parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getCompany","summary":"Retrieve a cached UK company dossier","security":[{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"description":"Returns the available company profile and cached financial periods. The dossier covers officers, persons with significant control, filing history, charges and insolvency. Check available, partial and total for each register section. Each section returns up to 100 records. Filing documents and fresh financial extraction are outside this operation.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Unique operation ID. Reuse with identical input when retrying."}]}},"/valuations":{"post":{"operationId":"calculateValuation","summary":"Indicative deterministic calculation","security":[{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"companyName":{"type":"string"},"companyNumber":{"type":"string"},"turnover":{"type":"number","minimum":0},"adjustedEbitda":{"type":"number"},"cash":{"type":"number"},"interestBearingDebt":{"type":"number","minimum":0},"sicCodes":{"type":"array","items":{"type":"string"}},"periodEnd":{"type":"string","format":"date"}},"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"description":"Unique operation ID. Reuse with identical input when retrying."}]}},"/marketplace":{"get":{"operationId":"searchMarketplace","summary":"Browse active public teasers","security":[],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"sector","in":"query","schema":{"type":"string","maxLength":120}},{"name":"region","in":"query","schema":{"type":"string","maxLength":120}},{"name":"minPrice","in":"query","schema":{"type":"number","minimum":0}},{"name":"maxPrice","in":"query","schema":{"type":"number","minimum":0}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","price_asc","price_desc"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":60}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":60}}]}},"/marketplace/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getListing","summary":"Public teaser, or full details with signed-NDA/owner access","security":[{},{"oauth":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}}}},"/listings":{"get":{"operationId":"listOwnedListings","summary":"Owned adverts","security":[{"oauth":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}}},"post":{"operationId":"createListing","summary":"Create draft; does not publish","security":[{"oauth":["listings:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/listings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getOwnedListing","summary":"Owned advert draft","security":[{"oauth":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}}},"patch":{"operationId":"patchListing","summary":"Patch owned draft with expectedVersion","security":[{"oauth":["listings:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/listings/{id}/validate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"validateListing","summary":"Missing fields and advertising eligibility","security":[{"oauth":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}}}},"/listings/{id}/publish":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"publishListing","summary":"Publish with opt-in delegated authority","security":[{"oauth":["listings:publish"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/listings/{id}/pause":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"pauseListing","summary":"Pause advert; paid clock continues","security":[{"oauth":["listings:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/listings/{id}/media":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createMediaUpload","summary":"Get signed byte-upload URL","security":[{"oauth":["media:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","name","mime","size","visibility"],"properties":{"kind":{"enum":["image","video","document"]},"name":{"type":"string"},"mime":{"type":"string"},"size":{"type":"integer","minimum":1},"visibility":{"enum":["public","nda"]}},"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/listings/{id}/media/{mediaId}/complete":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"completeMediaUpload","summary":"Validate uploaded bytes and attach media","security":[{"oauth":["media:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/listings/{id}/quote":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"quoteAdvertising","summary":"Quote 7–365 advertising days","security":[{"oauth":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["days"],"properties":{"days":{"type":"integer","minimum":7,"maximum":365}},"additionalProperties":false}}}}}},"/listings/{id}/checkout":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createAdvertisingCheckout","summary":"Return human Stripe Checkout link; never auto-charge","security":[{"oauth":["listings:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["days"],"properties":{"days":{"type":"integer","minimum":7,"maximum":365}},"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}},"/alerts":{"get":{"operationId":"listAlerts","summary":"Read own saved searches","security":[{"oauth":["account:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}}},"post":{"operationId":"saveAlert","summary":"Create or edit own search alert; account limits apply","security":[{"oauth":["alerts:write"]},{"apiKey":[]}],"responses":{"200":{"description":"Structured result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input"},"401":{"description":"Connect or refresh account authorization"},"402":{"description":"Insufficient prepaid API credit"},"403":{"description":"Missing scope or access"},"409":{"description":"Version conflict, idempotency conflict or pending operation"},"429":{"description":"Rate limited; respect Retry-After"},"503":{"description":"Temporarily unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","criteria"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":120},"criteria":{"type":"object","properties":{"q":{"type":"string"},"sectors":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","items":{"type":"string"}},"priceMin":{"type":"number"},"priceMax":{"type":"number"},"turnoverMin":{"type":"number"},"turnoverMax":{"type":"number"},"employeesMin":{"type":"integer"},"employeesMax":{"type":"integer"},"keywords":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"frequency":{"enum":["instant","daily","weekly"]},"active":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}]}}}}