Identifiers & PID Minting
Three fields, three meanings
The single most common integration error is treating a DOCiD, a DOI, and a Handle URL as interchangeable. They are stored in three separate columns on publications, each with a distinct contract.
| Field | Holds | Example |
|---|---|---|
document_docid |
The primary resolvable identifier — a bare Handle with no URL prefix. Unique across the platform and indexed. For harvested records this may instead carry the source DOI. | 20.500.14351/e7d1b5c9a30a45bc2858 |
doi |
A real Crossref or DataCite DOI only. Never a DOCiD Handle. | 10.1234/example.5678 |
handle_url |
A full resolvable URL for a handle held by an external repository, typically a harvested DSpace item. Distinct from document_docid. |
https://hdl.handle.net/10539/12345 |
The doi field rejects Handles
Values submitted to doi pass through a coercion step that strips any https://doi.org/ prefix and then requires the result to match ^10.\d+/. A DOCiD Handle beginning 20. is rejected and discarded, with a warning logged identifying the caller as one that still confuses the two columns. If you populate doi with a DOCiD, the value will silently not be stored.
The DOCiD Handle prefix
DOCiD mints Handles under the prefix 20.500.14351, administered by the African PID Alliance. Every natively minted DOCiD takes the form:
20.500.14351/e7d1b5c9a30a45bc2858
└────┬─────┘ └─────────┬──────────┘
prefix suffix
(APA-wide) (opaque, per-object)Suffixes are opaque. They carry no encoded meaning — not the year, not the resource type, not the depositor — and must not be parsed. Attached objects (individual files and documents) receive their own Handles in the same prefix, recorded in their handle_identifier column, so a file can be cited independently of the collection that contains it.
Documentation prior to v2.0 used a placeholder prefix
Earlier revisions of these pages illustrated Handles with 20.500.12345, which is not a real DOCiD prefix. Any integration built against that example should be rechecked.
The minting lifecycle
Identifier assignment happens in two stages: a synchronous per-object step at deposit time, and an asynchronous publication-level push to CORDRA.
Stage 1 — per-object Handle assignment
When an object is deposited with an existing identifier, that identifier is classified:
| Supplied identifier | Outcome |
|---|---|
A DOI (begins 10.) |
A new DOCiD Handle is minted for it; the DOI is retained as external_identifier with type DOI |
Already a Handle (contains /, does not begin 10.) |
Used as-is; no new Handle is minted |
| Anything else | Retained as an external identifier of unknown type |
Minting itself is a create operation against the CORDRA DOIP service, requesting an object of type APA_Handle_ID; CORDRA returns the generated identifier.
Stage 2 — asynchronous CORDRA push
Publication-level registration is deferred to a background task queued roughly a minute after deposit, so a slow or unavailable CORDRA never blocks a submission. Progress is tracked in five columns on publications: cordra_synced, cordra_synced_at, cordra_status, cordra_error, and cordra_object_id. The CORDRA object id is the document_docid itself.
cordra_status |
Meaning |
|---|---|
PENDING |
Default on insert; queued or not yet attempted |
MINTED |
Registered in CORDRA, or already carrying a minted identifier |
SKIPPED |
The record already has a real DOI (typically a Figshare import), so DOCiD does not mint a competing identifier |
FAILED |
The push failed; see cordra_error |
Two idempotency guards run before any push: a record with a non-empty doi becomes SKIPPED, and one already carrying a minted identifier becomes MINTED. Re-running the task is therefore safe.
None of the cordra_* fields are exposed in the API
Minting state is internal. No publication endpoint serialises cordra_status or its siblings, so a client cannot currently distinguish "minted" from "pending" through the public API.
Minting controls and audit
The explicit minting API — Handle assignment, the various DOI types, metadata deposit — is gated by the deployment flag PID_MINTING_ENABLED, which defaults to false. On a deployment where it has not been enabled, those routes are unavailable regardless of the caller's permissions.
Every mint write is recorded in an audit table capturing the acting user, operation, resource type, idempotency key, request id, a SHA-256 of the payload, the response status and body, the resulting identifier, error code, IP address, user agent, and timestamps. A unique constraint on request id, and another on the combination of user, operation and idempotency key, makes a retried mint request safe to submit twice.
Not a minting endpoint
GET /api/v1/docid/get-doi returns a random seven-character string from a lookup table. It is a suffix generator used during composition and performs no registration. Do not treat its output as an assigned identifier.
Resolution
A DOCiD resolves at the application root. Four routes serve resolution, with different tolerances:
| Route | Accepts |
|---|---|
GET /<docid> |
Root catch-all. The identifier must match ^\d+(\.\d+)+/.+$; anything else falls through to a 404 so other routes are unaffected. Supports ?type=xml. |
GET /doi/<prefix>/<suffix> |
Prefix must match ^\d+(\.\d+)+$ and the suffix must be strictly alphanumeric |
GET /api/v1/publications/docid?docid= |
Query form; the safest choice when scripting |
GET /api/v1/publications/<docid> |
Path form, slash-tolerant |
The /doi/ route rejects non-alphanumeric suffixes
Its suffix check is a strict alphanumeric test, so a DOCiD whose suffix contains a hyphen or a dot returns 400 there while resolving perfectly through the other three routes. Prefer the query form for general-purpose resolution.
Other identifier schemes
| Scheme | Status in DOCiD |
|---|---|
| DOI, CSTR, Handle, ARK | The four seeded values of the identifier_types reference table, selectable for attached documents |
| CSTR | Has its own column on publication_documents — which is never serialised in any API response — plus a dedicated set of registration endpoints |
| RAiD | Stored against projects, with dedicated mint and lookup endpoints. Project identifiers are not serialised: publication responses expose only id, title, raid id and description |
| ARK | Create, resolve and metadata endpoints exist, but there is no ARK column on publications; an ARK can only be held as an attached document's identifier |
Creator and organization identifier schemes are covered in Property 2: Creator and Property 4: Publisher.