Common Elements Vendors API

The Vendors API from Common Elements — 3 operation(s) for vendors.

GitHub OpenAPI

Operations 3

GET /api/v1/vendors Search the public vendor directory: verified vendors only, ranked by review… #
GET /api/v1/vendors/{id} The full public profile for one verified vendor: identity, self-reported… #
GET /api/v1/vendors/{id}/reviews Published reviews for a vendor, newest first #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/commonelements-com:commonelements-com-vendors-api"
All apis
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.

Get an API 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 Specification

commonelements-com-vendors-api-openapi.yml Raw ↑
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