Entities

Entities are the organization profiles at the center of Ring’s product loop: discover or create a profile, invite members, post opportunities, optionally activate a store, and keep discovery fresh after every mutation.

Entities are not a business-directory page bolted on later — they are the primary organization record that opportunities, vendor stores, verification procedures, and Tunnel discovery hang off.

Frequently asked questions

Impact

Will every clone show the same 26 industries?

No. The active catalog comes from entities.preset. Default platform ships 26 industry ids (technologySoftware … other). agricultural swaps in a wellness/farm vertical catalog. Clones can overlay presets via ringdom-clone-build.

Do entities replace LinkedIn company pages?

They are Ring’s native org graph for discovery, opportunities, store, and confidential desks — not a LinkedIn sync product.

Ops

Can visitors see the directory?

Yes. Public, non-confidential entities are listed and viewable without signing in. Everything else still needs an account.

Who can create an entity?

Authenticated users with member privileges (or platform admin / confidential role mapping). Confidential entities require confidential access (canCreateEntity).

How do I delete safely?

DELETE /api/entities/{id} with JSON { "confirm": true }, or the UI delete flow under /entities/[id]/delete. Missing confirm returns 400.

Why is My Entities empty for store?

The Store tab only lists entities where addedBy === currentUser and storeActivated === true. Activate the vendor store first.

Does verification auto-approve?

No. requestEntityVerification opens/submits a verification_procedures record (entity_identity) and sets entity verificationStatus to pending. Review is an ops/admin workflow.

Related documentation

Entities

Entities are the organization profiles at the center of Ring’s product loop: discover or create a profile, invite members, post opportunities, optionally activate a store, and keep discovery fresh after every mutation.

Entities are not a business-directory page bolted on later — they are the primary organization record that opportunities, vendor stores, verification procedures, and Tunnel discovery hang off.

Frequently asked questions

Impact

Will every clone show the same 26 industries?

No. The active catalog comes from entities.preset. Default platform ships 26 industry ids (technologySoftware … other). agricultural swaps in a wellness/farm vertical catalog. Clones can overlay presets via ringdom-clone-build.

Do entities replace LinkedIn company pages?

They are Ring’s native org graph for discovery, opportunities, store, and confidential desks — not a LinkedIn sync product.

Ops

Can visitors see the directory?

Yes. Public, non-confidential entities are listed and viewable without signing in. Everything else still needs an account.

Who can create an entity?

Authenticated users with member privileges (or platform admin / confidential role mapping). Confidential entities require confidential access (canCreateEntity).

How do I delete safely?

DELETE /api/entities/{id} with JSON { "confirm": true }, or the UI delete flow under /entities/[id]/delete. Missing confirm returns 400.

Why is My Entities empty for store?

The Store tab only lists entities where addedBy === currentUser and storeActivated === true. Activate the vendor store first.

Does verification auto-approve?

No. requestEntityVerification opens/submits a verification_procedures record (entity_identity) and sets entity verificationStatus to pending. Review is an ops/admin workflow.

Related documentation

Entities

Entities are the organization profiles at the center of Ring’s product loop: discover or create a profile, invite members, post opportunities, optionally activate a store, and keep discovery fresh after every mutation.

Entities are not a business-directory page bolted on later — they are the primary organization record that opportunities, vendor stores, verification procedures, and Tunnel discovery hang off.

Frequently asked questions

Impact

Will every clone show the same 26 industries?

No. The active catalog comes from entities.preset. Default platform ships 26 industry ids (technologySoftware … other). agricultural swaps in a wellness/farm vertical catalog. Clones can overlay presets via ringdom-clone-build.

Do entities replace LinkedIn company pages?

They are Ring’s native org graph for discovery, opportunities, store, and confidential desks — not a LinkedIn sync product.

Ops

Can visitors see the directory?

Yes. Public, non-confidential entities are listed and viewable without signing in. Everything else still needs an account.

Who can create an entity?

Authenticated users with member privileges (or platform admin / confidential role mapping). Confidential entities require confidential access (canCreateEntity).

How do I delete safely?

DELETE /api/entities/{id} with JSON { "confirm": true }, or the UI delete flow under /entities/[id]/delete. Missing confirm returns 400.

Why is My Entities empty for store?

The Store tab only lists entities where addedBy === currentUser and storeActivated === true. Activate the vendor store first.

Does verification auto-approve?

No. requestEntityVerification opens/submits a verification_procedures record (entity_identity) and sets entity verificationStatus to pending. Review is an ops/admin workflow.

Related documentation

Typical scenarios

• Local business ring — SMBs create public entities, invite staff, post local opportunities.
• Confidential partner desk — elevated roles create visibility: confidential entities for restricted collaboration (/confidential/entities).
• Vendor onboarding — entity owner activates store; My Entities Store tab surfaces those profiles.
• Vertical clone — set entities.preset to agricultural (or a clone overlay preset) so industry pickers match the niche instead of the default 26 platform industries.

Operator checklist

1. Confirm clone entities.preset in ring-config.json (empire org overlay uses platform).
2. Ensure creators have member (or higher) platform role — confidential create needs confidential access.
3. Walk /entities/add → profile → optional verify + invite → post first opportunity.
4. Use /entities/my to separate owned, store-enabled, and membership views.

Empire overlay (ring-platform-org) does not fork entity services in web/ for this feature — compose Layer1; locales/config may overlay via merge.

App routes

REST surface

MCP mirrors: /api/mcp/v1/entities, /api/mcp/v1/entities/search, /api/mcp/v1/entities/{id}.

