---
title: "Entities"
description: "Entities documentation for Ring Platform"
locale: "en"
---
# Entities API

Manage organizations and businesses with **11 endpoints** for comprehensive entity management, including role-based access control and industry-specific features.

## Overview

Entities represent organizations, businesses, and professional groups within the Ring Platform ecosystem.

**Key Features:**
- Industry types with visual icons
- Verification badge system
- Confidential entity protection
- Role-based access control

## API Endpoints

### `GET /api/entities`
List entities with role-aware filtering and pagination (`limit`, `startAfter`).

### `POST /api/entities/create`
Create a new entity (authenticated; requires sufficient role).

### `GET /api/entities/{id}`
Get entity details by ID.

### `PUT /api/entities/{id}`
Full update entity fields (owner or `ADMIN`).

### `PATCH /api/entities/{id}`
Partial update with validated fields (`name`, `type`, `shortDescription`, `visibility`, `isConfidential`, plus passthrough). Canonical update path — replaces legacy `PATCH /api/entities/update/{id}`.

### `DELETE /api/entities/{id}`
Hard-delete entity. Requires session cookie and JSON body `{ "confirm": true }`. Owner or `ADMIN` (see `delete-entity` service). Prefer the **Server Action** flow from `/entities/{id}/delete` for in-app UI.

### `POST /api/entities/{id}/verify`
Queue entity for platform verification review (owner or `ADMIN`). Sets `verificationStatus: 'pending'` and records `entity_verification_requests`. Returns `202` when accepted.

### `POST /api/entities/{id}/invite`
Invite an existing platform user to the entity by email. Appends their user id to `members` and sends an in-app notification. Body: `{ "email": "user@example.com", "role": "member" }` (`role` is informational today).

### `GET /api/entities/{id}/analytics`
Entity performance snapshot for owners, entity members, or `ADMIN`: member count, linked opportunities, `storeMetrics`, verification state.

### `POST /api/entities/upload`
Upload entity media assets.

Create/update/delete in the UI still prefer **Server Actions** (`app/_actions/entities.ts`). REST routes above are for API clients and integrations.

## Data model

API and server services expose **`SerializedEntity`** — date fields as ISO strings. Types live in `features/entities/types`.

{`interface SerializedEntity {
  id: string
  name: string
  type: EntityType          // e.g. 'technologySoftware'
  shortDescription: string
  fullDescription?: string
  addedBy: string
  dateAdded: string         // ISO 8601
  lastUpdated: string
  memberSince?: string
  location: string
  locale: string
  visibility: 'public' | 'subscriber' | 'member' | 'confidential'
  isConfidential: boolean
  members: string[]
  opportunities: string[]
  services?: string[]
  industries?: string[]
  tags?: string[]
  // …see features/entities/types/index.ts
}`}

### PostgreSQL mapping

`DatabaseService` query rows map through `mapDbQueryRowToSerializedEntity()` in `features/entities/lib/entity-db-mapper.ts`. Do **not** use `lib/converters/entity-converter.ts` on the Postgres path — it is a **Firestore-only legacy** `FirestoreDataConverter`.

### Post-mutation discovery sync

Creates, updates, and deletes call `syncEntityDiscovery()`:

1. **`revalidateTag`** — `invalidateEntitiesCache` (`lib/cached-data.ts`)
2. **`revalidatePath`** — `/[locale]/entities`, `/[locale]/entities/[id]`, `/[locale]/entities/my`, `/entities` on create
3. **Tunnel** — `syncDiscovery({ channel: 'entities', … })` → `entity:created|updated|deleted`

See [Discovery mutation sync](../architecture/discovery-mutation-sync).

### My Entities page

Authenticated members use **`/[locale]/entities/my`** (`ROUTES.MY_ENTITIES`). Data loads via `getMyEntities()` in `features/entities/services/get-user-entities.ts` with tab views: `all` (owned), `store`, `member`.

## Industry Types

Ring Platform supports **26 industry types**:

- Technology & Software
- Healthcare & Medical
- Finance & Banking
- Education & Training
- Manufacturing & Industrial
- Retail & E-commerce
- Real Estate & Construction
- Media & Entertainment
- Transportation & Logistics
- Energy & Utilities
- Agriculture & Food
- Legal & Professional Services
- Non-profit & Social Impact
- Government & Public Sector
- Consulting & Business Services
- Marketing & Advertising
- Design & Creative
- Sports & Recreation
- Travel & Hospitality
- Automotive
- Aerospace & Defense
- Biotechnology & Pharmaceuticals
- Environmental & Sustainability
- Mining & Resources
- Telecommunications
- Other

## Implementation Examples

### Create Entity

```typescript
const response = await fetch('/api/entities/create', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Tech Innovators Inc',
    type: 'technologySoftware',
    shortDescription: 'Leading software development company',
    location: 'San Francisco, CA',
  }),
})

const { entity } = await response.json()
```

### List Entities with Filtering

{`const response = await fetch('/api/entities?limit=10', { credentials: 'include' })
const { entities, lastVisible } = await response.json()`}

### Get Entity Details

```typescript
const response = await fetch(`/api/entities/${entityId}`)
const entity = await response.json()

if (entity.confidential && !hasConfidentialAccess) {
  // Handle confidential entity access
}
```

## Access Control

### Entity Visibility
- **Public Entities**: Visible to all users
- **Confidential Entities**: Require CONFIDENTIAL role or higher

### Entity Management
- **Create**: Requires MEMBER role
- **Update**: Entity members with admin role
- **Delete**: Platform admin only
- **Verify**: Special verification process

### Member Roles
- **OWNER**: Full entity control
- **ADMIN**: Manage members and content
- **MEMBER**: Basic entity access

## Verification Process

Entities can request verification badges:

1. Submit verification request
2. Provide required documentation
3. Platform review process
4. Verification badge granted

**Benefits of Verification:**
- Enhanced credibility
- Priority in search results
- Access to premium features
- Confidential entity creation

---

*Ready to create your first entity? Check our [Getting Started](/en/docs/getting-started) guide.*