Common Elements Vendors API
The Vendors API from Common Elements — 3 operation(s) for vendors.
Operations 3
GET
/api/v1/vendors/{id}
The full public profile for one verified vendor: identity, self-reported…
#
The Vendors API from Common Elements — 3 operation(s) for vendors.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/commonelements-com:commonelements-com-vendors-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Commonelements Com Vendors API
version: 1.4.0
contact:
name: Common Elements API support
url: https://commonelements.com/contact
license:
name: Commercial data licence
url: https://commonelements.com/developers/pricing/builder
termsOfService: https://commonelements.com/terms
description: 'Operations tagged Vendors across 2 of this provider''s published API definitions: commonelements-com-openapi.json, commonelements-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://commonelements.com/api/v1
description: Production
- url: https://commonelements.com/api/v1/meta/sandbox
description: Sandbox — fixed dataset, published test key, not metered
security:
- bearerAuth: []
tags:
- name: Vendors
description: ''
paths:
/api/v1/vendors:
get:
operationId: vendorsList
summary: 'Search the public vendor directory: verified vendors only, ranked by review…'
description: 'Search the public vendor directory: verified vendors only, ranked by review rating. Filter by name/description text, state (home or served), or service category.
**Plan:** Free keys: up to 50 rows per request; paid tiers raise the cap.
- Only verified vendors are listed. Coverage grows as vendors complete verification — see the note this endpoint returns on an empty result for the current count.'
tags:
- Vendors
security:
- bearerAuth: []
x-ce-scope: vendors.read
x-ce-docs-url: https://commonelements.com/developers/docs#vendors-list
x-ce-example-request: "curl \"https://commonelements.com/api/v1/vendors?state=FL&category=roofing\" \\\n -H \"Authorization: Bearer ce_live_your_key_here\""
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- ok
- data
properties:
ok:
type: boolean
const: true
data:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Vendor organization id.
name:
type: string
description: Vendor legal name.
subtype:
type:
- string
- 'null'
description: Vendor category subtype.
city:
type:
- string
- 'null'
description: Vendor location.
state:
type:
- string
- 'null'
description: Vendor location.
zip:
type:
- string
- 'null'
description: Vendor location.
website:
type:
- string
- 'null'
description: Vendor website.
service_states:
type: array
items:
type: string
description: States the vendor reports serving.
directory_slug:
type:
- string
- 'null'
description: Slug for the public vendor directory page.
review_count:
type:
- number
- 'null'
description: Platform review volume and average rating. Results are sorted by rating, highest first.
review_avg_rating:
type:
- number
- 'null'
description: Platform review volume and average rating. Results are sorted by rating, highest first.
description:
type:
- string
- 'null'
description: Vendor-authored description.
service_categories:
type: array
items:
type: string
description: Vendor-self-asserted service scope.
service_counties:
type: array
items:
type: string
description: Vendor-self-asserted service scope.
license_number:
type:
- string
- 'null'
description: Vendor-self-asserted credentials. Not independently verified at this endpoint — see /v1/vendors/{id} for the verified trust profile.
insurance_carrier:
type:
- string
- 'null'
description: Vendor-self-asserted credentials. Not independently verified at this endpoint — see /v1/vendors/{id} for the verified trust profile.
additionalProperties: true
additionalProperties: true
examples:
default:
value:
ok: true
data:
- id: 9a71c6b0-4e2f-41d8-8b09-5c3a2d17e604
name: COASTAL ROOFING SOLUTIONS, LLC
subtype: roofing
city: Fort Lauderdale
state: FL
zip: '33301'
website: https://example.com
service_states:
- FL
directory_slug: coastal-roofing-solutions
review_count: 24
review_avg_rating: 4.8
description: Licensed commercial and residential roofing serving South Florida HOAs and condos.
service_categories:
- roofing
service_counties:
- Broward
- Miami-Dade
license_number: CCC1234567
insurance_carrier: null
total: 1
limit: 10
offset: 0
'400':
description: '`validation_error` — A query parameter or body field is missing, malformed, or outside its allowed range. The message names the first parameter that failed. Next: Fix the named parameter and re-send. Every parameter and its accepted values are in the OpenAPI document at /api/v1/openapi; retrying an unchanged request will fail the same way.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: '`invalid_api_key` — No Authorization header, a header that is not `Bearer <key>`, or a key that does not resolve to an active record. Next: Send `Authorization: Bearer ce_live_...`. If the header is correct, the key has been revoked or expired — mint a new one at /settings/api-keys. Keys are shown once at creation and stored only as a hash, so a lost key cannot be recovered.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '`scope_not_allowed` — The key is valid but was created without the scope this endpoint requires. Scopes are set at key creation and are not widened at request time. Next: Create a key carrying the scope named in the message, or use the `all` scope. Each endpoint''s required scope is on its OpenAPI operation as `x-ce-scope`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: '`quota_exceeded` — The key has spent every request included in the current calendar month. There is no overage charge and no automatic top-up. Next: Call /api/v1/meta/usage to see the reset date and how the quota was spent, then either wait for the reset at the start of the next calendar month or upgrade the plan. /api/v1/meta/usage does not itself consume quota.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: '`internal_error` — The request was accepted and failed on our side. Next: Retry with exponential backoff (1s, 2s, 4s, up to about 30s). If it persists past a few minutes, check /api/v1/meta/status and contact support with the time of the request.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- name: q
in: query
required: false
description: Free-text search over name and description.
schema:
type: string
- name: state
in: query
required: false
description: Two-letter state code. Matches either the vendor's home state or a state it serves.
schema:
type: string
- name: category
in: query
required: false
description: A vendor-category slug, matched against the vendor's self-tagged service categories.
schema:
type: string
- name: limit
in: query
required: false
description: Max results per page. Free keys are capped at 50; paid tiers get a higher cap.
schema:
type: number
- name: offset
in: query
required: false
description: Pagination offset (default 0).
schema:
type: number
x-ce-plan-note: 'Free keys: up to 50 rows per request; paid tiers raise the cap.'
servers:
- url: https://commonelements.com/api/v1
description: Production
- url: https://commonelements.com/api/v1/meta/sandbox
description: Sandbox — fixed dataset, published test key, not metered
/api/v1/vendors/{id}:
get:
operationId: vendorsDetail
summary: 'The full public profile for one verified vendor: identity, self-reported…'
description: 'The full public profile for one verified vendor: identity, self-reported service offerings, review summary, and the neutral, independently-sourced trust profile (workers'' comp status, professional licenses, enforcement history) pulled from public records.
- Never returns private contact data, street address lines, phone, or email. That data does not exist on this endpoint at all, not merely hidden.
- Distinguish self-asserted from verified: description/services_offered/certifications/license_number are what the vendor states about itself; trust_profile is what public records independently confirm.'
tags:
- Vendors
security:
- bearerAuth: []
x-ce-scope: vendors.read
x-ce-docs-url: https://commonelements.com/developers/docs#vendors-detail
x-ce-example-request: "curl \"https://commonelements.com/api/v1/vendors/9a71c6b0-4e2f-41d8-8b09-5c3a2d17e604\" \\\n -H \"Authorization: Bearer ce_live_your_key_here\""
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- ok
- data
properties:
ok:
type: boolean
const: true
data:
type: object
properties:
id:
type:
- string
- 'null'
description: Vendor identity and location.
name:
type:
- string
- 'null'
description: Vendor identity and location.
subtype:
type:
- string
- 'null'
description: Vendor identity and location.
city:
type:
- string
- 'null'
description: Vendor identity and location.
state:
type:
- string
- 'null'
description: Vendor identity and location.
zip:
type:
- string
- 'null'
description: Vendor identity and location.
website:
type:
- string
- 'null'
description: Vendor identity and location.
verification_status:
type: string
description: Always "verified" for a row this endpoint returns.
service_states:
type: array
items:
type: string
description: States the vendor reports serving.
review_count:
type:
- number
- 'null'
description: Platform review summary.
review_avg_rating:
type:
- number
- 'null'
description: Platform review summary.
description:
type:
- string
- 'null'
description: Vendor-self-asserted display fields.
license_number:
type:
- string
- 'null'
description: Vendor-self-asserted display fields.
insurance_carrier:
type:
- string
- 'null'
description: Vendor-self-asserted display fields.
team_size:
type:
- string
- 'null'
description: Vendor-self-asserted display fields.
booth_tagline:
type:
- string
- 'null'
description: Vendor-self-asserted display fields.
services_offered:
type: array
items:
type: string
description: Vendor-self-asserted service scope and credentials.
certifications:
type: array
items:
type: string
description: Vendor-self-asserted service scope and credentials.
service_categories:
type: array
items:
type: string
description: Vendor-self-asserted service scope and credentials.
service_counties:
type: array
items:
type: string
description: Vendor-self-asserted service scope and credentials.
service_offerings:
type: array
items: {}
description: 'Published offering posts: id, title, body, category_slugs, service_states, service_counties, pinned, published_at.'
trust_profile:
type:
- object
- 'null'
additionalProperties: true
description: Independently-sourced, public-record credential facts (FL workers'-comp status, professional licenses, enforcement count). Null when the vendor has no confirmed public-record match — this is the verified boundary, distinct from the self-asserted fields above.
created_at:
type: string
format: date-time
description: When the vendor record was created.
additionalProperties: true
additionalProperties: true
examples:
default:
value:
ok: true
data:
id: 9a71c6b0-4e2f-41d8-8b09-5c3a2d17e604
name: COASTAL ROOFING SOLUTIONS, LLC
subtype: roofing
city: Fort Lauderdale
state: FL
zip: '33301'
website: https://example.com
verification_status: verified
service_states:
- FL
directory_slug: coastal-roofing-solutions
review_count: 24
review_avg_rating: 4.8
follower_count: 6
description: Licensed commercial and residential roofing serving South Florida HOAs and condos.
service_categories:
- roofing
service_counties:
- Broward
- Miami-Dade
license_number: CCC1234567
insurance_carrier: null
year_established: 2011
team_size: 11-50
booth_tagline: 24/7 emergency roof response for South Florida associations.
services_offered:
- Roof replacement
- Storm damage repair
certifications:
- GAF Master Elite
service_offerings: []
trust_profile:
workers_comp_status: active
licenses:
- type: CCC
number: CCC1234567
status: active
enforcement_count: 0
created_at: '2025-06-01T00:00:00Z'
'400':
description: '`validation_error` — A query parameter or body field is missing, malformed, or outside its allowed range. The message names the first parameter that failed. Next: Fix the named parameter and re-send. Every parameter and its accepted values are in the OpenAPI document at /api/v1/openapi; retrying an unchanged request will fail the same way.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: '`invalid_api_key` — No Authorization header, a header that is not `Bearer <key>`, or a key that does not resolve to an active record. Next: Send `Authorization: Bearer ce_live_...`. If the header is correct, the key has been revoked or expired — mint a new one at /settings/api-keys. Keys are shown once at creation and stored only as a hash, so a lost key cannot be recovered.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '`scope_not_allowed` — The key is valid but was created without the scope this endpoint requires. Scopes are set at key creation and are not widened at request time. Next: Create a key carrying the scope named in the message, or use the `all` scope. Each endpoint''s required scope is on its OpenAPI operation as `x-ce-scope`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: '`not_found` — The identifier is well-formed but matches nothing this key may see. Records excluded from the public directory read as absent rather than forbidden, deliberately — a 403 would confirm the row exists. Next: Confirm the identifier against a list or search endpoint before fetching it by id. A record that appears in the product but not here is outside the licensed dataset.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: '`quota_exceeded` — The key has spent every request included in the current calendar month. There is no overage charge and no automatic top-up. Next: Call /api/v1/meta/usage to see the reset date and how the quota was spent, then either wait for the reset at the start of the next calendar month or upgrade the plan. /api/v1/meta/usage does not itself consume quota.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: '`internal_error` — The request was accepted and failed on our side. Next: Retry with exponential backoff (1s, 2s, 4s, up to about 30s). If it persists past a few minutes, check /api/v1/meta/status and contact support with the time of the request.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- name: id
in: path
required: true
description: Vendor organization id.
schema:
type: string
format: uuid
servers:
- url: https://commonelements.com/api/v1
description: Production
- url: https://commonelements.com/api/v1/meta/sandbox
description: Sandbox — fixed dataset, published test key, not metered
/api/v1/vendors/{id}/reviews:
get:
operationId: vendorsReviews
summary: Published reviews for a vendor, newest first
description: 'Published reviews for a vendor, newest first. Every review is tied to a completed RFP or proposal, so each one is a verified-buyer review, not an open review anyone can post.
- Reviewer identity is never included, by design — the reviewing association is withheld to keep the projection neutral.'
tags:
- Vendors
security:
- bearerAuth: []
x-ce-scope: vendors
x-ce-docs-url: https://commonelements.com/developers/docs#vendors-reviews
x-ce-example-request: "curl \"https://commonelements.com/api/v1/vendors/9a71c6b0-4e2f-41d8-8b09-5c3a2d17e604/reviews\" \\\n -H \"Authorization: Bearer ce_live_your_key_here\""
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
required:
- ok
- data
properties:
ok:
type: boolean
const: true
data:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Review id.
rating:
type: number
description: 1 to 5.
body:
type: string
description: Review text.
created_at:
type: string
format: date-time
description: Review lifecycle timestamps.
updated_at:
type: string
format: date-time
description: Review lifecycle timestamps.
additionalProperties: true
additionalProperties: true
examples:
default:
value:
ok: true
data:
- id: f1a2b3c4-5d6e-4f70-8a91-2b3c4d5e6f70
rating: 5
body: Responsive and finished ahead of schedule after the storm.
created_at: '2026-06-02T00:00:00Z'
updated_at: '2026-06-02T00:00:00Z'
vendor_id: 9a71c6b0-4e2f-41d8-8b09-5c3a2d17e604
total: 1
limit: 25
offset: 0
'400':
description: '`validation_error` — A query parameter or body field is missing, malformed, or outside its allowed range. The message names the first parameter that failed. Next: Fix the named parameter and re-send. Every parameter and its accepted values are in the OpenAPI document at /api/v1/openapi; retrying an unchanged request will fail the same way.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: '`invalid_api_key` — No Authorization header, a header that is not `Bearer <key>`, or a key that does not resolve to an active record. Next: Send `Authorization: Bearer ce_live_...`. If the header is correct, the key has been revoked or expired — mint a new one at /settings/api-keys. Keys are shown once at creation and stored only as a hash, so a lost key cannot be recovered.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: '`scope_not_allowed` — The key is valid but was created without the scope this endpoint requires. Scopes are set at key creation and are not widened at request time. Next: Create a key carrying the scope named in the message, or use the `all` scope. Each endpoint''s required scope is on its OpenAPI operation as `x-ce-scope`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: '`not_found` — The identifier is well-formed but matches nothing this key may see. Records excluded from the public directory read as absent rather than forbidden, deliberately — a 403 would confirm the row exists. Next: Confirm the identifier against a list or search endpoint before fetching it by id. A record that appears in the product but not here is outside the licensed dataset.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: '`quota_exceeded` — The key has spent every request included in the current calendar month. There is no overage charge and no automatic top-up. Next: Call /api/v1/meta/usage to see the reset date and how the quota was spent, then either wait for the reset at the start of the next calendar month or upgrade the plan. /api/v1/meta/usage does not itself consume quota.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: '`internal_error` — The request was accepted and failed on our side. Next: Retry with exponential backoff (1s, 2s, 4s, up to about 30s). If it persists past a few minutes, check /api/v1/meta/status and contact support with the time of the request.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
- name: id
in: path
required: true
description: Vendor organization id.
schema:
type: string
format: uuid
- name: limit
in: query
required: false
description: Max results, 1 to 100 (default 25).
schema:
type: number
- name: offset
in: query
required: false
description: Pagination offset (default 0).
schema:
type: number
servers:
- url: https://commonelements.com/api/v1
description: Production
- url: https://commonelements.com/api/v1/meta/sandbox
description: Sandbox — fixed dataset, published test key, not metered
components:
schemas:
Error:
type: object
required:
- ok
- error
- message
properties:
ok:
type: boolean
const: false
error:
type: string
description: Stable machine-readable code. Switch on this, not on the message.
enum:
- validation_error
- invalid_api_key
- scope_not_allowed
- tier_not_allowed
- not_found
- quota_exceeded
- public_record_allowance_exceeded
- not_implemented
- search_timeout
- internal_error
- service_unavailable
message:
type: string
description: Human-readable detail. Wording may change; the code will not.
docs_url:
type: string
format: uri
description: Where this code is explained in full. Present on the meta namespace.
next_steps:
type: string
description: What to do about it. Present on the meta namespace.
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'An API key from /settings/api-keys, sent as `Authorization: Bearer ce_live_...`. Sandbox requests use the published test key documented at /api/v1/meta/sandbox.'
x-refined-from:
- commonelements-com-openapi.json
- commonelements-com-openapi.yml
x-ce-api-version: v1
x-ce-versions:
- version: v1
status: current
released_on: '2026-06-15'
sunset_on: null
note: The only version. No successor is announced, so no sunset date exists to publish; when one does, it appears here and in the Sunset header before anything is removed.
x-ce-compatibility:
- kind: additive
rule: Adding a new endpoint, a new optional query parameter, or a new field to a response object. Parse responses tolerantly; a client that errors on an unrecognised field will break on a change this policy permits.
- kind: additive
rule: Adding a new value to an open enumeration such as `change_kind`, a county-published milestone status, or a vendor category. Handle an unknown value as a passthrough string rather than a parse failure.
- kind: additive
rule: Raising a plan's row cap or quota, or widening a lookback window.
- kind: breaking
rule: Removing or renaming a field, changing a field's type, or changing the meaning of an existing value. Never done inside v1.
- kind: breaking
rule: Removing an endpoint, adding a required parameter to an existing endpoint, or tightening an existing parameter's accepted values.
- kind: breaking
rule: Moving an endpoint behind a higher plan than the one it shipped under. A new endpoint may launch on any plan; an existing one does not move up.
x-ce-deprecation-policy:
- label: 12 months minimum notice
detail: A version is supported for at least 12 months after its successor is generally available. No endpoint inside a supported version is removed during that window.
- label: Announced in three machine-readable places
detail: 'A deprecated operation carries `deprecated: true` in the OpenAPI document, a `Deprecation` and a `Sunset` HTTP header (RFC 8594) on every response, and an entry in the changelog on /developers/status. Poll any one of them; you do not have to read an email to find out.'
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://artifacts.apis.io/commonelements-com/openapi/commonelements-com-vendors-api-openapi.yml