> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cula.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# External IDs

> Cross-reference Cula objects with IDs from your own systems

Every object has a Cula-assigned `id` (for example `ste_01k6cvp6bdeayb0hfrghfwxjzv`). In addition,
some objects let you attach an **external ID** — your own identifier — so you can
cross-reference Cula records with the objects in your systems without storing Cula IDs.

## Assigning an External ID

Set `external_id` when you create a object:

```bash Create a site with an external ID theme={null}
curl -X POST https://api.demo.cula.earth/tracking/v1/sites \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Cula-Organisation-Id: org_01k6cvp6bdeayb0hfrghfwxjzx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Biomass Lutz",
    "address": "Friedrichstr. 1, 10117 Berlin, Germany",
    "external_id": "SITE-EXT-0001"
  }'
```

An external ID must be unique within your organisation,
be 1–100 characters long, and contain only letters, digits, hyphens, and underscores
(`A–Z a–z 0–9 - _`).

<Note>
  External IDs are **mutable** — you can change one later. If you need a stable, immutable
  handle for a object, use the Cula-assigned `id` instead.
</Note>

## Referencing Objects by External ID

Where a request references another object, you can identify it by either its Cula `id` or
its `external_id` — but not both. For example, when creating a site you can point at its
managing organisation by external ID:

```json Reference by external ID theme={null}
{
  "name": "Biomass Lutz",
  "organisation": { "external_id": "ORG-EXT-0001" }
}
```

This lets you build requests entirely from identifiers your own system already knows.

## Querying by External ID

Endpoints that return a single object accept an external ID in place of the Cula `id`, using
the `ext-{your_external_id}` path format. This works for every object type that supports
external IDs:

```bash Fetch a site by external ID theme={null}
curl https://api.demo.cula.earth/tracking/v1/sites/ext-SITE-EXT-0001 \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Cula-Organisation-Id: org_01k6cvp6bdeayb0hfrghfwxjzx"
```

The `ext-` prefix is only a lookup convention that distinguishes an external ID from a
Cula-assigned `id` (which uses the `{prefix}_...` format). The returned object reports its
external ID plainly as `external_id`, without the prefix.

## How External IDs Are Returned

Responses always include the object's own `external_id` (`null` if none was set), and
references to other objects are resolved to carry **both** identifiers:

```json Site response theme={null}
{
  "id": "ste_01k6cvp6bdeayb0hfrghfwxjzv",
  "external_id": "SITE-EXT-0001",
  "organisation": {
    "id": "org_01k6cvp6bdeayb0hfrghfwxjzx",
    "external_id": "ORG-EXT-0001"
  }
}
```