---
title: "UID"
description: "This article explains what the UID field is and how to configure it."
meta_title: "UID"
category: "fields"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

The UID field lets content writers assign a unique identifier to a page. It is often used to build page URLs.

The UID field has these characteristics:

* Only one UID field per page type or custom type is allowed. Slices cannot contain UID fields.
* The value must be unique to the page type or custom type and locale.
* The value must be lowercase and cannot contain spaces. For example, `about-us`.
* The value cannot contain special characters, except hyphens (`-`) and underscores (`_`).
* When a UID value is changed, the old value is retained as a reference. The page can be queried using the previous UID until another page reuses it.

To learn more about managing UIDs, see [Edit a page's Unique Identifier](https://prismic.io/docs/guides/create-pages.md#uid).

# Add a UID field to a content model

Reusable page types and custom types include a UID field with the API ID `uid`. The UID field cannot be manually added or removed.

# Use UID fields

The UID field is most often used to query a page by its UID. The `getByUID` client method returns a page with a matching page type and UID.

This example queries a Blog Post page with the UID `my-first-post`.

```ts
const blogPost = await client.getByUID("blog_post", "my-first-post");
```

[Learn more about `getByUID`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#getbyuid)

# Use the UID in a page's URL

A page's UID can be used in a [route resolver](https://prismic.io/docs/route-resolver.md) as `:uid`.

This example configures URLs for Page and Blog Post pages using their UIDs.

```ts
const routes = [
  { type: "page", path: "/:uid" },
  { type: "blog_post", path: "/blog/:uid" },
];
```

A route resolver can override a more general resolver by specifying a UID. This example overrides the default `page` route resolver when a page has the UID `home`.

```ts {3} /uid: "home"/
const routes = [
  { type: "page", path: "/:uid" },
  { type: "page", uid: "home", path: "/" },
  { type: "blog_post", path: "/blog/:uid" },
];
```

> Learn more about configuring [route resolvers](https://prismic.io/docs/route-resolver.md).

# API response

Here is what a UID field looks like from the Content API:

```json {3}
{
  "id": "YCiUyRUAACQAxfZK",
  "uid": "my-first-post",
  "url": "/blog/my-first-post",
  "type": "blog_post",
  "href": "https://example-prismic-repo.cdn.prismic.io/api/v2/...",
  "tags": ["Tag 1", "Tag 2"],
  "first_publication_date": "2021-02-14T03:22:26+0000",
  "last_publication_date": "2022-07-09T00:36:18+0000",
  "slugs": ["my-first-post"],
  "linked_documents": [],
  "lang": "en-us",
  "alternate_languages": [],
  "data": {
    // ...
  }
}
```

Unlike other field types, the UID field is a top-level page property, not a property within `data`.

> **Important**
>
> **The `slugs` property is deprecated**. It served a similar purpose as the UID field in the past.