Panama

Civil validation service for Panama. Performs identity verification against the Panama Civil Registry data.

Endpoint

POST /services/civilValidation

Headers

Name	Type	Required	Description
x-api-key	string	Yes	API Key for access authorization.
family	string	No	Value: Onboarding. Required with the tracking service.

All calls to the tracking Endpoints with Identity Platform must contain the header family.

Full Validation Mobile

Performs data validation and facial matching against the Panama Civil Registry using a mobile platform.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
operation	string	Yes	Validation operation to be performed. Value: "FULL".
platform	string	Yes	Platform from which the request is made. Value: "MOBILE".
tokenOcr	string	Yes	Token generated by the native or hybrid SelphID Widget, encrypted in AES256 and Tokenized, sent in Base64 format. Contains the OCR result of the captured Identity document.
bestImage	string	Yes	Open image of the user's face. Required for FACIAL or FULL operations.
countryCode	string	Yes	Country code in ISO 3166-1 alpha-3 format. Value: "PAN".
returnPII	boolean	No	Indicates whether the personal data generated by the OCR service and the Civil Registry response should be received.
documentValidation	boolean	No	Indicates whether the document validation should be started, returning scanReference and type.
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains Tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Request example

{
  "operation": "FULL",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "bestImage": "base64BestImageString",
  "countryCode": "PAN",
  "returnPII": false,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code indicating the overall result of the service execution. See Service Result Code.
serviceTime	string	Total processing time (milliseconds).
serviceResultLog	string	Descriptive field of the result of the service execution. Includes details when there is an error or exception.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
civilDataValidation	array	Array representing the OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried.
civilDataValidation[].field	string	Validated field name (e.g. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Validation result code. "0": Correctly validated. "-99": Possibly adulterated.
civilDataValidation[].message	string	Descriptive message of the validation result.
serviceFacialAuthenticationResult	integer	Code indicating the result of the facial matching. See Service Facial Authentication Result.
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the face in the document photo and the user's selfie. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Integrity hash of the biometric template used in a positive or uncertain facial authentication.
serviceDocument	string	JSON string representing the captured document. Its properties are all fields extracted by the OCR process.
civilServiceData	string	JSON string with the personal data obtained from the Civil Registry (only returned if returnPII was sent as true in the request).

Response example

{
  "serviceResultCode": 0,
  "serviceTime": "1799",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "f0392b79-664c-476f-8fad-d30009b68d60",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.9946,
  "serviceFacialAuthenticationHash": "NA",
  "serviceDocument": "{\"Back/INPUT/Issuer\":\"PAN\",\"Back/ML/DateOfBirth\":\"13/04/1964\",\"Back/ML/DateOfExpiry\":\"16/04/2023\",\"Back/ML/DocumentNumber\":\"1 0627 0723\",\"Back/ML/ElectoralAddress\":\"\",\"Back/ML/FatherName\":\"LUOOT NOT. HOSPITAL CENTRAL SAN JOSE\",\"Back/ML/Gender\":\"\",\"Back/ML/MotherName\":\"XO F\",\"Back/ML/PlaceOfBirth\":\"Domicilio Ectoral SAN BOSCO CENTRAL SAN JOSE\",\"DateOfBirth\":\"13/04/1964\",\"DateOfExpiry\":\"16/04/2023\",\"DocumentCaptured\":\"CR/All\",\"DocumentNumber\":\"1 0627 0723\",\"FirstName\":\"\",\"Front/INPUT/Issuer\":\"PAN\",\"Front/ML/CC\":\".:\")}",
  "civilServiceData": "{\"nombres\":\"APUY STIER\",\"fechaNacimiento\":\"13/04/1964\",\"fechaVencimiento\":\"16/04/2023\",\"lugarNacimiento\":\"SAN BOSCO CENTRAL SAN JOSE\"}"
}

Full Validation Web

Performs data validation and facial matching against the Panama Civil Registry using a web platform.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
operation	string	Yes	Validation operation to be performed. Value: "FULL".
platform	string	Yes	Platform from which the request is made. Value: "WEB".
imageFrontDocument	string	Yes	Front capture of the document, image in Base64 without the MIME type header. Required for WEB platform.
imageBackDocument	string	Yes	Back capture of the document, image in Base64 without the MIME type header. Required for WEB platform.
bestImage	string	Yes	Open image of the user's face. Required for FACIAL or FULL operations.
countryCode	string	Yes	Country code in ISO 3166-1 alpha-3 format. Value: "PAN".
returnPII	boolean	No	Indicates whether the personal data generated by the OCR service and the Civil Registry response should be received.
documentValidation	boolean	No	Indicates whether the document validation should be started, returning scanReference and type.
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains Tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Request example

{
  "operation": "FULL",
  "platform": "WEB",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "bestImage": "base64BestImageString",
  "countryCode": "PAN",
  "returnPII": false,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code indicating the overall result of the service execution. See Service Result Code.
serviceTime	string	Total processing time (milliseconds).
serviceResultLog	string	Descriptive field of the result of the service execution. Includes details when there is an error or exception.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
civilDataValidation	array	Array representing the OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried.
civilDataValidation[].field	string	Validated field name (e.g. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Validation result code. "0": Correctly validated. "-99": Possibly adulterated.
civilDataValidation[].message	string	Descriptive message of the validation result.
serviceFacialAuthenticationResult	integer	Code indicating the result of the facial matching. See Service Facial Authentication Result.
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the face in the document photo and the user's selfie. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Integrity hash of the biometric template used in a positive or uncertain facial authentication.
serviceDocument	string	JSON string representing the captured document. Its properties are all fields extracted by the OCR process.
civilServiceData	string	JSON string with the personal data obtained from the Civil Registry (only returned if returnPII was sent as true in the request).

Response example

{
  "serviceResultCode": 0,
  "serviceTime": "4074",
  "serviceResultLog": "Negative | Service executed ok",
  "serviceTransactionId": "e1243a68-be8f-464c-94a7-e8a5562d71a0",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0,
  "serviceFacialAuthenticationHash": "NA",
  "serviceDocument": "{\"ASK4BACK\":\"NO\",\"BACKSIDE\":{\"FIELD_DATA\":{\"ADDRESS\":\"SAN RAFAEL POAS ALAJUELA\",\"BARCODES\":[{\"DATA\":\"\",\"TYPE\":\"\"}],\"BIRTH_DATE\":\" 19 10 1984\",\"BIRTH_PLACE\":\"CENTRO CENTRAL ALAJUELA\",\"EXPIRATION_DATE\":\" 07 02 2028\",\"FATHER_NAME\":\"LUIS RODRIGUEZ CASTRO\",\"IDENTITY_NUMBER\":\"205990558\",\"MOTHER_NAME\":\"FLORA ISABEL QUESADA CASTRO\",\"SEX\":\"\",\"VERTICAL_NUMBER\":\"000631975\"}},\"CHECKS\":{\"IDENTITY_NUMBER_SIDE_MATCH\":true},\"COUNTRY_CODE\":\"PAN\",\"DOC_MODEL\":\"NEW\",\"FRONTSIDE\":{\"FIELD_DATA\":{\"FIRST_SURNAME\":\"RODRIGUEZ\",\"IDENTITY_NUMBER\":\"205990558\",\"NAME\":\"LUIS\",\"SECOND_SURNAME\":\"QUESADA\"}},\"SCORING\":{\"BACK_CONFIDENCE\":0.976855586876,\"BACK_SHA256\":\"4dfb73e9c8cbba6db42d1e4938ba1e62244bfe26efecd55579a4f65c9aed63ae\",\"FIELDS_RETURNED\":15,\"FIELDS_TOTAL\":15,\"FRONT_CONFIDENCE\":0.922833224138,\"FRONT_SHA256\":\"506b3192e0e80f851012f895300c63e8c85fea0ca78b9d99195e6256afadc5d4\",\"OVERALL_RATING\":100.0,\"OVERALL_SIDE_CORRESPONDENCE\":100.0}}",
  "civilServiceData": "{\"nombres\":\"LUIS RODRIGUEZ QUESADA\",\"fechaNacimiento\":\"19/10/1984\",\"lugarNacimiento\":\"CENTRO CENTRAL ALAJUELA\",\"direccion\":\"SAN RAFAEL POAS ALAJUELA\"}"
}

Facial Validation Mobile

Performs facial matching against the official images of the Panama Civil Registry using a mobile platform. Does not include data validation.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
operation	string	Yes	Validation operation to be performed. Value: "FACIAL".
platform	string	Yes	Platform from which the request is made. Value: "MOBILE".
bestImage	string	Yes	Open image of the user's face. Required for FACIAL or FULL operations.
documentNumber	string	No	User document number.
countryCode	string	Yes	Country code in ISO 3166-1 alpha-3 format. Value: "PAN".
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains Tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Request example

{
  "operation": "FACIAL",
  "platform": "MOBILE",
  "bestImage": "base64BestImageString",
  "documentNumber": "1 0627 0723",
  "countryCode": "PAN",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code indicating the overall result of the service execution. See Service Result Code.
serviceTime	string	Total processing time (milliseconds).
serviceResultLog	string	Descriptive field of the result of the service execution. Includes details when there is an error or exception.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
civilDataValidation	array	Array representing the OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried.
civilDataValidation[].field	string	Validated field name (e.g. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Validation result code. "0": Correctly validated. "-99": Possibly adulterated.
civilDataValidation[].message	string	Descriptive message of the validation result.
serviceFacialAuthenticationResult	integer	Code indicating the result of the facial matching. See Service Facial Authentication Result.
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the face in the document photo and the user's selfie. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Integrity hash of the biometric template used in a positive or uncertain facial authentication.

Response example

{
  "serviceResultCode": 0,
  "serviceTime": "2800",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "24681357-2468-1357-9024-246813579024",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.94,
  "serviceFacialAuthenticationHash": "NA"
}

Facial Validation Web

Performs facial matching against the official images of the Panama Civil Registry using a web platform. Does not include data validation.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
operation	string	Yes	Validation operation to be performed. Value: "FACIAL".
platform	string	Yes	Platform from which the request is made. Value: "WEB".
bestImage	string	Yes	Open image of the user's face. Required for FACIAL or FULL operations.
documentNumber	string	No	User document number.
countryCode	string	Yes	Country code in ISO 3166-1 alpha-3 format. Value: "PAN".
tracking	object	No	Object representing the necessary tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. Contains Tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Request example

{
  "operation": "FACIAL",
  "platform": "WEB",
  "bestImage": "base64BestImageString",
  "documentNumber": "205990558",
  "countryCode": "PAN",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
serviceResultCode	integer	Code indicating the overall result of the service execution. See Service Result Code.
serviceTime	string	Total processing time (milliseconds).
serviceResultLog	string	Descriptive field of the result of the service execution. Includes details when there is an error or exception.
serviceTransactionId	string	Transaction identifier associated with the request processed by the API.
civilDataValidation	array	Array representing the OCR validations against the data obtained from the Civil Registry. Its presence depends on the Civil Registry queried.
civilDataValidation[].field	string	Validated field name (e.g. firstName, lastName, dateOfBirth).
civilDataValidation[].code	string	Validation result code. "0": Correctly validated. "-99": Possibly adulterated.
civilDataValidation[].message	string	Descriptive message of the validation result.
serviceFacialAuthenticationResult	integer	Code indicating the result of the facial matching. See Service Facial Authentication Result.
serviceFacialSimilarityResult	number	Value indicating the facial similarity between the face in the document photo and the user's selfie. 1.0 = 100%.
serviceFacialAuthenticationHash	string	Integrity hash of the biometric template used in a positive or uncertain facial authentication.

Response example

{
  "serviceResultCode": 0,
  "serviceTime": "3200",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "87654321-4321-4321-4321-210987654321",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.15,
  "serviceFacialAuthenticationHash": "NA"
}

Reference tables

Service Result Code

The serviceResultCode indicates the overall result of the service execution:

serviceResultCode	Description	HTTP code
0	The service execution was successful, the module processed the request correctly.	200

Service Facial Authentication Result

The serviceFacialAuthenticationResult indicates the result of the facial matching operations (only for FULL and FACIAL operations):

Code	Result	Description
0	NONE	Facial verification could not be performed.
1	NEGATIVE	The process was executed successfully. The comparison of the facial pattern of the faces does not match.
3	POSITIVE	The process was executed successfully. The comparison of the facial pattern of the faces is positive. The value of serviceFacialSimilarityResult indicates the % similarity between the compared images.
4	NONE BECAUSE POSE EXCEED	Facial verification could not be performed due to the face position.
5	NONE BECAUSE INVALID EXTRACTIONS	Facial verification could not be performed due to problems in extracting the facial pattern.

Common errors

400 Bad Request

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}