Mexico Income Verification V2.0

Income verification API is suitable for personal income information verification in Mexico. This is an asynchronous interface, returning work details to customers.


STEP 1:Asynchronous Query

API Method

Base URL

API

Request MethodsContent-TypeOutput FormatCharacter Set
POSTapplication/jsonJsonUTF-8

Authentication

ParameterTypeRequired/OptionalNotes
partner_codeStringRequiredTo be assigned by TD
partner_keyStringRequiredTo be assigned by TD

Request Parameter

ParameterTypeRequired/OptionalNotes
id_numberStringRequiredID card number, CURP, eighteen character alphanumeric code with capital letters. Please fill in the CURP for applying NSS
id_typeStringRequirednational_id
nss_numberStringStrongly RecommendedSocial Security Number

Request Example For Push Notifications

{
    "id_number":"GUPN8904****CRRN08",
    "id_type":"national_id",
     "nss_number":"9213****746"
}

Response Parameter

ParameterTypeDescriptionNotes
codeIntegerAPI status code
messageStringStatus informationThe specific cause of the exception is displayed when the API is in an abnormal state
sequence_idStringResponse unique codeA unique identifier used to track the record of each request

API Status Code

codeMessageDescription
200Success
300Service not purchased or not effectiveService not purchased or not effective
301Service not purchasedService not purchased
302Service has been suspendService has been suspend
303Not enough balanceNot enough balance
304Service expiredService expired
9500Internal errorInternal error
9060{parameter} empty{parameter} empty
9061{parameter} error{parameter} error

After post the data to TD through the above API interface, TD will return the income data to you through the bellowing API.


STEP 2:Webhook Configuration and Sample of Result

API Format

Base URL

The subscription API address you provide to TD. Please contact us for the configuration and we will help you with it.

Remark: The subscription API address supports http with port 80 and https with port 443.

API

URLHTTP MethodRequest Content TypeResponse Content TypeCharset
api-base-url?partner_code=xxx×tamp=xxx&access_key=xxx&sign=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
timestampStringCurrent timestampRequiredMillisecond level
access_keyStringAccess keyRequiredAssigned by TD
signStringSignRequired

Sign generation method

sign = HmacSHA1(partner_code+timestamp+access_key,access_secret)

access_secret is assigned by TD

Headers

Parameter nameValueRequired/Optional
Content-Typeapplication/jsonRequired

Response Parameters For Push Notifications

ParameterTypeDescriptionRequired/Optional
resultStringIf the result is successfully obtained, OK is returned. If other conditions occur, ERROR is returned. For details, please refer to "Message"
messageStringDescription of the result, only occur when the result is ErrorConditionally required
sequence_idStringUnique identifier used to track each request recordRequired
report_baseJSONObjectReport basic informationRequired
report_dtStringReport dateRequired
user_nameStringUser nameRequired
nssStringnss numberRequired
curpStringcurp numberRequired
total_weeksStringTotal week that the person paid to the IMSS.Required
valid_weeksStringWeek that the person paid to the IMSS. Usually equals to the week the person work a formal job.Required
decr_weeksStringWeeks used in advance, usually during periods of unemployment.Required
incr_weeksStringRestored weeks. It is usually used in advance before payment is made.Required
worksJSONArrayWork detailsRequired
employer_nameStringCompany nameRequired
employer_registrationStringCompany IMSS codeRequired
federal_entityStringCompany stateRequired
date_registrationStringDate the person started in that job.Required
date_de_registrationStringDate the person stop working in that job. If it says “Vigente” it means is the current job.Required
base_salary_contributionStringThe latest base salaryRequired
detailJSONArrayWorking detailsRequired
type_movementStringMovement typeRequired
date_movementStringMovement dateRequired
salary_baseStringBase salary after each movementRequired
Enumeration values of message
message含义
Por el momento no es posible entregarle su constancia por favor intente más tarde o solicítela directamente en la Subdelegación más cercana a su domicilio en días y horas hábiles.More than 3 executions of the service with the same CURP
Para poder generar su Reporte de Semanas Cotizadas, es necesario acuda a la subdelegación más cercana a su domicilio a recibir orientación.In order to generate your Report, it is necessary to go to the subdelegation closest to your home to receive guidance.
Los datos de entrada no coinciden con los datos de la entidad externa RENAPO.The data does not match the data of the external entity RENAPO.
Es necesario que acudas a la Subdelegación más cercana a tu domicilio a presentar tu trámite.You need to assist to an IMSS branch physically
La CURP proporcionada no fue localizada en la entidad externa RENAPOCURP not found
Service unavailable, please retry laterService unavailable, please retry later
The CURP is incorrectcurp error
The NSS does not existnss not exist
Work in progressWork in progress
Enumeration values and meanings of type_movement
Enumeration valuesEnglish definitionDescription
AltaRegistrationNotice given when work begins, whether temporary, temporary or permanent.
BajaDismissalThis is the notification that a company submits to the Social Security Administration when the employment relationship with an employee ends, which also ends its obligation to maintain registration in the social security system.
ReingresoReentryA motion to rejoin is a notice that a company must file with IMSS when a laid off worker rejoins the company.
Modificación de salarioSalary modificationWage adjustment changes are notifications issued by the company when there is a change in the basic contribution wages of employees registered in the social security system.
Cambios de jornada laboralWorking day changesModifications on an employee's working hours, such as increasing or decreasing the number of hours in the working day.
Cambios en la razón social o estructura de la empresaChange of company name or corporate structureCompany name or structure changed.

