---
title: "Create an instance"
method: POST
path: "/instances"
tags: ["Private"]
---

# Create an instance

`POST /instances`

## Request

- Base URL: `https://api.beta.ons.gov.uk/v1`
- URL: `https://api.beta.ons.gov.uk/v1/instances`
- Auth: API key in header `Authorization`

Create an instance which will be imported. To create an instance an import job id and href is required. This is to allow a link back to the import job

## Request body

- NewInstance: A model for the request and response body for creating a new instance
  - `dimensions` Codelist[]: A list of codelists for each dimension of this instance
    - `href` string: A link to the codelist corresponding to this dimension
    - `id` string: The codelist id corresponding to this dimension
    - `name` string: The dimension name
    - `description` string: The dimension description
    - `label` string: A human readable label for dimension
  - `id` string: A unique id for an instance
  - `import_tasks` ImportTasks
    - `build_hierarchies` object[]
      - `code_list_id` string: The ID of the codelist that this hierarchy represents
      - `dimension_name` string: The name of the dimension the hierarchy represents
      - `state` string: The state of the import observations task
    - `build_search_indexes` object[]
      - `dimension_name` string: The name of the dimension the search index represents
      - `state` string: The state of the import observations task
    - `import_observations` object
      - `state` string: The state of the import observations task
      - `total_inserted_observations` integer: The number of inserted observations in this instance
  - `links` object
    - `dataset` object: An object describing the ID and URL for a dataset which is associated with this instance
      - `href` string: The URL for the dataset associated with this instance
      - `id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
    - `job` object: An object describing the ID and URL of the job containing this instance
      - `href` string, required: The URL for the job containing this instance
      - `id` string, required: The ID of the job containing this instance
    - `self` object: An object describing the ID and URL for a dataset which is associated with this instance
      - `href` string: The URL for this resource
  - `state` 'created' | 'completed' | 'failed' | 'edition-confirmed' | 'associated' | 'published': The state of the resource, can only be one of the following: * created * completed (instances only) * failed (instances only) * edition-confirmed (instances and versions only) * associated (not editions) * published

## Response `201`

Successfully created instance

- NewInstance: A model for the request and response body for creating a new instance
  - `dimensions` Codelist[]: A list of codelists for each dimension of this instance
    - `href` string: A link to the codelist corresponding to this dimension
    - `id` string: The codelist id corresponding to this dimension
    - `name` string: The dimension name
    - `description` string: The dimension description
    - `label` string: A human readable label for dimension
  - `id` string: A unique id for an instance
  - `import_tasks` ImportTasks
    - `build_hierarchies` object[]
      - `code_list_id` string: The ID of the codelist that this hierarchy represents
      - `dimension_name` string: The name of the dimension the hierarchy represents
      - `state` string: The state of the import observations task
    - `build_search_indexes` object[]
      - `dimension_name` string: The name of the dimension the search index represents
      - `state` string: The state of the import observations task
    - `import_observations` object
      - `state` string: The state of the import observations task
      - `total_inserted_observations` integer: The number of inserted observations in this instance
  - `links` object
    - `dataset` object: An object describing the ID and URL for a dataset which is associated with this instance
      - `href` string: The URL for the dataset associated with this instance
      - `id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
    - `job` object: An object describing the ID and URL of the job containing this instance
      - `href` string, required: The URL for the job containing this instance
      - `id` string, required: The ID of the job containing this instance
    - `self` object: An object describing the ID and URL for a dataset which is associated with this instance
      - `href` string: The URL for this resource
  - `state` 'created' | 'completed' | 'failed' | 'edition-confirmed' | 'associated' | 'published': The state of the resource, can only be one of the following: * created * completed (instances only) * failed (instances only) * edition-confirmed (instances and versions only) * associated (not editions) * published

## Other responses

- `400`: Failed to process the request due to invalid request
- `401`: The token provided is unauthorised to carry out this operation
- `403`: The request is forbidden
- `500`: Failed to process the request due to an internal error

---

[API](https://skmtc.dev/office-of-national-statistics/apis/dataset-api.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/dataset-api/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/dataset-api/revisions/a2947a13d675?raw)