Identifiers
The API uses several types of identifiers to reference entities. Understanding how they relate is key to navigating between endpoints.
Internal IDs
Every entity has a numeric internal ID that is stable and unique within its type.
| Entity | ID field | Type | Example |
|---|---|---|---|
| Company | companyId |
int | 3508351 |
| Person | personId |
int | 2954253 |
| Address | addressId |
int | 12345 |
| Vehicle | vehicleId |
int | 789012 |
| Property | propertyId |
int | 456789 |
| Workplace | companyWorkplaceId |
int | 234567 |
These IDs are used across all API endpoints:
GET /companies/3508351
GET /companies/3508351/representatives
GET /companies/3508351/documents
GET /persons/2954253
GET /vehicles/789012
Registration numbers
Companies can also be looked up by their local registration number (e.g. Swedish organisationsnummer). The registration number is available as a field in search results and company details.
| Field | Description | Example |
|---|---|---|
registrationNumber |
Local registration number | 5565199493 |
personalIdentityNumber |
Personal identity number (persons) | Varies by country |
To find a company by registration number, use the search API:
curl -H "x-api-key: YOUR_API_KEY" \
"https://lens-api.tic.io/search-public/companies?q=5565199493&query_by=registrationNumber"
The companyId from the search result can then be used with all /companies/{id}/... endpoints.
External UUIDs (Sweden)
Swedish properties and addresses from Lantmäteriet have external UUIDs. These can be used as an alternative lookup:
GET /properties/se/{uuid}
GET /properties/se/{uuid}/summary
GET /addresses/se/{uuid}
Watchlist IDs
Watchlists and their sub-resources use GUIDs:
| Entity | Type | Example |
|---|---|---|
| Watchlist | Guid | a1b2c3d4-e5f6-... |
| Watchlist member | Guid | f6e5d4c3-b2a1-... |
| Notification | Guid | 12345678-abcd-... |
| Subscription | Guid | abcdef01-2345-... |
Order IDs
Document orders are identified by GUIDs:
GET /orders/{orderGuid}
GET /orders/{orderGuid}/content
GET /orders/{orderGuid}/file
Connecting the dots
Search for a company by name or registration number to get companyId.
Use GET /companies/{companyId} to get the full company record.
Use GET /companies/{companyId}/representatives to get personId values.
Use GET /persons/{personId} or POST /persons/{personId}/companies to see their other positions.
Use POST /watchlists/{id}/companies/{companyId} to add the company to a watchlist.