ADMiT Leads API

The ADMiT Leads API is used to provide real-time event notifications when a lead is available.

Before you begin:

Endpoints

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

Lead Callbacks

The leads operation is able to provide real-time event notifications when a lead is available 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).

Lead Types

There are currently two classifications of leads:

Type	Description
QLF (Qualified)	Only provided when partner questions exist and the lead qualifies
STD (Standard)	Standard lead with basic customer data

Qualified (QLF) leads contain additional enriched data compared to Standard (STD) leads. In addition to general lead metadata and customer identifiers, the response also includes all the questions answered by the lead and the corresponding answers. These are returned as a structured key/value or object collection that represents the answers captured for that lead.

NOTE: Only partners with Partner Questions configured are eligible to receive QLF leads.

Callback Configuration

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

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

Example:
```
https://yourposturl.com/path
```
Click Save to persist your callback configuration.

Example Standard Lead Payload

When a new STD lead is captured, a POST request will be sent to your configured Callback URL with the following type of payload:

{
  "leadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "leadType": "STD"
}

Example Qualified Lead Payload

When a new QLF lead is captured, a POST request will be sent to your configured Callback URL with the following type of payload:

{
  "leadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "leadType": "QLF"
}

Retrieve Standard Lead Information

POST /leads


Purpose	Retrieves lead information based on lead ID and lead type.
Success response	200 OK - returns a LeadResult object
Tags	`Leads`

Request body = 'LeadRequest'

Field	Type	Required	Description
`leadId`	string	yes	Unique identifier for the lead
`leadType`	string	yes	Type of lead (STD)

Example Request

{
  "leadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "leadType": "STD"
}

Successful Standard Lead Response = 'LeadResult'

Field	Type	Description
`success`	boolean	`true` if the lookup was successful
`code`	string	Implementation-specific result code
`message`	string	Human-readable status message
`leadId`	string	Lead ID returned from the request
`firstName`	string	First name of the lead (if available)
`lastName`	string	Last name of the lead (if available)
`email`	string	Contact email (if available)
`msisdn`	string	Mobile number in MSISDN format
`idNumber`	string	National ID number or passport number

Successful Response (Standard Lead)

{
  "success": true,
  "code": "string",
  "message": "string",
  "leadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "msisdn": "string",
  "idNumber": "string"
}

Unsuccessful Response Example

{
  "success": false,
  "code": "INSUFFICIENT_FUNDS",
  "message": "Not enough funds available"
}

Retrieve Qualified Lead Information

POST /leads


Purpose	Retrieves lead information based on lead ID and lead type.
Success response	200 OK - returns a LeadResult object
Tags	`Leads`

Request body = 'LeadRequest'

Field	Type	Required	Description
`leadId`	string	yes	Unique identifier for the lead
`leadType`	string	yes	Type of lead (QLF)

Example Request

{
  "leadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "leadType": "QLF"
}

Successful Response = 'LeadResult'

Field	Type	Description
`success`	boolean	`true` if the lookup was successful
`code`	string	Implementation-specific result code
`message`	string	Human-readable status message
`leadId`	string	Lead ID returned from the request
`firstName`	string	First name of the lead (if available)
`lastName`	string	Last name of the lead (if available)
`email`	string	Contact email (if available)
`msisdn`	string	Mobile number in MSISDN format
`idNumber`	string	National ID number or passport number
`qualifyingCriteria`	Dictionary<string, string>	Contains each qualifying question and the user's answer

Successful Response Example (Qualified Lead)

{
  "success": true,
  "code": "string",
  "message": "string",
  "leadId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "msisdn": "string",
  "idNumber": "string"
  "QualifyingCriteria":[
  	"Do you own a home?": "Yes",
	"Do you own a vehicle?": "No",
  ]
}

Unsuccessful Response Example

{
  "success": false,
  "code": "INSUFFICIENT_FUNDS",
  "message": "Not enough funds available"
}