> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt
> Use this file to discover all available pages before exploring further.
# Secure Citizen Lookup Refugee verification call
> This is a service that requests the Identity Information of a consumer for use in an identity validation process and conducts a liveness check of the selfie provided for biometric verification.
A combination of either the ID number and the name and surname or the client's photo is required to return a match.
This is inline with recommendations from the SAFPS to ensure data is shared with the correct consumer.
## OpenAPI
````yaml products/didx-verify/api-reference/v1/openapi.json post /Citizen/RefugeeVerification
openapi: 3.0.1
info:
title: SecureCitizen.Citizen.Api
description: >-
This is the API documentation for Secure Citizen products. Should you
require further information please contact us on the email provided.
contact:
name: Api Contant Name
email: support@securecitizen.co.za
license:
name: Proprietary
url: https://www.securecitizen.co.za
version: v1
x-logo:
url: >-
https://securecitizen.co.za/wp-content/uploads/2022/11/Untitled-design-14.svg
altText: Secure Citizen
servers:
- url: https://citizen.uat.securecitizen.cloud
security: []
tags:
- name: Citizen
description: This details information we can replace to describe this endpoint
- name: CitizenV
description: This details information we can replace to describe this endpoint
- name: CustomClient
description: This details information we can replace to describe this endpoint
- name: Partner
description: This details information we can replace to describe this endpoint
paths:
/Citizen/RefugeeVerification:
post:
tags:
- Citizen
summary: Secure Citizen Lookup Refugee verification call
description: "This is a service that requests the Identity Information of a consumer for use in an identity validation process and conducts a liveness check of the selfie provided for biometric verification.\r\nA combination of either the ID number and the name and surname or the client's photo is required to return a match.\r\nThis is inline with recommendations from the SAFPS to ensure data is shared with the correct consumer."
operationId: RefugeeVerification
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefugeeVerificationRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/RefugeeVerificationProblemDetails'
examples:
ABCDEF01345678:
value:
type: null
title: Citizen Api Output
status: 200
details: Details of the output
instance: /Citizen/RefugeeVerification
response:
TrackingNumber: string
CachedResult: true
firstNameResult: '70'
lastNameResult: '70'
niisFileNumber: ABCDEF01345678
FaceResult:
isIdentical: true
confidence: 1
LivenessResult:
LivenessResultScore: 1
LivenessResultProbability: 0.8
LivenessResultQuality: 0.8
LivenessResultClass: false
LivenessPassResult: true
LivenessMessage: Liveness check successful
firstName: FirstName
lastName: LastName
gender: string
birthDate: string
age: 30
country: Country
nationality: Nationality
alternativeFileNumber: null
officeOfApplication: Office
fileStatus: Status
permitNumber: Permit Number
expiryDate: Monday, 12/02/2024; 24:00
refugeeIDNumber: Refugee Id Number
facialImage: string
CRef: string
Status: Success
Message: string
'401':
description: Unauthenticated
'403':
description: Unauthorized access to this resource
'500':
description: Cat-as-trophy
security:
- oauth2:
- sc-citizen
components:
schemas:
RefugeeVerificationRequest:
required:
- ConsentReceived
- FileNumber
- RequestReason
type: object
properties:
CRef:
title: Client Reference
type: string
description: "Example: \"REF00001\"\r\n\r\nThis is the unique transaction reference number that can be supplied by the controller. This will be provided in response messages related to the transaction and will be required for identifying transactions for support purposes."
format: string
nullable: true
ConsentReceived:
title: Consent Received
type: boolean
description: "Example: true\r\n\r\nThis is an indicator to audit the fact that the controller has obtained consent from the subject to process their personal information and data as per the regulatory requirements pertaining to local and global privacy and data protection legislation."
format: bool
Subsidiary:
title: Subsidiary
type: string
description: >-
In this field, the client should indicate who the verification is
done by/for where it is not for a known client of Secure Citizen.
format: string
nullable: true
FileNumber:
title: ID Number
minLength: 1
type: string
description: >-
This is the ID number that a client wishes to run an identity
validation query on.
format: string
LivenessRequired:
title: LivenessRequired
type: boolean
description: >-
In this field the client would indicate whether they want a liveness
check on the image provided by the consumer.
NIISImageRequired:
title: NIIS Image Required
type: boolean
description: >-
This specifies whether the client would like the image of the
consumer found in the National Immigration Information System.
FirstNames:
title: Firstnames
type: string
description: >-
Firstnames of the person being looked up. Required if FaceString is not provided
nullable: true
LastName:
title: Lastname
type: string
description: >-
Lastname of the person being looked up. Required if FaceString is not provided
nullable: true
FaceString:
title: Face String
type: string
description: >-
Image of the person being looked up. Required if FirstNames and LastName not
provided
nullable: true
RequestReason:
title: Request Reason
minLength: 1
type: string
description: Reason why lookup was requested.
MobileNumber:
title: Mobile Number
type: string
description: Mobile Number. Mobile number provided should be 0xxx.
nullable: true
additionalProperties: false
RefugeeVerificationProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
details:
type: string
nullable: true
instance:
type: string
nullable: true
response:
$ref: '#/components/schemas/RefugeeVerificationResponse'
additionalProperties: false
RefugeeVerificationResponse:
type: object
properties:
CRef:
title: Client Reference
type: string
description: >-
This field will return the reference provided by the client to track
the transaction.
format: string
nullable: true
Status:
$ref: '#/components/schemas/ExternalStatusEnums'
Message:
title: Message
type: string
description: >-
This will return a status of the transaction s well as external
tracking information.
format: string
nullable: true
TrackingNumber:
title: Tracking Number
type: string
description: Tracking number
nullable: true
CachedResult:
title: Cached Result
type: boolean
description: Indicated whether result came from cache or not
firstNameResult:
title: First Name Result
type: string
description: >-
Score that represents similarity between given first name and the
one gotten from DHA
nullable: true
lastNameResult:
title: Last Name Result
type: string
description: >-
Score that represents similarity between given last name and the one
gotten from DHA
nullable: true
niisFileNumber:
title: File Number of the refugee
type: string
description: File Number of the refugee
nullable: true
FaceResult:
$ref: '#/components/schemas/VerifyResult'
LivenessResult:
$ref: '#/components/schemas/IDRNDParialResponse'
firstName:
type: string
nullable: true
lastName:
type: string
nullable: true
gender:
type: string
nullable: true
birthDate:
type: string
nullable: true
age:
type: integer
format: int32
nullable: true
country:
type: string
nullable: true
nationality:
type: string
nullable: true
alternativeFileNumber:
type: string
nullable: true
officeOfApplication:
type: string
nullable: true
fileStatus:
type: string
nullable: true
permitNumber:
type: string
nullable: true
expiryDate:
type: string
nullable: true
refugeeIDNumber:
type: string
nullable: true
facialImage:
type: string
nullable: true
additionalProperties: false
ExternalStatusEnums:
title: Status
enum:
- Success
- Failure
- Unknown
- AuthFailure
- DataDeserializationError
- EmptyResults
- ErrorContactSupport
- FaceDetectionFailure
- FaceComparisonFailure
- NoStatusDefined
- FaceDetectionQualityTooLow
- FaceDetectionTooManyFaces
- FaceDetectionNoFacesFound
- FaceComparisonError
- FaceComparisonNotSame
- GoldenSourceImageNull
- ProvidedImageNull
- GoldenSourceNoFacesFound
- ProvidedImageNoFacesFound
- GoldenSourceHasTooManyFaces
- ProvidedImageHasTooManyFaces
- GoldenSourceQualityTooLow
- ProvidedImageQualityTooLow
- GoldenSourceGUIDIncorrect
- ProvidedImageGUIDIncorrect
- FaceAPIGeneralError
- FaceAPIPublicUrlInputError
- FaceBadInput
- GoldenSourceIncorrectStringFormat
- ProvidedImageIncorrectStringFormat
- SAFPSNPROk
- SAFPSHANISOk
- SAFPSNIISOk
- SAFPSNPRSlow
- SAFPSHANISSlow
- SAFPSNIISSlow
- SAFPSFailure
- SAFPSPossibleFailure
- SAFPSNPRFailure
- SAFPSHANISFailure
- SAFPSNIISFailure
- FaceTooClose
- EyesClosed
- FaceCloseToBorder
- FaceCropped
- FaceIsOccluded
- FaceNotFound
- TooManyFaces
- FaceTooSmall
- AbsoluteFaceTooSmall
- RelativeFaceTooSmall
- FaceAngleTooLarge
- FailedToPredictLandmarks
- Active
- CSuccess
- AsyncCSuccess
- IdentificationNumberInvalid
- IdentificationNumberAgeBelow18
- UnableToVerifyIdentificationNumberOnDocument
- UnableToVerifyIdentificationNumberAtGoldenSource
- GoldenSourceUnavailable
- MandatoryInformationMissing
- NPRSuccess
- HANISNotAvailable
- InvalidIDNCheckDigitTestNotPassed
- NPRNotAvailableOnlyPhotoIsReturned
- IDNRIsNotCurrentlyAValidNPRIDNR
- IDNRIsMarkedForDeletion
type: string
description: >-
Status values (static strings) to be used for external connection
management
format: string
VerifyResult:
type: object
properties:
isIdentical:
type: boolean
confidence:
type: number
format: double
additionalProperties: false
IDRNDParialResponse:
type: object
properties:
LivenessResultScore:
title: Liveness Result Score
type: number
description: >-
This is the raw liveness score generated by the system. It's an
unbounded linear value where higher scores indicate a greater
likelihood that the input (e.g., a face) is from a live person. This
score is primarily used for calibration and tuning purposes, such as
adjusting the system's sensitivity to false positives or negatives.
format: double
LivenessResultProbability:
title: Liveness Result Probability
type: number
description: >-
This represents the system's calculated probability that the input
is from a live person, expressed as a value between 0 and 1. A value
greater than 0.5 typically indicates a live input, while a value
below 0.5 suggests a spoof or fake. This probability is the main
metric used to make liveness decisions.
format: double
LivenessResultQuality:
title: Liveness Result Quality
type: number
description: >-
This field assesses the quality of the input image in the context of
liveness detection. The quality score ranges from 0 (poor quality)
to 1 (high quality). A score below 0.5 generally indicates that the
image is unsuitable for reliable liveness analysis. Note that in
some contexts, this field may be deprecated in favor of more
detailed image quality warnings.
format: double
LivenessResultClass:
title: Liveness Result Class
type: boolean
description: >-
This field classifies the input based on its suitability for
liveness detection. For example, a value of 1 might indicate a
good-quality image suitable for analysis, while 0 could denote a
poor-quality image. However, this field is considered obsolete in
some versions of the model, with a recommendation to use the quality
score instead.
LivenessPassResult:
title: Liveness Pass Result
type: boolean
description: >-
This boolean field indicates whether the liveness check was passed.
A value of true means the input was determined to be live, while
false indicates a failure in the liveness check. This is a
straightforward pass/fail result based on the system's analysis.
readOnly: true
LivenessMessage:
title: Liveness Message
type: string
description: >-
This field likely provides a textual message or status related to
the liveness check, such as "Live," "Spoof," or "Invalid." It offers
a human-readable interpretation of the liveness result, which can be
useful for logging or user feedback.
nullable: true
readOnly: true
additionalProperties: false
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://sts.uat.securecitizen.cloud/connect/authorize
tokenUrl: https://sts.uat.securecitizen.cloud/connect/token
scopes:
sc-citizen: SecureCitizen.Citizen.Api
````