AmalaID Verification

The Amala verification endpoint provides programmatic access to an individual's basic information via the Amala ID linked to his/her account.

Base URL

https://acs-uat-verifications.amala.cloud/

https://acs-prod-verifications.amala.cloud/

Endpoint

POST verification/api/v1/idv/advance/amalaid

Request Headers

You can use either the API key or Bearer Token for Authorization

Header	Type	Description
Content-Type	application/json	Specifies that the request body is in JSON format.
Authorization	Bearer <token>	Bearer Token for authentication.
x-api-key	API KEY	API Key for authentication.

Request Body

The request body should contain Amala ID details in JSON format.

Example Request

{
  "amalaId": "AML123456",
  "firstName": "John",
  "lastName": "Doe",
  "reference": "REF123456",
  "serviceProviderCode": "SPC001"
}

Request Body Schema

Field	Type	Required	Description
amalaId	string	✅	The Amala ID assigned to the individual.
firstName	string	✅	First name of the individual.
lastName	string	✅	Last name of the individual.
reference	string	✅	A unique transaction reference.
serviceProviderCode	string	✅	Code identifying the service provider.

Responses

Success Response (200 OK)

If the Amala ID is valid, the API returns user details as per the GetAmalaIdResponseApiResponse schema.

{
  "apiVersion": "1.0",
  "success": true,
  "code": "00",
  "message": "Verification successful",
  "requestId": "REQ-123456",
  "data": {
    "amalaId": "AML123456",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "phoneNumber": "[phone]",
    "email": "[email protected]",
    "dateOfBirth": "1990-05-15"
  }
}

Error Responses

Status Code	Description	Example Response
400	Bad Request (Invalid Amala ID)	{ "success": false, "message": "Invalid Amala ID.", "code": "400" }
401	Unauthorized (Invalid API Key)	{ "success": false, "message": "Unauthorized access.", "code": "401" }
500	Internal Server Error	{ "success": false, "message": "Something went wrong.", "code": "500" }

Usage Example (cURL)

curl -X POST "https://acs-uat-verifications.amala.cloud/verification/api/v1/idv/advance/amalaid" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "amalaId": "AML123456",
           "firstName": "John",
           "lastName": "Doe",
           "reference": "REF123456",
           "serviceProviderCode": "SPC001"
         }'