Visibility ladder

Discovery filters use platform roles (visitor → admin). Confidential rows require hasConfidentialAccess. Setting visibility: confidential or isConfidential: true on create/update is gated the same way.

Create via service

1. 1

   Authenticate as a user who may create entities (canCreateEntity — member+; confidential create needs confidential access).

2. 2

   Call the service (or POST /api/entities/create). Required shape centers on name, type, descriptions, addedBy, locale, location, visibility, members, opportunities.

3. 3

   After mutations, rely on syncEntityDiscovery — do not invent a separate search-index table; PostgreSQL JSONB is SSOT.

Invite & verify

Guest reads

GET /api/entities and the /entities page resolve anonymous callers to role visitor. getEntityById no longer throws for guests on public rows; non-public rows still require a session. Creating an entity as a guest redirects to login with callbackUrl back to /entities/add.

Analytics payload

GET /api/entities/{id}/analytics returns EntityAnalytics: member count, opportunity id list length, linked opportunities (organizationId count), verification / moderation fields, optional storeMetrics / storeVerification, and generatedAt.

See-also: role ladder and confidential access patterns that gate entity visibility.

Typical scenarios

• Local business ring — SMBs create public entities, invite staff, post local opportunities.
• Confidential partner desk — elevated roles create visibility: confidential entities for restricted collaboration (/confidential/entities).
• Vendor onboarding — entity owner activates store; My Entities Store tab surfaces those profiles.
• Vertical clone — set entities.preset to agricultural (or a clone overlay preset) so industry pickers match the niche instead of the default 26 platform industries.

Operator checklist

1. Confirm clone entities.preset in ring-config.json (empire org overlay uses platform).
2. Ensure creators have member (or higher) platform role — confidential create needs confidential access.
3. Walk /entities/add → profile → optional verify + invite → post first opportunity.
4. Use /entities/my to separate owned, store-enabled, and membership views.

Empire overlay (ring-platform-org) does not fork entity services in web/ for this feature — compose Layer1; locales/config may overlay via merge.

App routes

REST surface

MCP mirrors: /api/mcp/v1/entities, /api/mcp/v1/entities/search, /api/mcp/v1/entities/{id}.

Visibility ladder

Discovery filters use platform roles (visitor → admin). Confidential rows require hasConfidentialAccess. Setting visibility: confidential or isConfidential: true on create/update is gated the same way.

Create via service

1. 1

   Authenticate as a user who may create entities (canCreateEntity — member+; confidential create needs confidential access).

2. 2

   Call the service (or POST /api/entities/create). Required shape centers on name, type, descriptions, addedBy, locale, location, visibility, members, opportunities.

3. 3

   After mutations, rely on syncEntityDiscovery — do not invent a separate search-index table; PostgreSQL JSONB is SSOT.

Invite & verify

Guest reads

GET /api/entities and the /entities page resolve anonymous callers to role visitor. getEntityById no longer throws for guests on public rows; non-public rows still require a session. Creating an entity as a guest redirects to login with callbackUrl back to /entities/add.

Analytics payload

GET /api/entities/{id}/analytics returns EntityAnalytics: member count, opportunity id list length, linked opportunities (organizationId count), verification / moderation fields, optional storeMetrics / storeVerification, and generatedAt.

See-also: role ladder and confidential access patterns that gate entity visibility.

Typical scenarios

• Local business ring — SMBs create public entities, invite staff, post local opportunities.
• Confidential partner desk — elevated roles create visibility: confidential entities for restricted collaboration (/confidential/entities).
• Vendor onboarding — entity owner activates store; My Entities Store tab surfaces those profiles.
• Vertical clone — set entities.preset to agricultural (or a clone overlay preset) so industry pickers match the niche instead of the default 26 platform industries.

Operator checklist

1. Confirm clone entities.preset in ring-config.json (empire org overlay uses platform).
2. Ensure creators have member (or higher) platform role — confidential create needs confidential access.
3. Walk /entities/add → profile → optional verify + invite → post first opportunity.
4. Use /entities/my to separate owned, store-enabled, and membership views.

Empire overlay (ring-platform-org) does not fork entity services in web/ for this feature — compose Layer1; locales/config may overlay via merge.

App routes

REST surface

MCP mirrors: /api/mcp/v1/entities, /api/mcp/v1/entities/search, /api/mcp/v1/entities/{id}.

Visibility ladder

Discovery filters use platform roles (visitor → admin). Confidential rows require hasConfidentialAccess. Setting visibility: confidential or isConfidential: true on create/update is gated the same way.

Create via service

1. 1

   Authenticate as a user who may create entities (canCreateEntity — member+; confidential create needs confidential access).

2. 2

   Call the service (or POST /api/entities/create). Required shape centers on name, type, descriptions, addedBy, locale, location, visibility, members, opportunities.

3. 3

   After mutations, rely on syncEntityDiscovery — do not invent a separate search-index table; PostgreSQL JSONB is SSOT.

Invite & verify

Guest reads

GET /api/entities and the /entities page resolve anonymous callers to role visitor. getEntityById no longer throws for guests on public rows; non-public rows still require a session. Creating an entity as a guest redirects to login with callbackUrl back to /entities/add.

Analytics payload

GET /api/entities/{id}/analytics returns EntityAnalytics: member count, opportunity id list length, linked opportunities (organizationId count), verification / moderation fields, optional storeMetrics / storeVerification, and generatedAt.

See-also: role ladder and confidential access patterns that gate entity visibility.