---
title: primaryid field
slug: pa9c0434
canonical_url: https://docs.coveo.com/en/pa9c0434/
collection: leverage-machine-learning
source_format: adoc
---
# primaryid field
The `primaryid` field contains a globally unique ID that identifies an [item](https://docs.coveo.com/en/210/) across your whole Coveo organization.
The `primaryid` encodes both the [source](https://docs.coveo.com/en/246/) and the [index](https://docs.coveo.com/en/204/), so two items with the same `uri` or `permanentid` will never collide.

`primaryid` points to exactly one item, no matter how it was [indexed](https://docs.coveo.com/en/204/) in your Coveo organization.
It's meant to identify an exact item the [index](https://docs.coveo.com/en/204/) returned after all security filters and [query pipeline](https://docs.coveo.com/en/180/) rules have been applied.

## `primaryid` versus `permanentid` and `uniqueid`

Coveo indexes every item with several identifiers.
The three main identifiers are `primaryid`, `permanentid`, and `uniqueid`.
These item IDs point to the same logical document in the [index](https://docs.coveo.com/en/204/), but each ID has a specific purpose and scope.
`primaryid` is mainly for external use, `permanentid` is used mainly for [Coveo Machine Learning](https://docs.coveo.com/en/188/), and `uniqueid` is used internally by the Coveo indexing system.

The following table summarizes the key differences between the item IDs, in which context the IDs are safe to use, and whether they survive reindexing or different sources:

[options="header", cols="1,3,3,3"]
|===
|Identifier |Visibility and API usage |Scope and stability |Notes

|`uniqueid`
|Returned in [query](https://docs.coveo.com/en/231/) results.
Cannot be queried.
|Unique within an index as long as the document is indexed using a single source.
If the same document is indexed in multiple sources, each instance has its own `uniqueid`.
|Used by the index as the document key.
Not meant to be reliable for external use.

|`permanentid`
|Returned in [query](https://docs.coveo.com/en/231/) results and [Coveo Analytics events](https://docs.coveo.com/en/260/).
|Stable across versions of the same item.
Stable across sources if the same item was indexed.
|Useful for item grouping, [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/),  or product-level analytics.
Not globally unique or security-aware.

If two items differ only by permissions, they will have the same `permanentid`.
This can lead to permission or authorization issues.

|`primaryid`
|Returned in the API responses.[.footnote]^[[1](#api-support)]^
|Unique within an organization, stable, and security-filtered.
|Safest choice for referencing or persisting a item exactly as in search results.
|===

--
1. The Search API, PR API, and Answer API return the `primaryid` field in their responses.
--

## Best practices

Choosing which item ID to use depends on what you're doing with the item data.
Picking the right item ID for your integration helps to avoid collisions, stale references, or permission mismatches.

### `primaryid`

Use `primaryid` when you need a one-to-one reference to a specific, security-filtered item.
For example, to:

* fetch passages or [snippets](https://docs.coveo.com/en/laeb0292/).

* store or cache the search results.

* link securely to a item.

* build pipelines or exports that must not drift from search results.

### `permanentid`

Use `permanentid` to group or analyze multiple representations of the same item, such as versions, languages, or product variants.
It's suitable for publicly available items for which access control isn't a concern.


### `uniqueid`

Use the `primaryid` instead.
`uniqueid` is an internal Coveo index identifier and isn't reliable for use in external implementations.