---
title: "Entity Type"
section: "API Reference"
route: /apientitytype
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Entity Type

Entity Types are used to categorize and describe Entities.

For example you make a generic category 'Building' and describe what attributes you'd like any building in your account to have.
Attributes such as 'Name', 'Address', 'Owner', etc.

Entities must be assigned an Entity Type ID.

## Data model

Below is a basic data model for an Entity Type record.

When further documentation refers to `IEntityType` or just an Entity Type record, you can reference this data model.

```typescript
interface IEntityType {
    // ID of the Entity Type.
    ID?: string;
    // Human readable name of the Entity Type.
    Name: string;
    // Description of the Entity Type.
    Description?: string;
    // An Entity record used for default values.
    Data?: Entity.IEntity;
    // If entity type access (and entity access) should be restricted.
    // When an entity type is restricted a user must have the "EntityType_<typeId>" permission.
    IsAccessRestricted?: boolean;
    // The data schema defining expected attributes for Entities to have.
    DataSchema?: IDataSchema; // See 'Entity Type: Data Schema' documentation.
    // Default Style for the corresponding Entities.
    "DisplaySetting.ID"?: number;
    // Created/updated date/time in ISO 8601 UTC.
    Created: string;
    Updated: string;
    // ID of the parent Entity Type.
    // This is used for organization.
    // When a parent type is deleted, the child types are also deleted.
    "Parent.EntityType.ID"?: string;
}
```

## Entity Type requests.

Below are the basic requests for managing Entity Type records.

### Get Entity Types

```http
GET https://{accountId}.api.nextspace.host/entitytypes?typeId=type_id&parentEntityTypeID=type_id&expandSettings=true/false&search=text
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `typeId=type_id` | query | no | Filter for a specific Entity Type ID. Include multiple times to filter for multiple Entity Type IDs. Eg: typeId=1&typeId=2 |
| `parentEntityTypeID=type_id` | query | no | Filter for Entity Types with a specific Parent Entity Type ID. Pass 'IS_NULL' to filter for Entity Types without a parent. |
| `expandSettings=true/false` | query | no | If the response should include expanded settings such as the Data Schema. This is discouraged unless you have a strict filter. |
| `search=text` | query | no | Search for Entity Types by name or description. |

**Response**

```typescript
interface IResponse {
    Items: IEntityType[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entitytypes";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

When requesting a list of Entity Types with any filter, the parent Entity Types are included in the response.

### Get Entity Type by ID

```http
GET https://{accountId}.api.nextspace.host/entityType/{type_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{type_id}` | path | yes | Entity Type ID to retrieve the record for. |

**Response**

```typescript
// Response is the Entity Type record directly.
// Refer to the IEntityType description at the top.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{type_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Create/Update Entity Type

```http
POST https://{accountId}.api.nextspace.host/entityType/{type_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{type_id}` | path | yes | Entity Type ID to create or update. |

**Response**

```typescript
// Body is the Entity Type record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{type_id}";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete Entity Type

```http
DELETE https://{accountId}.api.nextspace.host/entityType/{type_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{type_id}` | path | yes | Entity Type ID to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{type_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

Deleting an Entity Type will also delete all Entities of that type, and all child Entity Types (recursively).

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apientitytype