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

An Entity Attachment is a linking record between a Client File and Entity. Attachments have corresponding Attachment Type records which let you define a level of categorization.

Some Attachment Types are used for our default panels, for example the Attachment Type "photo" will display the files in the "Media" tab when selecting Entities in Navigator.

You will find other Attachment Types appear under the 'Attachments' Selected Entity tab in Navigator. They will appear as folders of related Client Files.

## Attachment Types requests

Below are the basic requests for managing Attachment Type records.

### Get Attachment Types

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

**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. |

**Response**

```typescript
interface IResponse {
    Items: {
        // Attachment type description.
        Description: string;
        // Attachment type ID.
        ID: Type;
        // Human readable attachment type name.
        Name: string;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityAttachmentTypes";
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);
});
```

### Get Attachment Type by ID

```http
GET https://{accountId}.api.nextspace.host/entityAttachmentType/{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>".

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

**Response**

```typescript
interface IResponse {
    // Attachment type description.
    Description: string;
    // Attachment type ID.
    ID: Type;
    // Human readable attachment type name.
    Name: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityAttachmentType/{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 Attachment Type

```http
POST https://{accountId}.api.nextspace.host/entityAttachmentType/{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 | Attachment Type ID to create or update. |

**Response**

```typescript
interface IRequest {
    // Attachment type description.
    Description: string;
    // Attachment type ID.
    ID: Type;
    // Human readable attachment type name.
    Name: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityAttachmentType/{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 Attachment Type

```http
DELETE https://{accountId}.api.nextspace.host/entityAttachmentType/{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 | Attachment Type ID to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityAttachmentType/{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);
});
```

## Get Entity Attachments

You can only request the full list of attachments as we haven't had a need to filter them.
This will likely change in the future.

### Get Entity Attachments

```http
GET https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments
```

**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. |
| `{entity_id}` | path | yes | Entity ID to retrieve attachments for. |

**Response**

```typescript
interface IResponse {
    Items: {
        // Attachment ID.
        ID: number;
        // Associated Client File record.
        ClientFile?: ClientFile.IFile;
        // Associated Client File ID.
        "ClientFile.ID": string;
        // Display order among sibling attachments.
        DisplayOrder?: number;
        // Entity this attachment is associated with.
        "Entity.ID": string;
        // Attachment type ID.
        "EntityAttachmentType.ID": Type;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments";
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);
});
```

## Update display order

If you have the need to re-order attachments so that certain ones appear first, you can use this request.
This order is tied to the Entity ID and Attachment Type ID.

### Update display order

```http
POST https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments/{type_id}/setOrder
```

**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. |
| `{entity_id}` | path | yes | Entity ID to retrieve attachments for. |
| `{type_id}` | path | yes | Attachment Type ID to set order for. |

**Request body**

```typescript
interface IRequest {
    // Array of Client Files to update display order for.
    // These should be in the desired order.
    "ClientFile.ID": string[];
    // The starting display order for the first Client File when updating.
    // Typically this is 0.
    "DisplayOrder.Start": number;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments/{type_id}/setOrder";
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 Attachments

Deleting Attachments does not delete the corresponding Client File records, it only unlinks them from the Entity.

### Delete Entity Attachments

```http
POST https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments/{type_id}/delete
```

**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. |
| `{entity_id}` | path | yes | Entity ID to delete (unlink) attachments for. |
| `{type_id}` | path | yes | Attachment Type ID to filter for. |

**Request body**

```typescript
interface IRequest {
    // Array of the related Client File IDs we want to unlink from the Entity.
    "ClientFile.ID": string[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments/{type_id}/delete";
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);
});
```

## Create / update Entity Attachments

You can request an array of Attachments to update or create the links to an Entity.
It is recommended to read the [Client and temp files](/apiclientfile) documentation first.

### Update Entity Attachments

```http
POST https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments
```

**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. |
| `{entity_id}` | path | yes | Entity ID to delete (unlink) attachments for. |

**Request body**

```typescript
interface IRequest {
    "attachments": {
        // Associated Client File ID.
        "ClientFile.ID": string;
        // Display order among sibling attachments.
        DisplayOrder?: number;
        // Entity this attachment is associated with.
        "Entity.ID": string;
        // Attachment type ID.
        "EntityAttachmentType.ID": Type;
    }[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entity/{entity_id}/attachments";
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);
});
```

---

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/apientityattachment