canonical: https://jentic.com/apis/id4i.de/id4i

# Id4i De ID4i API

ID4i is an industrial identifier service that issues and manages globally unique numbers (GUIDs and aliases) for products, components, and digital twins. The HTTP API exposes 107 endpoints covering account registration, organization billing, API key management, GUID issuance, alias mapping, collections, country and language reference data, history and auditing, image attachments, and routes for partner messaging. Authentication uses an API key in the Authorization header. The surface is broad enough to cover full lifecycle management from issuing a new identifier to auditing every read and write against it.

## For AI agents

Issue and manage globally unique product identifiers, attach metadata and images, and audit access through 107 endpoints covering accounts, organizations, GUIDs, aliases, and collections.

## Scope

Does not handle end-user authentication, document verification, or KYC checks - use for industrial product identifier issuance and management only.

## Capabilities

- Provision and manage organization accounts, billing, and per-organization API keys
- Issue new GUIDs and reserve identifier ranges for products, components, or batches
- Attach aliases and external identifiers to a GUID through `/api/v1/aliases` mappings
- Group identifiers into collections via `/api/v1/collections` for batch operations
- Attach images and metadata to a GUID for digital twin or labelling workflows
- Audit reads and writes against an identifier via the changelog and history endpoints
- Manage API key privileges scoped to specific GUID namespaces

## Use cases

### Industrial Product Identifier Issuance

Manufacturers issue a unique ID4i identifier for every produced unit so that downstream systems - maintenance, recalls, supply chain - can query a single source of truth. The `/api/v1/guids` endpoints allocate identifiers in batches that map to production runs, with metadata captured per unit. Integrations are typically live within a week because the API surface mirrors familiar resource patterns.

Example prompt: Allocate a batch of 500 GUIDs through POST `/api/v1/guids` and tag each with the production run identifier in metadata

### Digital Twin Lookup

Field technicians scan a label, the application looks up the GUID and returns attached metadata, images, and history. The API serves `/api/v1/guids/{id}` alongside `/api/v1/images` and `/api/v1/history` endpoints, so a single resolution can power a full digital-twin view inside a maintenance app.

Example prompt: Resolve a scanned GUID via GET `/api/v1/guids/{id4n}` and fetch attached images and history endpoints to render a digital twin view

### Alias Mapping for Cross-System Integration

Bridge an ID4i identifier with external systems (ERP SKU, GTIN, internal asset code) by storing aliases that resolve back to the canonical GUID. The alias endpoints enable lookups in either direction so partner systems can keep their own identifiers while still resolving to the same physical asset.

Example prompt: Create an alias mapping via POST `/api/v1/aliases` that links an internal SKU to an existing ID4i GUID

### AI Agent Inventory Audit

An audit agent uses Jentic to find ID4i operations matching 'audit product identifier history', loads the changelog schema, and walks through every change for a flagged identifier. The agent compiles a summary the auditor can act on without writing an HTTP client by hand.

Example prompt: Use Jentic search 'audit product identifier history' to load the ID4i changelog schema and execute it for a given GUID

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/apikeys` | Create a new API key with scoped privileges |
| GET | `/api/v1/collections` | List collections owned by the authenticated organization |
| GET | `/api/v1/collections/{id4n}/elements` | List the GUIDs contained in a collection |
| GET | `/api/v1/billing/{organizationId}` | Retrieve billing summary for an organization |
| GET | `/api/v1/billing/{organizationId}/positions` | List billing line items for an organization |
| GET | `/api/v1/changelog/organization/{organizationId}/` | Audit changelog for all activity in an organization |
| POST | `/account/registration` | Register a new user account |
| GET | `/api/v1/countries` | List supported countries for organization data |

## Key resources

- **Accounts** — User registration, password, and email verification endpoints
- **API Keys** — Create, list, and scope API keys per organization and namespace
- **Billing** — Per-organization billing positions and invoices
- **Guids** — Issue, retrieve, and manage globally unique identifiers
- **Alias** — Map external identifiers to canonical ID4i GUIDs
- **Collections** — Group identifiers for batch lookup and operations
- **Images** — Attach and serve image assets bound to an identifier
- **Auditing** — Changelog and history endpoints for compliance review

## Why Jentic

- **Setup:** Wiring the ID4i API by hand means passing your key in the Authorization header against its backend host and mapping its identifier collection and billing routes yourself. Through Jentic you install once, import the ID4i API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** ID4i puts the collection and organization ids in the URL path (`/collections/{id4n}/elements`, `/billing/{organizationId}`), so a rule can pin your agent to reading elements and billing for one organization. You choose the operations it may call, so issuing new API keys or registering accounts is not included unless you add them.
- **Credential handling:** Your ID4i API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list a collection's identifiers' or 'read an organization's billing positions', and Jentic returns the matching ID4i operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AddressFinder API** — Address validation that pairs with ID4i for shipping and physical-asset workflows
- **Auth0 API** — Customer identity layer that can front the ID4i platform for end-user authentication
- **Okta API** — Enterprise directory and access management - different scope from industrial identifier issuance

## FAQ

### What authentication does the ID4i API use?

The ID4i API uses an API key passed in the Authorization header. Keys are issued per organization through `/api/v1/apikeys` and can be scoped to specific privileges and GUID namespaces. Through Jentic, the key is stored encrypted in your Jentic One instance and injected at execution time.

### Can I issue a batch of GUIDs through the ID4i API?

Yes. The `/api/v1/guids` endpoints support bulk issuance so manufacturing systems can allocate identifiers in production-run-sized batches. Each GUID can carry metadata and be added to a collection through `/api/v1/collections/{id4n}/elements` for downstream lookup.

### What are the rate limits for the ID4i API?

The ID4i platform applies per-organization rate limits tied to your subscription tier. The OpenAPI spec does not encode exact thresholds. Build agents to detect 429 responses and back off, and prefer batch endpoints for bulk allocation rather than firing one request per identifier.

### How do I retrieve a product's history through Jentic?

Run pip install jentic and import the SDK, then await client.search('audit product identifier history') to find the ID4i changelog operation. Load the `/api/v1/changelog/organization/{organizationId}`/ schema and execute it. Run Jentic One, the self-hosted execution layer, for an API key.

### Does the ID4i API support attaching images to an identifier?

Yes. The `/api/v1/images` endpoints let you attach, list, and retrieve image assets bound to a specific GUID. This is commonly used for digital-twin lookups so a scanned identifier resolves to a labelled, photographed unit.

### Can I scope an API key to a specific GUID namespace?

Yes. POST `/api/v1/apikeys` creates a key, and `/api/v1/apikeys/{key}/privileges/{privilege}/id4ns` binds privileges to specific identifier namespaces. This lets a partner application read or write only the GUIDs it owns without seeing the rest of the organization's catalog.

### Can I limit what my agent is allowed to do with the ID4i API?

Yes. Because you run Jentic One yourself, your own rules decide which ID4i operations and credentials the agent may call. Since ID4i puts organization and collection IDs in the URL path, such as `/api/v1/collections/{id4n}/elements` and `/api/v1/billing/{organizationId}`, you can pin the agent to reading a single organization's collection elements and billing positions. Sensitive operations like issuing new API keys through `/api/v1/apikeys` or registering accounts stay off unless you explicitly allow them.