> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognite.com/llms.txt > Use this file to discover all available pages before exploring further. # Define unique IDs with externalId > Learn how to use the externalId field to define unique IDs for data objects in CDF and maintain relationships between source systems. The external ID field, (`externalId`), is available in API v1 for time series, assets, events, files, and sequences. It lets you define a unique ID for each data object in Cognite Data Fusion (CDF) as an optional extension to the existing `id` field. The purpose of external IDs is to: * Avoid duplicates when you insert data. * Avoid extra lookups when you update data. * Maintain relationships between data objects from source systems. * Use the time series `name` field for display instead of lookup. * Give you a way of performing key-value lookups with keys you control that works the same across resources. Make sure to set an `externalId` on all CDF resources for better performance. ## Properties of external IDs The external ID is unique per resource type. An **asset** with `externalId=123` will **not** interfere with a **time series** with `externalId=123`. If you try to create a data object with an existing external ID for a resource type, you'll cause an error. The field is **optional** and **mutable**, so users can choose to add external IDs to data objects that already exist in CDF. If you try to update the external ID to an existing external ID, you'll cause an error. An empty external ID isn't treated as a unique value. The external ID limits to 255 characters, and leading and trailing white spaces aren't allowed. The external ID is case-sensitive. Because `externalId` is matched exactly, a non-breaking space (NBSP) or other invisible whitespace—and strings copied from the CDF user interface or another UI—can break `byids` and other lookups. See [Exact matching and NBSP](#exact-matching-and-nbsp). ## Migrate from earlier API versions For **time series** created in earlier versions of the API, the `name` field was **unique**, and the `externalId` field automatically populated with the value of the `name` field. The external ID is mutable, and you can override this value. All **other resource types** created in earlier API versions will start with an empty `externalId` field. ## Key collisions When you populate the external IDs, it's important that you build a structure in each ID that avoids key collisions. For example, some databases use incrementing integers as row keys, and it's probably a good idea to use for instance `//` as the external ID instead of just the row key. ## ID vs. external ID The existing `id` field, which is a pseudo-random integer between 1 and 2^53-1, remains a valid way of doing a key-value lookup on data objects in CDF. All data objects still have an `id`, and `externalId` is an optional extension that lives side-by-side with it. You can't specify both the `id` and the `externalId` in the same object when you do **lookups**. However, batch lookups in the same request, for example `/byids`, can mix `id` and `externalId` if each object has only one of the fields. CDF does **not** support external IDs in GET requests to `/resource/:externalId`, as it does with the existing `id` field. You must use the `POST resource/byids` endpoint instead. ### Exact matching and NBSP CDF matches `externalId` as an exact string. A non-breaking space (NBSP, U+00A0) is not an ordinary space (U+0020), so two values can look the same but differ: `byids` and other requests then return no match and automation that reuses the wrong string breaks. UI and clipboard copy (including the CDF user interface) may replace NBSP with U+0020 or otherwise normalize the string. Use the `externalId` from API or SDK responses—not pasted or retyped UI text—as the source of truth. For new IDs, prefer ASCII-safe strings. See [CDF resource naming conventions](/cdf/deploy/reference/cdf_resource_naming_conventions#anti-patterns-to-avoid). For HTTP patterns including **Retrieve** with `POST …/byids`, see [Use the API](/dev/use_the_API).