Entity Resource

Manage custom entities (tables) in your tenant's data model. Every custom entity is stored with a __c suffix on its Name. Send the plain name on create; the platform appends __c and returns the entity's new ID.

See the Entity Management API Overview for authentication, permission requirements, and response shape.

Create an Entity

POST /api/3.0/entity/Entity
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "Name": "SampleContract",
  "Label": "Sample Contract",
  "PluralLabel": "Sample Contracts",
  "NameFieldLabel": "Contract Name"
}

Successful response returns the new entity ID:

{ "id": "7NS0000000000A50001", "errors": [], "success": true }

Save the returned id; you need it as EntityId on every EntityField call that adds columns to this entity.

Object vs Person entity

Set Type to 1 to create a Person entity (built-in name-part fields, contact-style attributes). Default is 0 (Object). No other values are accepted.

{
  "Name": "SampleApplicant",
  "Label": "Sample Applicant",
  "PluralLabel": "Sample Applicants",
  "Type": 1
}

Auto-numbered Name field

To make the entity's built-in Name field an auto-number instead of free text, set IsAutoNumber = true and supply AutoNumberFormat, StartingNumber, and AutoIncrement:

{
  "Name": "Invoice",
  "Label": "Invoice",
  "PluralLabel": "Invoices",
  "IsAutoNumber": true,
  "AutoNumberFormat": "INV-{0:0000}",
  "StartingNumber": 1000,
  "AutoIncrement": 1
}

The format uses exactly one {0:0+} counter token — for example INV-{0:0000} yields INV-1000, INV-1001, and so on. The token must include the 0: prefix; formats such as INV-{0000} are rejected as invalid.

Payload Reference

System-assigned; do not send:Id, KeyPrefix, Code. Schema is technically writable but restricted to internal values (standard, schema, system, Force, DynamicsCrm); leave it unset to default to standard.

EntityOptions

Standard Fields Provisioned Automatically

Every entity ships with these system-managed fields; you do not create them:

• Id — 19-character record identifier (first three characters are the entity's KeyPrefix).
• Name — the display name (auto-number when IsAutoNumber = true).
• OwnerId — Lookup to the User who owns the record.
• CreatedById, CreatedOn, ModifiedById, ModifiedOn — audit fields (UTC).
• IsDeleted — soft-delete flag.

Get an Entity

Retrieve one entity by ID:

GET /api/3.0/entity/Entity/<entity id>
Authorization: Bearer <token>
Accept: application/json

Retrieve one entity's metadata (fields, layouts, and other schema data returned by the platform):

GET /api/3.0/entity/Entity/<entity id>/metadata
Authorization: Bearer <token>
Accept: application/json

Retrieve metadata for many entities in one call:

GET /api/3.0/entity/metadata?entities=Account,Contact,Invoice__c
Authorization: Bearer <token>
Accept: application/json

List Entities

GET /api/3.0/entity/Entity?limit=100&sort=Name
Authorization: Bearer <token>
Accept: application/json

Supports the same query-string filters, fields, sort, order, limit, and offset parameters as the record-CRUD API. See Read records.

Update an Entity

PATCH /api/3.0/entity/Entity/<entity id>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "Label": "Renamed Contract",
  "Description": "Contracts issued to customers after negotiation",
  "EntityOptions": { "TrackFeeds": true, "AllowReports": true }
}

Editable after creation:Label, PluralLabel, Description, NameFieldLabel, StartsWithVowel, IsReadOnly, and EntityOptions.*.

Immutable:Name, KeyPrefix, Code, Schema, Type. Once the entity is created, these cannot be changed via PATCH.

Delete an Entity

DELETE /api/3.0/entity/Entity/<entity id>
Authorization: Bearer <token>

Deletion is destructive — it drops the underlying table, not just the metadata. All records in the entity are removed and cannot be recovered. Fields on the entity, layouts, list layouts, and buttons that reference the entity are also removed.

Add ?isPermanent=true to bypass the recycle bin. Without it, the entity is soft-deleted and can be restored by a Host user via the platform Recycle Bin.

Status Codes

<< Entity Management API Overview | EntityField Resource >>