Business Registration System API — Get Business by UEN

This document describes how to retrieve a registered business by its Unique Entity Number (UEN) from the BRS API.

---

Authentication

The BRS API uses DIT's Central Authentication Service (CAS) for authentication. This endpoint requires machine-to-machine (M2M) authentication via the Client Credentials flow.

CAS URLs

Use https://auth.dev.krd in dev, staging, and pre-prod environments.

Use https://account.id.krd in production environment.

OpenID Connect

The CAS is an OpenID Connect-compatible service. It provides a discovery endpoint for dynamic information discovery at /.well-known/openid-configuration.

Required Scope

To call this endpoint, your client must be granted the following scope:

Scope	Description
beas-processes-api.businesses.get_by_uen	Grants permission to read a business by UEN

Obtaining an Access Token

To obtain an access token, send a POST request to the CAS token endpoint:

POST https://auth.dev.krd/connect/token

Set the Header to: Content-Type: application/x-www-form-urlencoded

Set the Request Body to:

{
    "grant_type": "client_credentials",
    "scope": "beas-processes-api.businesses.get_by_uen",
    "client_id": "YOUR CLIENT ID",
    "client_secret": "YOUR CLIENT SECRET"
}

Upon successful handling of the request, the response payload will contain an access token, expiry time, token type, and requested scopes:

{
    "access_token": "A LONG ACCESS TOKEN HERE",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "beas-processes-api.businesses.get_by_uen"
}

Use the access_token from the response as a Bearer token in the Authorization header when calling the endpoint.

Note: We highly recommend using existing packages and libraries that take care of the OAuth 2.0 Client Credentials implementation instead of making raw HTTP requests. The existing libraries are battle-tested and handle many details that you may otherwise skip.

---

Endpoint

Get Business by Unique Entity Number (UEN)

Retrieves a single registered business by its Unique Entity Number.

Request

GET /v1/admin/businesses/uen/:uen

Path Parameters

Parameter	Type	Required	Description
uen	string	Yes	The Unique Entity Number (UEN) of the business. A 14-digit identifier (e.g., 20241001048392).

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token obtained from the CAS. Format: Bearer <access_token>
Accept-Language	string	No	Preferred language for localized content. Supported: en, ar, ckb. Defaults to the application default locale.

Example Request

curl -X GET "https://api.example.com/v1/admin/businesses/uen/20241001048392" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

Successful Response

Status: 200 OK

Content-Type: application/vnd.api+json

All responses follow the JSON:API v1.0 specification. Attribute keys are serialized in camelCase.

{
  "data": {
    "id": "42",
    "type": "businesses",
    "attributes": {
      "email": "company@example.com",
      "language": "ckb",
      "uniqueEntityNumber": "20241001048392",
      "tradeNameId": 100,
      "houseNumber": "12",
      "streetNumber": "5",
      "street": "Bakhtiari Street",
      "address": "Sulaymaniyah, Kurdistan Region",
      "neighborhood": "Raparin",
      "establishedAt": "2024-03-15T00:00:00.000Z",
      "totalFeesPaid": "250000.0",
      "response": null,
      "version": 3,
      "businessState": "registered",
      "userActivities": "Retail Trade",
      "createdAt": "2024-03-15T10:30:00.000Z",
      "updatedAt": "2024-06-20T14:45:00.000Z",
      "workflowState": "registered",
      "dossierNumber": 12345,
      "letterTo": ["ministry_of_interior"],
      "terminationDate": "2025-03-15",
      "pendingReview": false,
      "upn": "1234567890",
      "transitions": [],
      "transitionComment": ""
    },
    "relationships": {
      "tradeName": {
        "data": { "id": "100", "type": "tradeNames" }
      },
      "district": {
        "data": { "id": "5", "type": "districts" }
      },
      "province": {
        "data": { "id": "2", "type": "provinces" }
      },
      "businessType": {
        "data": { "id": "1", "type": "businessTypes" }
      },
      "company": {
        "data": { "id": "42", "type": "companies" }
      },
      "activities": {
        "data": [
          { "id": "10", "type": "activities" }
        ]
      },
      "transferOwnershipUploads": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "100",
      "type": "tradeNames",
      "attributes": { "..." : "..." }
    },
    {
      "id": "5",
      "type": "districts",
      "attributes": { "..." : "..." }
    },
    {
      "id": "2",
      "type": "provinces",
      "attributes": { "..." : "..." }
    },
    {
      "id": "1",
      "type": "businessTypes",
      "attributes": { "..." : "..." }
    },
    {
      "id": "42",
      "type": "companies",
      "attributes": { "..." : "..." }
    },
    {
      "id": "10",
      "type": "activities",
      "attributes": { "..." : "..." }
    }
  ]
}

Response Attributes

Attribute	Type	Description
email	string	Contact email of the business
language	string	Language of the business record (en, ar, ckb)
uniqueEntityNumber	string	The 14-digit Unique Entity Number
tradeNameId	integer	ID of the associated trade name
houseNumber	string	House number of the business address
streetNumber	string	Street number of the business address
street	string	Street name of the business address
address	string	Full address of the business
neighborhood	string	Neighborhood of the business
establishedAt	datetime	Date the business was established
totalFeesPaid	string	Total fees paid for registration
response	object/null	Response data (if any)
version	integer	Version number of the record
businessState	string	Always registered for businesses with a UEN
userActivities	string	Description of business activities
createdAt	datetime	Record creation timestamp
updatedAt	datetime	Record last update timestamp
workflowState	string	Current workflow state
dossierNumber	integer	Dossier number assigned upon registration
letterTo	array	List of entities the registration letter is addressed to
terminationDate	date	Date the business registration terminates
pendingReview	boolean	Whether the business is pending review
upn	string	Unified Personal Number of the business owner
transitions	array	Always [] for this endpoint
transitionComment	string	Latest transition comment (if applicable)

Included Relationships

The response includes the following related resources in the included array:

Relationship	Type	Description
tradeName	tradeNames	The trade name associated with this business
district	districts	The district where the business is located
province	provinces	The province where the business is located
businessType	businessTypes	The type/category of the business
company	companies	The company entity (local or foreign) with nested country, shareholders, and ceo
activities	activities	The list of economic activities associated with the business
transferOwnershipUploads	uploads	Uploads related to ownership transfer

Error Responses

Status Code	Condition	Example Response
401 Unauthorized	Missing or malformed Authorization header	{ "status": "unauthorized", "code": 401, "errors": "no authorization header is supplied" }
403 Forbidden	Invalid or expired token, or missing required scope	{ "status": "forbidden", "code": 403, "errors": "You are not authorized to access this resource." }
404 Not Found	No business found with the given UEN	{ "status": "not_found", "code": 404, "errors": "Couldn't find Business" }

---

Appendix

UEN Format

The Unique Entity Number (UEN) is a 14-digit identifier structured as follows:

YYYY EEEE NNNNNN
│    │    └── 6 random digits
│    └─────── 4-digit entity type code
└──────────── 4-digit year of registration

Example: 20241001048392

• 2024 — Year of registration
• 1001 — Entity type code
• 048392 — Random digits (unique)