Go back

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 for an individual. Currently, two assessments are available:

scoreType Description
DRA Individual Psychometric Score
DEA Dynamic Entrepreneurial Assessment

Two types of operations (/requests) exist for initiating an assessment.

  • "POST /assessment" is used when all customer information is available, thus all fields are required, and a re-direct url is available for after the assessment is complete.
  • "POST /assessment/PostWithRegistration" is used for situations where some customer information is not available, thus not all fields are required but the customer will be asked to input those that are missing. This also does not provide a re-direct url and the customer will continue to the ADMiT portal after the 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'

Used when all customer information is available, thus all fields are required, and a re-direct url is available for after the assessment is complete.

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
}

POST /assessment/PostWithRegistration

Request body - 'AssessmentWithRegistrationRequest'

Used for situations where some customer information is not available, thus not all fields are required but the customer will be asked to input those that are missing. This also does not provide a re-direct url and the customer will continue to the ADMiT portal after the assessment.

Field Type Required Notes
firstName string no Given name of the applicant
lastName string no Family name
email string no Contact e-mail address
scoreType string yes Code for the score being assessed (e.g. DRA, DEA)
msisdn string no Mobile number in MSISDN format
idOrPassport string no National ID or passport number
countryCode string yes ISO-3166-1 alpha-2 country code
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",
  "idVerified": true
}

Successful response - 'AssessmentResult' & 'AssessmentWithRegistrationRequest'

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:

  1. Navigate to Developer

  2. 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

  3. Select the events for which your application should receive callbacks. Available options include:

    • STARTED
    • COMPLETED
    • SCORED

  4. 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"
}
An unhandled error has occurred. Reload 🗙