Response example

{
    "sequence_id": "1699272744735016I303341798930550",
    "result": "OK",
    "report_base": {
        "report_dt": "13/03/2024",
        "user_name": "HERNANDEZ BUSTAMANTE GUILLERMO",
        "nss": "33634110879",
        "curp": "HEBG410210HCHRSL08",
        "total_weeks": "1091",
        "valid_weeks": "1091",
        "decr_weeks": "0",
        "incr_weeks": "0"
    },
    "works": [
        {
            "employer_name": "DISTRIBUCIONES INSTITUCIONALES",
            "employer_registration": "A803058510",
            "federal_entity": "CHIHUAHUA",
            "date_registration": "04/05/1992",
            "date_de_registration": "05/02/2007",
            "base_salary_contribution": "$111.88",
            "detail": [
                {
                    "type_movement": "BAJA",
                    "date_movement": "05/02/2007",
                    "salary_base": "$111.88"
                }
            ]
        },
        {
            "employer_name": "AERONAVES DE MEX SA",
            "employer_registration": "3301028610",
            "federal_entity": "CHIHUAHUA",
            "date_registration": "28/12/1984",
            "date_de_registration": "23/06/1988",
            "base_salary_contribution": "$28.37",
            "detail": [
                {
                    "type_movement": "BAJA",
                    "date_movement": "23/06/1988",
                    "salary_base": "$28.37"
                }
            ]
        }
    ]
}

Response Parameters

Parameters that your business system needs to respond to after receiving a push request

ParameterTypeDescriptionRequired/OptionalNotes
codeIntegerAPI status codeRequired
messageStringStatus messageRequiredIn the API exception state, the specific exception reason will be output.

API Status Code

code**Description**
200Success

Response Example

{
  "code": 200,
  "message": ""
}

Note: If the status code you return is not 200, we will retry 3 times. If we failed for all 3 times, we will not push the data any more. However, you can query through the following query interface if the push is missed.




Synchronous API: Can be used only when webhook failed

If you have not received the returned data push for a long time, you can pass the sequence_id returned by the first call through the following query interface to query the results. This interface only supports result query within 48 hours).

Remark: This interface is back up interface for asynchronous queries. After configuring the asynchronous interface, if the call is successful but there is no return, you can query through this interface


API Method

Base URL

API

Request MethodsContent-TypeOutput FormatCharacter Set
POSTapplication/jsonJsonUTF-8

Authentication

ParameterTypeRequired/OptionalNotes
partner_codeStringRequiredTo be assigned by TD
partner_keyStringRequiredTo be assigned by TD

Request Parameter

ParameterTypeRequired/OptionalNotes
sequence_idStringRequiredsequence_id from the first step

Response Parameters

The response will be the same with the above push request parameters. Please refer to Response Parameters For Push Notifications within this document.

API Status Code

codeMessageDescription
200Success
9060{parameter} empty{parameter} empty
9080Only queries within 48 hours are available.Only queries within 48 hours are available

Response Example(Success)

{
    "code": 200,
    "sequence_id": "1699272744735016I303341798930550",
    "result": "OK",
    "report_base": {
        "report_dt": "13/03/2024",
        "user_name": "HERNANDEZ BUSTAMANTE GUILLERMO",
        "nss": "33634110879",
        "curp": "HEBG410210HCHRSL08",
        "total_weeks": "1091",
        "valid_weeks": "1091",
        "decr_weeks": "0",
        "incr_weeks": "0"
    },
    "works": [
        {
            "employer_name": "DISTRIBUCIONES INSTITUCIONALES",
            "employer_registration": "A803058510",
            "federal_entity": "CHIHUAHUA",
            "date_registration": "04/05/1992",
            "date_de_registration": "05/02/2007",
            "base_salary_contribution": "$111.88",
            "detail": [
                {
                    "type_movement": "BAJA",
                    "date_movement": "05/02/2007",
                    "salary_base": "$111.88"
                }
            ]
        },
        {
            "employer_name": "AERONAVES DE MEX SA",
            "employer_registration": "3301028610",
            "federal_entity": "CHIHUAHUA",
            "date_registration": "28/12/1984",
            "date_de_registration": "23/06/1988",
            "base_salary_contribution": "$28.37",
            "detail": [
                {
                    "type_movement": "BAJA",
                    "date_movement": "23/06/1988",
                    "salary_base": "$28.37"
                }
            ]
        }
    ]
}

Response Example(ERROR)

{
    "code": 9080,
    "message": "Only queries within 48 hours are available.",
    "sequence_id": "1703123181798646G109E3248****377"
}