Entities

Entities are the core data objects in Sphere. Each entity is an instance of a family (schema) and stores its data using an Entity-Attribute-Value (EAV) model. Entities can be filtered, sorted, searched, and linked together via relations.

Write operations (create, update, delete) are processed through the intentions system. When you POST or PATCH an entity, you are submitting an intention that gets processed into events. See the Intentions page for details on the CQRS write path.

GET/core/api/v1/entities

List entities

Retrieve a paginated list of entities, optionally filtered by family, field values, and search terms.

Query parameters

Name
family
Type
string
Description
Filter by family code (e.g. contact, company). Required in most use cases.
Name
page
Type
integer
Description
The page number to retrieve. Defaults to 1.
Name
per_page
Type
integer
Description
Number of entities per page. Defaults to 15, maximum 100.
Name
search
Type
string
Description
Full-text search across searchable fields.
Name
sort
Type
string
Description
Field code to sort by (e.g. first_name, created_at).
Name
direction
Type
string
Description
Sort direction: asc or desc. Defaults to asc.
Name
filters[field]
Type
string
Description
Filter by field value. Use the field code as the key (e.g. filters[industry]=Technology).

GET

/core/api/v1/entities

curl -G https://your-sphere.example.com/core/api/v1/entities \
  -H "Authorization: Bearer {token}" \
  -d family=contact \
  -d sort=last_name \
  -d direction=asc \
  -d page=1 \
  -d per_page=20

Response

{
  "data": [
    {
      "id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "family_code": "contact",
      "fields": {
        "first_name": "Alice",
        "last_name": "Martin",
        "email": "alice@example.com",
        "phone": "+33 6 12 34 56 78"
      },
      "status": "active",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-10T14:00:00Z"
    },
    {
      "id": "ent-2b3c4d5e-6f7a-8901-bcde-f12345678901",
      "family_code": "contact",
      "fields": {
        "first_name": "Bob",
        "last_name": "Dupont",
        "email": "bob@example.com",
        "phone": null
      },
      "status": "new",
      "created_at": "2026-02-01T09:00:00Z",
      "updated_at": "2026-02-01T09:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 94
  }
}

GET/core/api/v1/entities/{id}

Get entity

Retrieve a single entity by its unique identifier, including all field values and metadata.

Path parameters

Name
id
Type
string
Description
The unique identifier of the entity.

GET

/core/api/v1/entities/{id}

curl https://your-sphere.example.com/core/api/v1/entities/ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "family_code": "contact",
    "fields": {
      "first_name": "Alice",
      "last_name": "Martin",
      "email": "alice@example.com",
      "phone": "+33 6 12 34 56 78",
      "company": "ent-9f8e7d6c-5b4a-3210-fedc-ba0987654321"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-10T14:00:00Z"
  }
}

POST/core/api/v1/entities

Create entity

Create a new entity by submitting a creation intention. The entity will be created with the specified family and field values. Required fields (as defined by the family schema) must be provided.

Request body

Name
family
Type
string
Description
The family code for the new entity (e.g. contact, company).
Name
fields
Type
object
Description
An object mapping field codes to their values. Required fields must be included.
Name
status
Type
string
Description
Initial status for the entity. Must be a valid status from the family's pipeline. Defaults to the first status.

POST

/core/api/v1/entities

curl -X POST https://your-sphere.example.com/core/api/v1/entities \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "family": "contact",
    "fields": {
      "first_name": "Charlie",
      "last_name": "Bernard",
      "email": "charlie@example.com",
      "phone": "+33 6 98 76 54 32"
    }
  }'

Response

{
  "data": {
    "id": "ent-3c4d5e6f-7a8b-9012-cdef-234567890abc",
    "family_code": "contact",
    "fields": {
      "first_name": "Charlie",
      "last_name": "Bernard",
      "email": "charlie@example.com",
      "phone": "+33 6 98 76 54 32"
    },
    "status": "new",
    "created_at": "2026-02-20T14:30:00Z",
    "updated_at": "2026-02-20T14:30:00Z"
  }
}

PATCH/core/api/v1/entities/{id}

Update entity

Update an existing entity by submitting an update intention. Only the provided fields will be modified; omitted fields remain unchanged.

Path parameters

Name
id
Type
string
Description
The unique identifier of the entity to update.

Request body

Name
fields
Type
object
Description
An object mapping field codes to their new values. Only include fields you want to change.
Name
status
Type
string
Description
New status for the entity. Must be a valid status from the family's pipeline.

PATCH

/core/api/v1/entities/{id}

curl -X PATCH https://your-sphere.example.com/core/api/v1/entities/ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "email": "alice.martin@newdomain.com",
      "phone": "+33 6 00 00 00 00"
    },
    "status": "active"
  }'

Response

{
  "data": {
    "id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "family_code": "contact",
    "fields": {
      "first_name": "Alice",
      "last_name": "Martin",
      "email": "alice.martin@newdomain.com",
      "phone": "+33 6 00 00 00 00",
      "company": "ent-9f8e7d6c-5b4a-3210-fedc-ba0987654321"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T15:00:00Z"
  }
}

DELETE/core/api/v1/entities/{id}

Delete entity

Delete an entity by its unique identifier. This submits a deletion intention that removes the entity and its associated relations.

Path parameters

Name
id
Type
string
Description
The unique identifier of the entity to delete.

DELETE

/core/api/v1/entities/{id}

curl -X DELETE https://your-sphere.example.com/core/api/v1/entities/ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Entity deleted successfully"
}

GET/core/api/v1/entities/by-user/{authUserId}

Find entity by user

Look up an entity that is linked to a specific auth user ID. This is useful for finding the entity representation of a user (e.g. a contact entity associated with their account).

Path parameters

Name
authUserId
Type
string
Description
The auth user UUID to look up.

GET

/core/api/v1/entities/by-user/{authUserId}

curl https://your-sphere.example.com/core/api/v1/entities/by-user/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "family_code": "contact",
    "fields": {
      "first_name": "Alice",
      "last_name": "Martin",
      "email": "alice@acme.com"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-10T14:00:00Z"
  }
}

GET/core/api/v1/users/by-auth-id/{authUserId}

Find user entity by auth ID

Find a user entity by its auth user ID. This performs a tenant-wide lookup and returns the entity matching the given auth user, regardless of workspace context. This endpoint is typically used for profile updates.

Path parameters

Name
authUserId
Type
string
Description
The auth user UUID to look up.

GET

/core/api/v1/users/by-auth-id/{authUserId}

curl https://your-sphere.example.com/core/api/v1/users/by-auth-id/9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "family_code": "user",
    "auth_user_id": "9e1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "fields": {
      "first_name": "Alice",
      "last_name": "Martin",
      "email": "alice@acme.com"
    },
    "status": "active",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-10T14:00:00Z"
  }
}