Responses
The Shufti Pro Verification API will send you two types of responses if a request for verification is made. First is the HTTP response sent against your request, and the second is the callback response. Both HTTP and callback responses will be in JSON format with a header. application/json
The response header also includes a Key Signature. This key is used for validating the source of the response. Be sure to validate the request by generating signature and matching it with the Signature value from the response header.
HTTP Status Codes
Shufti Pro Verification API uses conventional HTTP response codes to indicate the success or failure of an API request. Every response is generated in JSON with a specific HTTP code.
Following is a list of HTTP codes that are generated in responses by Shufti Pro Verification API.
HTTP code | HTTP message | Message |
---|---|---|
200 | OK | success |
400 | Bad Request | Bad Request: one or more parameter is invalid or missing |
401 | Unauthorized | Unauthorized: invalid signature key provided in the request |
402 | Request Failed | Invalid request data: missing required parameters |
403 | Forbidden | Forbidden: service not allowed |
404 | Not Found | Resource not found |
409 | Conflict | Conflicting data: already exists |
429 | Too Many Requests | Too Many Attempts. |
500 | Server Error | Internal Server Error |
504 | Gateway Timeout | Server error |
524 | Timeout from Cloudflare | Unofficial Server Error |
Response Events
Events are sent in responses that show the status of the request. These events are sent in both HTTP and callback responses.
Event | description | HTTP Response | Callback Response |
---|---|---|---|
request.invalid | Request parameters provided in request are invalid. | Yes | No |
request.unauthorized | Request is unauthorized. The information provided in authorization header is invalid. | Yes | No |
verification.accepted | Request was valid and accepted after verification. | Yes | Yes |
verification.declined | Request was valid and declined after verification. | Yes | Yes |
request.deleted | Request has been deleted. | Yes | Yes |
verification.status.changed | Request status has been updated. | No | Yes |
- Accepted
- Declined
- Invalid
- Unauthorized
- Status.Changed
- Deleted
{
"reference": "17374217",
"event": "verification.accepted",
"verification_data": {
"background_checks": {
"dob": "1990-01-01",
"name": {
"first_name": "Don",
"last_name": "Joe"
},
"aml_data": {
"filters": [
"sanction",
"warning",
"fitness-probity",
"pep-class-1",
"pep-class-4",
"pep-class-3",
"pep-class-2",
"pep"
],
"hits": []
}
}
},
"verification_result": {
"background_checks": 1
},
"info": {
"agent": {
"is_desktop": true,
"is_phone": false,
"useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
"device_name": "Macintosh",
"browser_name": "",
"platform_name": "OS X - 10_14_0"
},
"geolocation": {
"host": "212.103.50.243",
"ip": "212.103.50.243",
"rdns": "212.103.50.243",
"asn": "9009",
"isp": "M247 Ltd",
"country_name": "Germany",
"country_code": "DE",
"region_name": "Hesse",
"region_code": "HE",
"city": "Frankfurt am Main",
"postal_code": "60326",
"continent_name": "Europe",
"continent_code": "EU",
"latitude": "50.1049",
"longitude": "8.6295",
"metro_code": "",
"timezone": "Europe/Berlin"
}
}
}
{
"reference": "95156124",
"event": "verification.declined",
"verification_data": {
"aml_for_business": {
"business_name": "Lukenya Greens Limited",
"aml_data": {
"filters": [
"pep-class-3",
"adverse-media-terrorism",
"adverse-media-general",
"adverse-media-financial-crime",
"adverse-media",
"pep-class-2",
"pep-class-1",
"pep",
"adverse-media-fraud",
"pep-class-4",
"adverse-media-sexual-crime",
"adverse-media-narcotics",
"adverse-media-violent-crime",
"sanction",
"warning",
"fitness-probity"
],
"hits": [
{
"name": "LUKENYA GREENS LIMITED",
"entity_type": "organisation",
"score": 0.7,
"match_types": [
"name_exact",
"removed_organisation_suffix"
],
"alternative_names": [
"LUKENYA GREENS LIMITED",
"Lukenya Greens Limited"
],
"assets": [],
"associates": [],
"fields": {
"Nationality": [
{
"value": "Kenya",
"source": "african-development-bank",
"tag": ""
},
{
"value": "Kenya",
"source": "america-idb",
"tag": ""
}
],
"Country": [
{
"value": "Kenya",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "Kenya",
"source": "america-idb",
"tag": ""
},
{
"value": "Kenya",
"source": "european-bank-ineligible-entities",
"tag": ""
},
{
"value": "Kenya",
"source": "debarred-firm-list",
"tag": ""
}
],
"Original Country Text": [
{
"value": "Kenya-",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "Kenya",
"source": "america-idb",
"tag": ""
},
{
"value": "Kenya",
"source": "european-bank-ineligible-entities",
"tag": ""
},
{
"value": "Kenya",
"source": "debarred-firm-list",
"tag": ""
}
],
"Activation Date": [
{
"value": "1/Jul/2022",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "29 Jun 2022",
"source": "european-bank-ineligible-entities",
"tag": ""
},
{
"value": "29-Jun-2022",
"source": "debarred-firm-list",
"tag": ""
},
{
"value": "29-Jun-2022",
"source": "african-development-bank",
"tag": ""
},
{
"value": "Jul 22, 2022",
"source": "america-idb",
"tag": ""
}
],
"Address": [
{
"value": "MITSUMI BUSINESS PARK, 5TH FLOOR, SUITE 502, 67 MUTHITHI ROAD, WESTLANDS NAIROBI, P.O. BOX 72149, NAIROBI 00200",
"source": "debarred-firm-list",
"tag": ""
},
{
"value": "MITSUMI BUSINESS PARK, 5TH FLOOR, SUITE 502, 67 MUTHITHI ROAD, WESTLANDS NAIROBI, P.O. BOX 72149, NAIROBI 00200, KENYA",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "Mitsumi Business Park, 5th floor, Suite 502 67 Muthithi Road Westlands Nairobi P.O. Box 72149 Nairobi Kenya 00200",
"source": "european-bank-ineligible-entities",
"tag": ""
}
],
"Enforcement Agency": [
{
"value": "ASIA DEVELOPMENT BANK",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "African Development Bank",
"source": "african-development-bank",
"tag": ""
},
{
"value": "Inter-American Development Bank",
"source": "america-idb",
"tag": ""
},
{
"value": "World Bank",
"source": "debarred-firm-list",
"tag": ""
},
{
"value": "World Bank Group",
"source": "european-bank-ineligible-entities",
"tag": ""
}
],
"Enforcement Type": [
{
"value": "Debarred",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "Fraudulent Practices",
"source": "european-bank-ineligible-entities",
"tag": ""
},
{
"value": "Reprimand, debarment, conditional debarment or conditions on future contracting.",
"source": "america-idb",
"tag": ""
}
],
"Locationurl": [
{
"value": "https://lnadbg4.adb.org/oga0009p.nsf",
"source": "asian-development-bank",
"tag": ""
},
{
"value": "https://www.afdb.org/en/projects-operations/debarment-and-sanctions-procedures",
"source": "african-development-bank",
"tag": ""
},
{
"value": "https://www.ebrd.com/ineligible-entities-list.html",
"source": "european-bank-ineligible-entities",
"tag": ""
},
{
"value": "https://www.iadb.org/en/transparency/sanctioned-firms-and-individuals",
"source": "america-idb",
"tag": ""
},
{
"value": "https://www.worldbank.org/en/projects-operations/procurement/debarred-firms",
"source": "debarred-firm-list",
"tag": ""
}
],
"offence": [
{
"value": "Fraud",
"source": "america-idb",
"tag": ""
}
],
"Other Info": [
{
"value": "The firms and individuals listed are ineligible to be awarded a World Bank-financed contract for the periods indicated because they have been sanctioned under the Bank's fraud and corruption policy.",
"source": "debarred-firm-list",
"tag": ""
},
{
"value": "The individuals and firms below have been sanctioned by the African Development Bank Group or by signatories to the Agreement for Mutual Enforcement of Debarment Decisions. Sanctions are imposed on entities found to have participated in coercive, collusive, corrupt, fraudulent or obstructive practices under the Bank's sanctions system or adopted under the Agreement for Mutual Enforcement of Debarment Decisions.",
"source": "african-development-bank",
"tag": ""
}
],
"Related URL": [
{
"value": "https://www.iadb.org/en/transparency/sanctioned-firms-and-individuals",
"source": "america-idb",
"tag": "related_url"
}
],
"Termination Date": [
{
"value": "28 Jun 2025",
"source": "european-bank-ineligible-entities",
"tag": ""
},
{
"value": "28-Jun-2025",
"source": "debarred-firm-list",
"tag": ""
},
{
"value": "28/Jun/2025",
"source": "asian-development-bank",
"tag": ""
}
],
"Countries": [
{
"value": "Kenya",
"source": "",
"tag": "country_names"
}
]
},
"media": [],
"source_notes": {
"african-development-bank": {
"aml_types": [
"fitness-probity"
],
"country_codes": [
"KE"
],
"listing_started_utc": "2022-07-28T00:00:00Z",
"name": "African Development Bank Debarment and Sanctions Procedures",
"url": "http://www.afdb.org/en/projects-and-operations/procurement/debarment-and-sanctions-procedures/"
},
"america-idb": {
"aml_types": [
"fitness-probity"
],
"country_codes": [
"KE"
],
"listing_started_utc": "2022-08-03T00:00:00Z",
"name": "Inter-American Development Bank Disciplined Firms and Individuals",
"url": "http://www.iadb.org/en/topics/transparency/integrity-at-the-idb-group/sanctioned-firms-and-individuals,1293.html"
},
"asian-development-bank": {
"aml_types": [
"warning"
],
"country_codes": [
"KE"
],
"listing_started_utc": "2022-07-06T00:00:00Z",
"name": "Asian Development Bank Sanctions",
"url": "https://lnadbg4.adb.org/oga0009p.nsf"
},
"debarred-firm-list": {
"aml_types": [
"warning"
],
"country_codes": [
"KE"
],
"listing_started_utc": "2022-07-08T00:00:00Z",
"name": "World Bank Debarred Firm List",
"url": "http://www.worldbank.org/en/projects-operations/procurement/debarred-firms"
},
"european-bank-ineligible-entities": {
"aml_types": [
"fitness-probity"
],
"country_codes": [
"KE"
],
"listing_started_utc": "2022-12-22T00:00:00Z",
"name": "European Bank for Reconstruction and Development (EBRD) ineligible entities",
"url": "https://www.ebrd.com/ineligible-entities-list.html"
}
},
"sources": [
"african-development-bank",
"america-idb",
"asian-development-bank",
"debarred-firm-list",
"european-bank-ineligible-entities"
],
"types": [
"fitness-probity",
"warning"
]
}
]
}
}
},
"verification_result": {
"aml_for_businesses": 0
},
"info": {
"agent": {
"is_desktop": true,
"is_phone": false,
"useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
"device_name": "Macintosh",
"browser_name": "",
"platform_name": "OS X - 10_14_0"
},
"geolocation": {
"host": "212.103.50.243",
"ip": "212.103.50.243",
"rdns": "212.103.50.243",
"asn": "9009",
"isp": "M247 Ltd",
"country_name": "Germany",
"country_code": "DE",
"region_name": "Hesse",
"region_code": "HE",
"city": "Frankfurt am Main",
"postal_code": "60326",
"continent_name": "Europe",
"continent_code": "EU",
"latitude": "50.1049",
"longitude": "8.6295",
"metro_code": "",
"timezone": "Europe/Berlin"
}
},
"declined_reason": "AML screening failed. Business found in Fitness-Probity lists.",
"declined_codes": [
"SPDR184",
"SPDR34"
],
"services_declined_codes": {
"aml_for_businesses": [
"SPDR184",
"SPDR34"
]
}
}
{
"reference": "17374217",
"event": "request.invalid",
"error": {
"service": "background_checks",
"key": "dob",
"message": "The dob does not match the format Y-m-d."
},
"email": null,
"country": null
}
{
"reference": "",
"event": "request.unauthorized",
"error": {
"service": "",
"key": "",
"message": "Authorization keys are missing/invalid."
},
"email": null,
"country": null"
}
{
"reference": "17374217",
"event": "verification.status.changed"
}
{
"reference": "17374217",
"event": "request.deleted"
}
Verification Response
Responses will contain the following parameters:
Parameters | Description |
---|---|
reference | Your unique request reference, which you provided us at the time of request, so that you can identify the response in relation to the request made. |
events | This is the request event which shows status of request. Event is changed in every response. Please consult Events for more information. |
error | Whenever there is an error in your request, this parameter will have the details of that error. |
token | This is the unique request token of the request. |
verification_result | It is only returned in case of a valid verification. This includes results of each verification. 1 means accepted 0 means declined null means not processed Check verification.accepted and verification.declined responses in Events section for a sample response. |
verification_data | It is only returned in case of a valid verification. This object will include the all the gathered data in a request process. Check verification.accepted and verification.declined responses in Events section for a sample response. |
info | This object will be returned in case of verification.accepted or verification.declined. It contains the following keys: Agent provides information about the device and browser of the end-user. Geolocation provides information about the geographical location of the end-user. For Details on info object go to Info |
declined_reason | This parameter will have the reason due to which a verification has been declined, and is only returned in this case in the callback URL. For more info click here |
declined_codes | This array contains status codes of all declined verification reasons. It will return only for verification.declined. For more info click here |
services_declined_codes | This object contains status codes of declined reasons for each service separately. Each service object will contain an array of status codes for declined reasons specific to that service. It will return only for verification. declined. For more info click here |
Callback response will be sent on the callback_url provided in the request callback_url parameter.
Status Response
The Shufti Pro Verification API will send a JSON response if a status request is made. Make sure to validate the request by generating signature and matching it with the Signature value from the response header.
Parameters | Description |
---|---|
reference | Your unique request reference, which you provided us at the time of request, so that you can identify the response in relation to the request made. |
event | This is the request event which shows status of request. Event is changed in every response. Please consult Events for more information. |
country | This contains country code sent by the merchant at the time of request. Country code in the format of ISO 3166-1 alpha-2. Please consult Supported Countries for country codes. Type: string Example: DE null if not provided by merchant. |
verification_data | This contains all the data used for verification. This will only be returned in case of verification.accepted or verification.declined. |
verification_result | This is the complete result of the verification. 1 stands for verified, 0 for not verified and null for no verification performed. This will only be returned in case of verification.accepted or verification.declined. |
info | This object will be returned in case of verification.accepted or verification.declined. It contains the following keys: Agent provides information about the device and browser of the end-user. Geolocation provides information about the geographical location of the end-user. For Details on info object go to Info |
declined_reason | This key will only be returned when event is verification.declined. This will contain the reason why verification was declined. |
declined_codes | This array contains status codes of all declined verification reasons. It will return only for verification.declined. |
services_declined_codes | This object contains status codes of declined reasons for each service separately. Each service object will contain an array of status codes for declined reasons specific to that service. It will return only for verification. declined. |
request.invalid response with HTTP status code 400 means the request is invalid.
Delete Request Response
The Shufti Pro Verification API will send a JSON response if a delete request is made. Make sure to validate the request by generating signature and matching it with the Signature value from the response header
Parameters | Description |
---|---|
reference | Your unique request reference, which you provided us at the time of request, so that you can identify the response in relation to the request made. |
event | This is the request event which shows status of request. Event is changed in every response. |
Please consult Events for more information.
request.invalid will be returned in case of invalid reference provided or the request is already deleted.
//Content-Type: application/json
//Signature: NmI4NmIyNzNmZjM0ZmNl
{
"reference": "17374217",
"event": "request.deleted"
}
Response Signature
Every HTTP and Callback response will be in application/JSON with a key Signature in the header. It can be used to validate the source of the request. Make a signature using the following procedure:
- Concatenate Secret Key at the end of the raw response string. (i.e. response + secret_key).
- Take SHA256 of concatenated string.
- Match the SHA256 string with Signature value from the header of the response.
In short, make signature as mentioned format and match it with the signature provided in the header in Signature key.
hash('sha256', response . your_secret_key)
The clients who are registered with shuftipro after 15th March, 2023. They need to make the signature using the following procedure.
- Take SHA256 of Secret Key string.
- Concatenate hashed Secret Key at the end of the raw response string. (i.e. response + hash('sha256', secret_key)).
- Take SHA256 of concatenated string.
- Match the SHA256 string with Signature value from the header of the response.
hash('sha256', response . hash('sha256', secret_key))