API Validations

Standalone API validations that are not related to any interview or onboarding process. This helps with various identity verifications specific to certain countries such as CURP and INE in Mexico or SSN in USA.

Token Validation

POST /api/validate/token

Validate an Incode released token.

Request:

• token: String, mandatory. Token issued by Incode

Response:

• status: Boolean. Flag indicating if token is valid or not.
• reason: String. Message explaining the status of the token.

Data source identity verification

POST /api/validate/identityRequest

This endpoint executes KYC verification and returns if any of the following matches a person: address, phone, identity or email

CountryCode must be in ISO2 format and can be obtained from https://en.wikipedia.org/wiki/ISO_3166-2

The Endpoint will return the full details of the findinsg in the findings field. Each data verification can have the following scores:

Response:

• Score: Integer. Possible values:
  • FullMatch (0, "Full match"),
  • PartialMatch (1, "Partial Match"),
  • NoMatch (2, "NoMatch")

SSN Validation

POST /api/validate/ssn

Validate a social security number and the person associated with it.

Request:

• ssn: String, mandatory. Person's social security number
• firstName: String, mandatory. Person's first name
• lastName: String, mandatory. Person's last name
• middleName: String, optional. Person's year of birth
• dateOfBirth: String, mandatory. Person's birthdate in format YYYY-MM-DD ex 1976-11-21
• email: String, optional. Person's email

Response:

• requestId: Int. Response's status, check catalog.
• ssnValid: Boolean. Indicates if ssn information sent is valid.
• deceasedPerson: Boolean. Indicates if information sent corresponds to a deceased person.
• errorCode: String. Error code in case something goes wrong.
• errorCodeDescription: String. Error description in case something goes wrong or if ssn is not valid.

INE scraping validation

POST /api/validate/ine

Check for valid INE directly with an automated search in https://listanominal.ine.mx/scpln/ and return corresponding values of that ID.

Scraping service will start working asynchronously and this service will return a resultsId to fetch the results in /omni/fetch-ine. The recommended wait time is 20 sec.

Possible parameters are ocr, cic, claveElector and numeroEmision but the parameters sent depend on the model of the INE/IFE to be consulted.

Model C: IFE with emission year from 2008 to 2013, should send claveElector, numeroEmision and ocr from the back of ID.

Model D: INE with emission year from 2013, should send cic from back of ID (9 characters) and OCR from the back of the ID (13 characters).

Model E,F,G,H: INE with emission year from 2014 onwards, should send CIC from the back of the ID (9 characters) and citizen id (ocr) from the back of the ID (9 characters).

Additional indications and information on the models of the credentials can be found in https://listanominal.ine.mx/scpln/

Request:

• ocr: String, mandatory.
• cic: String, mandatory (for model D,E,F,G,H).
• claveElector: String, mandatory (for model C).
• numeroEmision: String, mandatory (for model C, should have a length of 2: ex 02).

Response:

• idResults: String.

Fetch INE scraping results

POST /api/fetch/ine?idResults=irjgqioeghoiqegho

Fetch the results from /omni/validate-ine. The recommended wait time is 20 sec and retrying every 5 sec after that.

scrapingStatus possible values are: "IN_PROGRESS": service hasn't finished and should retry in 5 seconds. "FINISHED": scrapping service finished and we got either a successful response or an error such as curp not found. "ERROR": scrapping service had an unhandled error, another attempt should be sent to validate curp.

If INE is not found or an error occurs (such as service being in maintenance) then the success field will be false and the field resultDetails will have additional information.

Request Query Params:

• idResults: String.

Response:

• _id: String.
• scrapingStatus: String.
• success: Boolean.
• result: String.
• resultDetails: String.
• screenshotUrl: String.
• cic: Integer.
• claveElector: String.
• numeroEmision: Integer.
• ocr: String.
• anioRegistro: Integer.
• anioEmision: Integer.

CURP scraping validation

POST /api/validate/curp/v3

Check for valid CURP directly with an automated search in https://www.gob.mx/curp/ and return corresponding values of that person. Parameter must be "curp".

Scraping service will start working asynchronously and this service will return a resultsId to fetch the results in /omni/fetch-curp/v3. The recommended wait time is 25 sec.

Request:

• curp: String, mandatory.

Response:

• idResults: String.

