/civilValidation

Description

This service performs facial matching and/or data validation between the properties sent and the data from the Civil Registry.

Supported Countries

The civilValidation service supports the following countries, based on the ISO 3166-1 alpha-3 format:

Ecuador (ECU)
Costa Rica (CRI)
Argentina (ARG)
Peru (PER)
Guatemala (GTM)
Panama (PAN)
Honduras (HND)

Request:

curl --location '{IDENTITY_API_BASE_URL}/services/civilValidation' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
  "operation": "FULL",
  "platform": "WEB",
  "documentNumber": "123456789",
  "imageFrontDocument": "base64ImageString",
  "imageBackDocument": "base64ImageString",
  "countryCode": "ARG",
  "tokenOcr": "base64TokenString",
  "bestImage": "base64BestImageString",
  "gender": "M",
  "templateRaw": "base64TemplateString",
  "documentCode": "12345",
  "documentValidation": true,
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}'

Request Parameters

Parameter	Type (Content)	Required	Description
operation	String	Yes	Validation operation to perform, possible values: FACIAL: Performs facial matching against the official image from the Civil Registry DATA: Data validation against Civil Registry data FULL: Data validation and facial matching against the Civil Registry
platform	String	Yes	Platform on which the request is made, possible values: WEB: Request made with web widgets MOBILE: Request made with mobile widgets
documentNumber	String	No	User's document number. Required if operation = FACIAL.
imageFrontDocument	String (Base64)	No	Front capture of the document, base64 image without the mime type header. Required if: platform = WEB operation = FACIAL and documentNumber is empty
imageBackDocument	String (Base64)	No	Back capture of the document, base64 image without the mime type header. Required if: platform = WEB operation = FACIAL and documentNumber is empty
countryCode	String	No	Country code in ISO 3166-1 alpha-3 format. Required if: platform = WEB or platform = MOBILE and operation = FACIAL and documentNumber is not empty
tokenOcr	String (Base64)	No	Token generated by the native or hybrid SelphID widget, AES256 encrypted and tokenized, sent in Base64 format. Contains the OCR result generated from the identity document capture. Required if: platform = MOBILE or operation = FACIAL and documentNumber is empty
bestImage	String (Base64)	No	BestImage property generated by the Selphi widget. Required if: operation = FACIAL or FULL and countryCode = ARG or PAN
gender	String	No	Gender of the individual to consult, possible values are “M” or “F”. Required if documentIssuer = ARG and documentNumber is not empty.
templateRaw	String (Base64)	No	Biometric template, property generated by the Selphi widget. Required if: operation = FACIAL or FULL
documentCode	String	No	Document code (fingerprintCode), necessary for document validation in Ecuador. Also received as idTramite (optional) for Renaper (Argentina). Required if: countryCode = ECU
documentValidation	Boolean	No	Indicates if document validation is to be initiated, returning scanReference and type. The documentation and exposure as a resource for document validation is found separately in the FPhi.API documentValidation specification.
returnPII	Boolean	No	Indicates if personal data generated by both the OCR service and the Civil Registry response is to be received.
tracking	JSON Object	No	Object that represents necessary tracking information.
extraData	String (Base64)	No	Token generated by Mobile/Web SDK. Contains tokenized tracking information with Platform.
operationId	String (Base64)	No	Operation identifier generated by Mobile/Web SDK.

precaución

Depending on the integration with the Civil Registry, the use of templateRaw or bestImage may vary. For some countries and their respective integrations, it is necessary to send bestImage or templateRaw. Please check the specific requirements for each country.

Additionally, some countries require documentNumber, documentCode, and gender. Please also check these specific requirements.

Example response:

200 OK

Content-Type: application/json

{
    "serviceResultCode": 0,
    "serviceTime": "2812",
    "serviceResultLog": "Positive | Service executed ok",
    "serviceTransactionId": "81e9db11-4501-48e0-9021-d2eccc536ece",
    "civilDataValidation": [
        {
            "field": "firstName",
            "code": "0",
            "message": "Validated ok"
        },
        {
            "field": "lastName",
            "code": "0",
            "message": "Validated ok"
        },
        {
            "field": "dateOfBirth",
            "code": "0",
            "message": "Validated ok"
        }
    ],
    "serviceFacialAuthenticationResult": 3,
    "serviceFacialSimilarityResult": 0.9919787,
    "serviceFacialAuthenticationHash": "309C36558C983358CEF98E811EFDA5F302023F894E2DBB66CE7BFDE56E4B4C0F28D0805C769B0C4CF7EED412EDDCC23BE7EA2637862CC634B2074DB77FA91AB5",
    "serviceDocument": {
        "documentNumber": "123456789",
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "01/01/1980",
        "gender": "M",
        "nationality": "Nationality",
        "dateOfExpiry": "01/01/2030",
        "placeOfBirth": "Location",
        "dateOfIssue": "01/01/2020",
        "civilStatus": "Single"
    },
    "civilServiceData": {
        "lastName": "Doe",
        "firstName": "John",
        "dateOfBirth": "01/01/1980",
        "gender": "Male",
        "nationality": "Nationality",
        "civilStatus": "Single",
        "address": "Address",
        "city": "City",
        "province": "Province",
        "country": "Country",
        "documentNumber": "123456789",
        "issueDate": "01/01/2020",
        "expiryDate": "01/01/2030",
        "spouseName": "Spouse Name",
        "motherName": "Mother Name",
        "fatherName": "Father Name",
        "photoUrl": "https://cdn.example.com/photo.jpeg",
        "signatureUrl": "https://cdn.example.com/signature.jpeg"
    }
}

nota

This is an example response for a FULL operation. The serviceDocument depends on the document modeling, and the civilServiceData depends on the response provided by the service. Some fields may or may not be present depending on the integration with the Civil Registry

Response fields:

Identifier	Type	Description
serviceResultCode	Integer	Code indicating the overall result of the service execution. See Table 1 - Service Result Code.
serviceTime	String	Field indicating the processing time.
serviceResultLog	String	Descriptive field of the service execution result. Includes details when there is an error or exception in the module.
serviceTransactionId	String	Transaction identifier associated with the request processed by the API.
civilDataValidation	String	Object representing the OCR validations against the data obtained from the Civil Registry. The presence of this object depends on the consulted Civil Registry.
serviceFacialAuthenticationResult	Integer	Code indicating the result of the facial matching. See Table 2 - Service Facial Authentication Result.
serviceFacialAuthenticationHash	String	Integrity hash of the biometric template used in a positive or uncertain facial authentication.
serviceFacialSimilarityResult	Float	Value indicating the facial similarity between the face in the identity document photo and the selfie taken by the user. 1.0 = 100%.
serviceDocument	JSON	Object representing the captured document. Its properties are all the fields extracted by the OCR process.
civilServiceData	JSON	Object representing the personal data obtained from the Civil Registry (returned only if returnPII was sent as true in the request).

Description​

Supported Countries​

Request Parameters​

Response fields:​

Description

Supported Countries

Request Parameters

Response fields: