---
title: "Create a filter for a dataset"
method: POST
path: "/filters"
tags: ["Public"]
---

# Create a filter for a dataset

`POST /filters`

## Request

- Base URL: `/v1` (relative, and the document’s source URL is not known)
- URL: `/v1/filters`
- Auth: none declared

Create a resource for listing a selection of dimensions and dimension options to be added to filter for a dataset

## Request body

- NewFilterRequest: A description of a job to generate a customised dataset
  - `filter_id` string: A unique id for this resource
  - `links` FilterLinks: A list of links related to this resource
    - `version` object
      - `href` string: A URL to the version being filtered
      - `id` string: An ID of the version being filtered
    - `dimensions` object
      - `href` string: A URL to list the dimensions selected for the filter
    - `self` object
      - `href` string: A URL to link to the filter record
  - `dataset` Dataset: A version of an edition for a dataset to filter on.
    - `id` string: The unique identifier of a dataset
    - `edition` string: An edition of a dataset
    - `version` integer: A version of a dataset
  - `dimensions` DimensionOptions[]: A list of dimensions in the filter job
    - `name` string: The name of the dimension to filter on
    - `options` string[]: A list of options for dimension to filter on a dataset
  - `population_type` string: If specifying a custom filter, the population type that the data should be queried from

## Response `201`

filter was created

- NewFilterResponse: A description of a job to generate a customised dataset
  - `filter_id` string: A unique id for this resource
  - `links` FilterLinks: A list of links related to this resource
    - `version` object
      - `href` string: A URL to the version being filtered
      - `id` string: An ID of the version being filtered
    - `dimensions` object
      - `href` string: A URL to list the dimensions selected for the filter
    - `self` object
      - `href` string: A URL to link to the filter record
  - `instance_id` string: The instance of a dataset this filter relates to
  - `dataset` Dataset: A version of an edition for a dataset to filter on.
    - `id` string: The unique identifier of a dataset
    - `edition` string: An edition of a dataset
    - `version` integer: A version of a dataset
  - `dimensions` DimensionOptions[]: A list of dimensions in the filter job
    - `name` string: The name of the dimension to filter on
    - `options` string[]: A list of options for dimension to filter on a dataset
  - `type` string: The type of filter, e.g. flexible for census filters
  - `published` boolean: Whether the dataset the filter relates to is published or not
  - `population_type` string: The population type that the filter is based on, this is for Census filters only

## Other responses

- `400`: Invalid request body
- `500`: Failed to process the request due to an internal error

---

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