Errors:

• Invalid curp: a 400 error will be thrown if the curp provided does not match the correct pattern.

CURP scraping validation by data

POST /api/validate/curp-by-data/v3

Check for valid CURP directly with an automated search in https://www.gob.mx/curp/ and return corresponding curp of that person. Parameters are the person's details.

Scraping service will start working asynchronously and this service will return a resultsId to fetch the results in /omni/fetch-curp/v3. The recommended wait time is 25 sec.

The valid birthDate format is dd/mm/yyy. Ex: february 5th 2020 -> 05/02/2020

The valid gender values are "H" (Hombre, male) and "M" (mujer, female).

Valid values for state are the ones listed by renapo in this link: https://es.wikipedia.org/wiki/Plantilla:Abreviaciones_de_los_estados_de_México

Request:

• name: String, mandatory.
• firstLastName: String, mandatory.
• secondLastName: String, mandatory.
• gender: String, mandatory.
• birthDate: String, mandatory.
• state: String, mandatory.

Response:

• idResults: String.

Errors:

• Bad request: a 400 error will be thrown if some of the required fields are missing.

Fetch CURP scraping results

POST /api/fetch/curp/v3?idResults=irjgqioeghoiqegho

Fetch the results from /api/validate/curp/v3. The recommended wait time is 25 secs and retrying every 5 secs after that.

Request Query Params:

• idResults: String.

Scraping status:

• IN_PROGRESS: Service hasn't finished and should retry in 5 seconds.
• FINISHED: Service finished and we got a result. Either a success or an error, such as curp not found.
• ERROR: Service had an unhandled error, a new attempt is recommended.

Result:

• success: Call finished and data was validated successfully.
• error: Invalid curp or data, exact details returned by the website can be found in the resultDetails field.
• timeout: Elements needed for scrapping were never found, isolated network issue, website down or website changed.
• maintenance: Elements indicating that the website is under maintenance have been found.
• unhandledError: Unhandled error occured during scrapping.

Response:

• _id: String.
• scrapingStatus: String.
• success: Boolean.
• result: String.
• resultDetails: String.
• screenshotUrl: String.
• curp: String.
• nombre: String.
• primerApellido: String.
• segundoApellido: String.
• sexo: String.
• nacionalidad: String.
• entidadNacimiento: String.
• documentoProbatorio: String.
• datosDocumentoProbatorio: Object with following fields.
  • municipioRegistro: String.
  • entidadRegistro: String.
  • numeroActa: Integer.
  • anioRegistro: Integer.

CURP validation v4

POST /api/validate/curp/v4

Check for valid CURP and return corresponding values of that person. Parameter must be "curp".

If CURP is not found then renapo_valid field will be false.

if CURP has invalid format or is not found an error object with details will be returned, for example:

{ "error": { "codigoError": "06", "message": "La CURP no se encuentra en la base de datos" }, "result": "Not valid request: La CURP no se encuentra en la base de datos code: 06", }

Request:

• curp: String, mandatory.

Response:

• success: Boolean.
• curp: String.
• sex: String.
• nationality: String.
• result: String.
• renapo_valid: Boolean.
• names: String.
• paternal_surname: String.
• mothers_maiden_name: String.
• birthdate: String.
• entity_birth: String.
• probation_document: String.
• probation_document_data: Object with following fields.
  • foja: String.
  • numEntidadReg: String.
  • libro: String.
  • NumRegExtranjeros: String.
  • cveEntidadNac: String.
  • numActa: String.
  • CRIP: String.
  • tomo: String.
  • cveEntidadEmisora: String.
  • anioReg: String.
  • cveMunicipioReg: String.
  • FolioCarta: String.
• status_curp: String.

CURP by data validation v4

POST /api/validate/curp-by-data/v4

Check for valid CURP based on a person data and return corresponding values of that person including the CURP.

The valid birthDate format is dd/mm/yyy. Ex: february 5th 2020 -> 05/02/2020

Valid gender values are "H" (Hombre, male) and "M" (mujer, female).

Valid values for state are the ones listed by renapo in this link: https://es.wikipedia.org/wiki/Plantilla:Abreviaciones_de_los_estados_de_México

If data doesn't match any CURP then the field renapo_valid will be false.

If there is an error with the request data an error object is returned with the details, example:"

