# Businesses (/docs/api-reference/businesses)



Every business keeps one stable SMB business ID. A workspace adds private context and permissions without creating a second identity for the same business.

<Cards>
  <Card title="Search Businesses" href="/docs/api-reference/search_businesses" description="Search published Businesses by name and status." />

  <Card title="List Workspace Businesses" href="/docs/api-reference/search_workspace_businesses" description="List the Businesses you can access in one Workspace, with an optional name filter." />

  <Card title="Get a Business" href="/docs/api-reference/get_business" description="Open one Business and the information SMB can return." />

  <Card title="Add a Business" href="/docs/api-reference/add_business" description="Add a new Business and optionally connect it to a Workspace." />

  <Card title="Update a Business" href="/docs/api-reference/update_business" description="Update the permitted information for one Business." />
</Cards>

## List Businesses in a Workspace [#list-businesses-in-a-workspace]

Use `GET /v1/workspaces/{workspace_id}/businesses` to discover the Businesses you can access in a Workspace. This includes unpublished Businesses and the Workspace's private observations. Each request checks your current permissions and requires `businesses:read`.

Send a signed-in user's access token or a Workspace API key. The `SMB-Workspace-Id` header must match the Workspace ID in the URL.

```bash
curl "https://api-staging.smb.co/v1/workspaces/$WORKSPACE_ID/businesses?limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "SMB-Workspace-Id: $WORKSPACE_ID"
```

For a Workspace API key, replace the `Authorization` header with `X-SMB-API-Key: $SMB_API_KEY`.

* Omit `name` to list all accessible Businesses, one page at a time.
* Add `name=Acme` to filter by name. Supplied names must contain 3–200 characters after trimming surrounding spaces.
* `limit` defaults to 20 and accepts 1–100.
* When `page.has_more` is `true`, pass `page.cursor` as the next request's `cursor`, keeping the same Workspace and filter. Stop when `page.has_more` is `false`.

```bash
curl --get "https://api-staging.smb.co/v1/workspaces/$WORKSPACE_ID/businesses" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "SMB-Workspace-Id: $WORKSPACE_ID" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

Results use stable Business ID order. Permissions are checked again for every page, so access changes take effect on subsequent requests. An empty page means no accessible Businesses matched; it does not establish that the Workspace has no other Businesses. This operation is available through HTTP; it is not currently a standalone MCP tool.

See [Business Data](/docs/business-data) for the customer-facing field guide.

### Saved logos [#saved-logos]

Each workspace business may include `logo_url`, a saved HTTP(S) logo URL from that workspace's business information. It is `null` when no logo is saved or the value is invalid. Use it as the business image and keep a fallback for missing or failed images.

A saved workspace logo is private context. It does not publish a canonical Brand, grant access to a different workspace, or provide a link to a legacy SMB profile page. Location, website and industry fields retain their existing workspace scope. The endpoint does not fetch or invent logos.