---
title: "Import JSON"
section: "API Reference"
route: /apiimportjson
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Import JSON

You can mimic the import functionality you see in Operator by making your own import process for JSON files.

We'll assume you know how to upload files through the API and that you have access to a `TempFile.ID` or `ClientFile.ID`.

As JSON is a very flexible format, here is an example of the expected file content:

```json
[
    {
        "name": "thing1",
        "description": "This is a thing."
    },
    {
        "name": "thing2",
        "description": "This is another thing."
    },
    {
        "name": "thing3",
        "description": "This is yet another thing."
    }
]
```

## Import

### JSON Import

```http
POST https://{accountId}.api.nextspace.host/import/json
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- 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. |

**Request body**

```typescript
interface IPostBody {
    // Previously uploaded temp file ID or Client File ID.
    // One of these is required.
    "TempFile.ID": string;
    // File name used for creating an import record.
    // Eg: 'my-file.json'.
    // If you specify a Client File ID, this is not needed as the name is already known.
    "TempFile.Name": string;
    "ClientFile.ID": string;

    // Specifies how the features should be imported.
    // Eg: 'A' for add, 'U' for update, 'R' for replace (delete before importing).
    // You can also use 'U+A' to update or add (our default).
    // Or 'U+A+D' to update or add, then delete any Entities not in the JSON.
    // These are all relative to the specified Entity Type.
    "ImportMode": "A" | "U" | "R" | "U+D" | "U+A" | "U+D+A";
    // Set to true to skip features that fail to import.
    // If false, the first failure will stop the import.
    "SkipFailedFeatures"?: boolean;

    // Destination Entity Type.
    "EntityType.ID": string;
    // Array of Nextspace Tag IDs to apply to all imported Entities.
    "AddLayerIDs"?: number[];

    // Data mapping for the JSON properties to the target Entity Type schema.
    "DataMapping": any;
}
```

**Example request body**

```json
{
    "TempFile.ID": "blah-abc",
    "TempFile.Name": "my-file.json",
    "ImportMode": "U+A",
    "SkipFailedFeatures": true,
    "EntityType.ID": "123",
    "DataMapping": {}
}
```

**Response**

```typescript
interface IResponse {
    "PendingActionID": number;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/import/json";
const method = "post";
const token = "your-token";
const body = {
    "TempFile.ID": "blah-abc",
    "TempFile.Name": "my-file.json",
    "ImportMode": "U+A",
    "SkipFailedFeatures": true,
    "EntityType.ID": "123",
    "DataMapping": {}
};

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 the Pending Action is marked as completed, here is the result to expect:

```typescript
interface IResult {
    // Number of failed to import features.
    "CountFailed": number;
    // Number of successfully imported features.
    "CountImported": number;
}
```

---

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