{ "error": { "descripcionRespuesta": "DATOS INCORRECTOS: [El campo no cumple con el formato.]", "codigoRespuesta": "02", } }

Request:

• name: String, mandatory.
• firstLastName: String, mandatory.
• secondLastName: String, mandatory.
• gender: String, mandatory.
• birthDate: String, mandatory.
• state: String, mandatory.

Response:

• success: Boolean.
• curp: String.
• sex: String.
• nationality: String.
• result: String.
• probation_document_data: Object with following fields.
  • name: String.
  • firstLastName: String.
  • secondLastName: String.
  • gender: String.
  • birthDate: String.
  • state: String.
• renapo_valid: Boolean.
• names: String.
• paternal_surname: String.
• mothers_maiden_name: String.
• birthdate: String.
• entity_birth: String.
• probation_document: String.
• probation_document_data: Object with following fields.
  • foja: String.
  • numEntidadReg: String.
  • libro: String.
  • NumRegExtranjeros: String.
  • cveEntidadNac: String.
  • numActa: String.
  • CRIP: String.
  • tomo: String.
  • cveEntidadEmisora: String.
  • anioReg: String.
  • cveMunicipioReg: String.
  • FolioCarta: String.
• status_curp: String.

RFC validation by CURP

POST /api/validate/rfc-by-curp

Check for valid CURP, obtain corresponding RFC and values of that person and then validate the RFC.

Parameter must be "curp".

If CURP is not found then renapo_valid field will be false.

if CURP has invalid format an error object with details will be returned, example:

{ "error": { "curp": [ "PEPJ870918MVZRRS01a has not a valid CURP format." ] } }

Request:

• curp: String, mandatory.

Response:

• curp: String.
• homonimo: Boolean.
• sex: String.
• nationality: String.
• rfc: String.
• renapo_valid: Boolena.
• names: String.
• paternal_surname: String.
• mothers_maiden_name: String.
• birthdate: String.
• entity_birth: String.
• probation_document: String.
• probation_document_data: Object with following fields.
  • anioReg: Integer.
  • crip: String.
  • cveEntidadEmisora: String.
  • cveMunicipioReg: Integer.
  • foja: String.
  • folioCarta: String.
  • libro: String.
  • numActa: Integer.
  • numEntidadReg: Integer.
  • numRegExtranjeros: String.
  • tomo: String.
• status_curp: String.
• rfcStatus: String.
• rfcValidationMessage: String.
• validRFC: Boolean.

RFC validation by CURP v2

POST /api/validate/rfc-by-curp/v2

Check for valid CURP, use obtained data to calculate RFC and then validate the RFC.

Parameter must be "curp".

If CURP is not found then renapo_valid field will be false.

if CURP has invalid format a 400 Bad Request exception will be thrown.

Request:

• curp: String, mandatory.

Response:

• curp: String.
• homonimo: Boolean.
• sex: String.
• nationality: String.
• rfc: String.
• renapo_valid: Boolena.
• names: String.
• paternal_surname: String.
• mothers_maiden_name: String.
• birthdate: String.
• entity_birth: String.
• probation_document: String.
• probation_document_data: Object with following fields.
  • anioReg: Integer.
  • crip: String.
  • cveEntidadEmisora: String.
  • cveMunicipioReg: Integer.
  • foja: String.
  • folioCarta: String.
  • libro: String.
  • numActa: Integer.
  • numEntidadReg: Integer.
  • numRegExtranjeros: String.
  • tomo: String.
• status_curp: String.
• rfcStatus: String.
• rfcValidationMessage: String.
• validRFC: Boolean.

RFC validation

POST /api/validate/rfc

Check for valid RFC. Parameter must be "rfc".

If RFC is not found then validRFC field will be false.

if RFC has invalid format a 400 Bad Request Exception will be thrown.

Request:

• rfc: String, mandatory.

Response:

• validRFC: Boolean.
• status: String.
• message: String.
• rfcType: String.
• messageCode: Integer.

Calculate RFC

POST /api/calculate/rfc

Calculate and return the RFC based on a person data.

The valid birthDate format is dd/mm/yyyy. Ex: february 5th 2020 -> 05/02/2020

Once you obtain the calculated RFC it doesn't necessarily mean it's a valid one. You could use the validate RFC method to check if it exists.

