ADMiT Assesments API

The ADMiT API is used to initiate inline assessments for individuals.

Before you begin:

Endpoints

Environment	Base URL
Test	https://api.staging.principa.cloud/admit/v1
Production	https://api.principa.cloud/admit/v1

Initiate a new Assessment

This operation will initiate an assessment against for an individual. Currently, two assessments are available:

`scoreType`	Description
DRA	Dynamic Risk Assessment
DEA	Dynamic Entrepreneurial Assessment

Process Flow

This operation returns a url in a successful response, which is the URL that the source system should redirect the user to in order to begin their assessment.
When the user has completed their assessment, they will be redirected back to the redirectUrl provided in the request body.

POST /assessment

Request body - 'AssessmentRequest'

Field	Type	Required	Notes
`firstName`	string	yes	Given name of the applicant
`lastName`	string	yes	Family name
`email`	string	yes	Contact e-mail address
`scoreType`	string	yes	Code for the score being assessed (e.g. DRA, DEA)
`msisdn`	string	yes	Mobile number in MSISDN format
`idOrPassport`	string	yes	National ID or passport number
`countryCode`	string	yes	ISO-3166-1 alpha-2 country code
`redirectUrl`	string	no	Where to send the customer after completing the online questionnaire
`idVerified`	string	no	Specify whether the applicant has been verified or not. If true, ID verification will not be enforced via Didit, the questionnaire can be completed immediately. If false, ID verification will be enforced via Didit before a user can complete the questionnaire. Only clients who have "Request KYC" enabled (Activated via support in the Admin Portal), will be able to use this flag to enforce ID Verification via the API (setting idVerified as False).

Example request

{
  "firstName": "Nomusa",
  "lastName": "Nkosi",
  "email": "nomusa@example.com",
  "scoreType": "DRA",
  "msisdn": "27831234567",
  "idOrPassport": "9001010052088",
  "countryCode": "ZA",
  "redirectUrl": "https://app.example.com/assess/complete",
  "idVerified": true
}

Successful response - 'AssessmentResult'

Field	Type	Description
`success`	boolean	`true` when the assessment record was created
`code`	string	Implementation-specific result code
`message`	string	Human-readable message
`url`	string	URL the applicant should visit to complete or view the assessment

Example response

{
  "success": true,
  "code": "SUCCESS",
  "url": "https://admit.staging.principa.cloud/e/3d5f4d09-e5a1-4c9c-b92b-0f4e6b7c27af"
}

Unsuccessful response example - Code 400

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Country code not valid."
}

Unsuccessful response example - Code 500

{
  "success": false,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred. Please try again later."
}

Status Callbacks

The assessment operation is able to provide real-time event notifications for critical stages in the assessment lifecycle (e.g., when an assessment is started, completed, or scored). This integration removes the need to poll the API repeatedly and enables your platform to respond to important events instantly.

Webhooks (callbacks) are stateless, HTTP-based push messages that transmit structured JSON payloads to a pre-registered endpoint on your side. Your application listens to these and reacts as needed (e.g., update UI, notify customer, process downstream rules).

Callback Configuration

Callback configuration is set up within the Principa Cloud Portal as follows:

Navigate to Developer
In the Webhooks tab, under the Assessment Webhook section, enter the endpoint in your application that will handle incoming webhook notifications.

Example:
```
https://yourposturl.com/path
```
Select the events for which your application should receive callbacks. Available options include:
- STARTED
- COMPLETED
- SCORED
Click Save to persist your callback configuration.

Callback Events

The following callback events can be configured:

Event	Trigger Description	Example Usage
`STARTED`	The assessment is actively being processed	Mark status as "in progress", disable re-submission UI
`COMPLETED`	All required data has been evaluated	Prepare for score delivery, notify compliance workflow
`SCORED`	A score is now available for the assessment	Trigger downstream rules, send SMS/email, or update frontend

Each event is independent and may arrive in sequence or in isolation. Your system should support idempotent, asynchronous processing.

Example Payload

When an event (e.g., SCORED) occurs, a POST request will be sent to your configured Callback URL with the following type of payload:

{
  "idOrPassport": "4839165153528",
  "status": "Scored",
  "statusAt": "2025-07-23T10:47:30.3666667Z",
  "countryCode": "ZA",
  "scoreType": "SCORE_DRA"
}