Request:

• name: String, mandatory.
• firstLastName: String, mandatory.
• secondLastName: String, mandatory.
• birthDate: String, mandatory.

Response:

• calculatedRFC: String.

Registraduria validation - Colombian id

POST /api/validate/registraduria

Check for valid Colombian ID and return corresponding values of that person.

Optionally, you can set isForeign flag to true to check for foreign people living in Colombia.

An example could be a Mexican person with a Colombian ID.

emissionDate format should be dd/mm/yyyy ex: 30/10/2020

A response example for foreigners is:

{ "data": { "ce": "456123", "estado": "VIGENTE", "fecha_expedicion": "02/10/2019", "fecha_nacimiento": "05/03/1956", "fecha_vencimiento": "01/10/2024", "nacionalidad": "CHILENA", "nombre_completo": "JUAN ALEJANDRO PEREZ LOPEZ" }, "error": "", "findings": [], "status": true }

Request:

• id: String, mandatory.
• isForeign: Boolean, (optional, by default false).
• emissionDate: String, (mandatory if isForeign is true, otherwise optional).

Response:

• data: Object with following fields.
  • anio_resolucion: Integer.
  • codigo_error_datos_cedula: Integer.
  • codigo_respuesta: Integer.
  • date: String.
  • departamento_expedicion: String.
  • descripcion_estado: String.
  • estado_cedula: Integer.
  • fecha_expedicion: String.
  • informacion_adicional: String.
  • municipio_expedicion: String.
  • nombre_completo: String.
  • nuip: Integer.
  • numero_resolucion: Integer.
  • particula: String.
  • primer_apellido: String.
  • primer_nombre: String.
  • segundo_apellido: String.
  • segundo_nombre: String.
• error: String.
• findings: String [].
• status: Boolean.

Colombia - Temporary Residency / PPT Validation

POST /api/validate/registraduria-ppt

Check for a valid Colombian temporary residency ID and return the corresponding values of that person.

Request Body:

• id: String, mandatory.
• fullName: String, optional.

Response:

• data: Object with following fields.
  • estado: String.
  • fecha_entrega: String.
  • identidad_venezolana: String.
  • lugar_entrega: String.
  • nombre_completo: String.
  • ppt: String.
  • tipo_documento: String.
• error: String.
• findings: String [].
• status: Boolean.

Vehicle Identification Number Validation

POST /api/validate/vin

Validate a VIN number and obtain data related to reports about crashes, theft, etc.

Request:

• vin: String, mandatory. Vehicle Identification Number
• getPdf: Boolean, optional. False by default, obtains pdf with details in base64 format.

Response:

• id: String.
• vin: String.
• attributes: Object with following fields.
  • vin: String.
  • year: String.
  • make: String.
  • model: String.
  • type: String.
  • made_In: String.
  • style: String.
  • engine: String.
• success: Boolean.
• error: String.
• base64PDF: String.

Validate bank statement

POST /api/validate/bank-statement

This endpoint is used to validate and get the information from a bank statement.

Request parameters:

• dummy: Boolean, optional. Enables sending any pdf and will return a dummy response. The default value is false, in case it is not sent.

Request:

• body: byte array, mandatory: pdf (bank-statement pdf)

Response: (fields are optional, based on the bank statement format)

• name: String.
• account_num: String.
• clabe: String.
• summary: String.
• bank: String.
• rfc: String.
• starting_balance: Float.
• ending_balance: Float.
• pdf_quality: Number.
• summary: Object. Object with detailed information on balance, deposits, withdrawals and fees.
• txs: Array of transactions.

Validate bank statement v2

POST /api/validate/bank-statement/v2

This endpoint is used to validate and get the information from a bank statement.

Request parameters:

• dummy: Boolean, optional. Enables sending any pdf and will return a dummy response. The default value is false, in case it is not sent.

Request:

• base64File: String, mandatory. Base64 string representation of the bank statement pdf.

Response: (fields are optional, based on the bank statement format)

• name: String.
• account_num: String.
• clabe: String.
• summary: String.
• bank: String.
• rfc: String.
• starting_balance: Float.
• ending_balance: Float.
• pdf_quality: Number.
• summary: Object. Object with detailed information on balance, deposits, withdrawals and fees.
• txs: Array of transactions.