Employee data

Employee data is the employment information of a recipient, used only on payroll CFDIs (CFDI: Mexico's electronic invoice; payroll CFDI: the CFDI issued for each salary payment, type N). Each recipient has a single employee data record, so create the recipient first and then their employee data.

Employee data is a subresource of people (person: any individual or legal entity registered in your tenant), at the path /api/v4/people/<personId>/employee. The employee data of the tenant owner (tenant: the space in Fiscalapi that holds your issuers, recipients, credits, and data; owner: the person who created the tenant) can be created, updated, or deleted only by the owner. If another person tries, the endpoint returns 403.

Employee data model

Properties that start with sat take their values from the SAT catalogs (SAT: Mexico's tax authority, Servicio de Administración Tributaria). Look up their keys in CFDI 4.0 catalogs or through the SAT catalogs API.

Properties

Name
id
Type
string?
Description
The ID assigned by Fiscalapi.
Name
employerPersonId
Type
string
required
Description
The ID of the person who is the employer.
Name
employeePersonId
Type
string
required
Description
The ID of the person who is the employee.
Name
employeeNumber
Type
string
required
Description
The employee number the employer assigns.
Name
socialSecurityNumber
Type
string
required
Description
The employee's social security number.
Name
laborRelationStartDate
Type
date
required
Description
The start date of the employment relationship.
Name
satContractTypeId
Type
string
required
expandable
Description
The type of contract between the employee and the employer. SAT catalog c_TipoContrato.
Type
enum:
Values
"01""02""03"
Name
satTaxRegimeTypeId
Type
string
required
expandable
Description
The employee's hiring regime. SAT catalog c_TipoRegimen.
Type
enum:
Values
"02""03""04"
Name
satWorkdayTypeId
Type
string
required
expandable
Description
The employee's workday type. SAT catalog c_TipoJornada.
Type
enum:
Values
"01""02""03"
Name
satJobRiskId
Type
string
required
expandable
Description
The occupational risk class of the employee's position. SAT catalog c_RiesgoPuesto.
Type
enum:
Values
"1""2""3"
Name
satPaymentPeriodicityId
Type
string
required
expandable
Description
The employee's pay period. SAT catalog c_PeriodicidadPago.
Type
enum:
Values
"01""02""03"
Name
satPayrollStateId
Type
string
required
expandable
Description
The Mexican state where the employee works. SAT catalog c_Estado.
Type
enum:
Values
"AGU""BCN""BCS"
Name
seniority
Type
string
required
Description
The employee's seniority as an ISO 8601 duration, in weeks or in years, months, and days. For example, P437W for 437 weeks or P1Y5M0D for 1 year and 5 months.
Name
baseSalaryForContributions
Type
number
required
Description
The employee's base salary for social security contributions. It must be between 0 and 999,999,999,999.999999.
Name
integratedDailySalary
Type
number
required
Description
The employee's integrated daily salary. It must be between 0 and 999,999,999,999.999999.
Name
satBankId
Type
string?
expandable
Description
The bank where the employee receives their payroll payments. SAT catalog c_Banco.
Type
enum:
Values
002006009
Name
satUnionizedStatusId
Type
string?
expandable
Description
Whether the employee is a union member. SAT catalog c_Sindicalizado.
Type
enum:
Values
"Sí""No"
Name
position
Type
string?
Description
The employee's position.
Name
department
Type
string?
Description
The department where the employee works.
Name
bankAccount
Type
string?
Description
The bank account where the employee receives their payroll payments.
Name
subcontractorRfc
Type
string?
Description
The RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes) of the taxpayer that subcontracts the employee (where the employee directly provides their services), when the employee is subcontracted.
Name
timePercentage
Type
number?
Description
The percentage of working time, when the employee is subcontracted.

GET/api/v4/people/<personId>/employee

Get employee data

This endpoint returns a person's employee data by the person's ID.

Request

GET

/api/v4/people/<personId>/employee

curl --location 'https://test.fiscalapi.com/api/v4/people/<personId>/employee' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
        "employeeNumber": "123456789",
        "socialSecurityNumber": "0101010101",
        "laborRelationStartDate": "2020-01-12T00:00:00.000",
        "satContractType": {
            "id": "01",
            "description": "Contrato de trabajo por tiempo indeterminado",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satTaxRegimeType": {
            "id": "02",
            "description": "Sueldos (Incluye ingresos art. 94 LISR)",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satWorkdayType": null,
        "satJobRisk": {
            "id": "1",
            "description": "Clase I",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satPaymentPeriodicity": {
            "id": "04",
            "description": "Quincenal",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satBank": null,
        "satPayrollState": {
            "id": "JAL",
            "description": "Jalisco",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satUnionizedStatus": null,
        "department": null,
        "position": null,
        "seniority": "P1Y5M15D",
        "bankAccount": null,
        "baseSalaryForContributions": 520,
        "integratedDailySalary": 186,
        "subcontractorRfc": null,
        "timePercentage": 0
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/people/<personId>/employee

Create employee data

This endpoint creates a person's employee data. Each person has a single employee data record; if the person already has one, use Update employee data.

Request body

Name
employerPersonId
Type
string
required
Description
The ID of the person who is the employer.
Name
employeePersonId
Type
string
required
Description
The ID of the person who is the employee.
Name
employeeNumber
Type
string
required
Description
The employee number the employer assigns.
Name
socialSecurityNumber
Type
string
required
Description
The employee's social security number.
Name
laborRelationStartDate
Type
date
required
Description
The start date of the employment relationship.
Name
satContractTypeId
Type
string
required
expandable
Description
The type of contract between the employee and the employer. SAT catalog c_TipoContrato.
Type
enum:
Values
"01""02""03"
Name
satTaxRegimeTypeId
Type
string
required
expandable
Description
The employee's hiring regime. SAT catalog c_TipoRegimen.
Type
enum:
Values
"02""03""04"
Name
satWorkdayTypeId
Type
string
required
expandable
Description
The employee's workday type. SAT catalog c_TipoJornada.
Type
enum:
Values
"01""02""03"
Name
satJobRiskId
Type
string
required
expandable
Description
The occupational risk class of the employee's position. SAT catalog c_RiesgoPuesto.
Type
enum:
Values
"1""2""3"
Name
satPaymentPeriodicityId
Type
string
required
expandable
Description
The employee's pay period. SAT catalog c_PeriodicidadPago.
Type
enum:
Values
"01""02""03"
Name
satPayrollStateId
Type
string
required
expandable
Description
The Mexican state where the employee works. SAT catalog c_Estado.
Type
enum:
Values
"AGU""BCN""BCS"
Name
seniority
Type
string
required
Description
The employee's seniority as an ISO 8601 duration, in weeks or in years, months, and days. For example, P437W for 437 weeks or P1Y5M0D for 1 year and 5 months.
Name
baseSalaryForContributions
Type
number
required
Description
The employee's base salary for social security contributions. It must be between 0 and 999,999,999,999.999999.
Name
integratedDailySalary
Type
number
required
Description
The employee's integrated daily salary. It must be between 0 and 999,999,999,999.999999.
Name
satBankId
Type
string?
expandable
Description
The bank where the employee receives their payroll payments. SAT catalog c_Banco.
Type
enum:
Values
002006009
Name
satUnionizedStatusId
Type
string?
expandable
Description
Whether the employee is a union member. SAT catalog c_Sindicalizado.
Type
enum:
Values
"Sí""No"
Name
position
Type
string?
Description
The employee's position.
Name
department
Type
string?
Description
The department where the employee works.
Name
bankAccount
Type
string?
Description
The bank account where the employee receives their payroll payments.
Name
subcontractorRfc
Type
string?
Description
The RFC of the taxpayer that subcontracts the employee (where the employee directly provides their services), when the employee is subcontracted.
Name
timePercentage
Type
number?
Description
The percentage of working time, when the employee is subcontracted.

Errors

Every case arrives as a validation failure on the field shown.

Status	When it happens	Message
400	The person already has employee data. It fails on EmployeePersonId.	La persona ya tiene datos de empleado: modifícalos con PUT /api/v4/people/{personId}/employee.
400	baseSalaryForContributions is less than 0. It fails on BaseSalaryForContributions.	SalarioBaseCotApor debe ser mayor o igual a 0.
400	baseSalaryForContributions is greater than 999,999,999,999.999999. It fails on BaseSalaryForContributions.	SalarioBaseCotApor no puede ser mayor a 999999999999.999999.
400	integratedDailySalary is less than 0. It fails on IntegratedDailySalary.	SalarioDiarioIntegrado debe ser mayor o igual a 0.
400	integratedDailySalary is greater than 999,999,999,999.999999. It fails on IntegratedDailySalary.	SalarioDiarioIntegrado no puede ser mayor a 999999999999.999999.

Request

POST

/api/v4/people/<personId>/employee

curl --location 'https://test.fiscalapi.com/api/v4/people/54fc14ae-c88f-4afc-996b-0574d63341e2/employee' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
  "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
  "employeeNumber": "12345",
  "satContractTypeId": "01",
  "satTaxRegimeTypeId": "02",
  "satPaymentPeriodicityId": "04",
  "satPayrollStateId": "JAL",
  "socialSecurityNumber": "123456789012345",
  "laborRelationStartDate": "2023-01-15T00:00:00",
  "satWorkdayTypeId": "01",
  "satJobRiskId": "1",
  "satBankId": "002",
  "satUnionizedStatusId": "No",
  "department": "Recursos Humanos",
  "position": "Analista de Nóminas",
  "seniority": "P7Y3M7D",
  "bankAccount": "12345678901234567890",
  "baseSalaryForContributions": 490.22,
  "integratedDailySalary": 146.47,
  "subcontractorRfc": null,
  "timePercentage": null
}'

Response

{
    "data": {
        "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "employerRegistration": "B5510768108",
        "originEmployerTin": "URE180429TM6",
        "satFundSource": null,
        "ownResourceAmount": null,
        "id": "23f0b555-68bc-48fd-bb90-deb36ed25ef6",
        "createdAt": "2025-09-18T20:17:44.175",
        "updatedAt": "2025-09-18T20:17:44.175"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/people/<personId>/employee

Update employee data

This endpoint updates a person's employee data by the person's ID.

Request body

Name
employerPersonId
Type
string
required
Description
The ID of the person who is the employer.
Name
employeePersonId
Type
string
required
Description
The ID of the person who is the employee.
Name
employeeNumber
Type
string
required
Description
The employee number the employer assigns.
Name
socialSecurityNumber
Type
string
required
Description
The employee's social security number.
Name
laborRelationStartDate
Type
date
required
Description
The start date of the employment relationship.
Name
satContractTypeId
Type
string
required
expandable
Description
The type of contract between the employee and the employer. SAT catalog c_TipoContrato.
Type
enum:
Values
"01""02""03"
Name
satTaxRegimeTypeId
Type
string
required
expandable
Description
The employee's hiring regime. SAT catalog c_TipoRegimen.
Type
enum:
Values
"02""03""04"
Name
satWorkdayTypeId
Type
string
required
expandable
Description
The employee's workday type. SAT catalog c_TipoJornada.
Type
enum:
Values
"01""02""03"
Name
satJobRiskId
Type
string
required
expandable
Description
The occupational risk class of the employee's position. SAT catalog c_RiesgoPuesto.
Type
enum:
Values
"1""2""3"
Name
satPaymentPeriodicityId
Type
string
required
expandable
Description
The employee's pay period. SAT catalog c_PeriodicidadPago.
Type
enum:
Values
"01""02""03"
Name
satPayrollStateId
Type
string
required
expandable
Description
The Mexican state where the employee works. SAT catalog c_Estado.
Type
enum:
Values
"AGU""BCN""BCS"
Name
seniority
Type
string
required
Description
The employee's seniority as an ISO 8601 duration, in weeks or in years, months, and days. For example, P437W for 437 weeks or P1Y5M0D for 1 year and 5 months.
Name
baseSalaryForContributions
Type
number
required
Description
The employee's base salary for social security contributions. It must be between 0 and 999,999,999,999.999999.
Name
integratedDailySalary
Type
number
required
Description
The employee's integrated daily salary. It must be between 0 and 999,999,999,999.999999.
Name
satBankId
Type
string?
expandable
Description
The bank where the employee receives their payroll payments. SAT catalog c_Banco.
Type
enum:
Values
002006009
Name
satUnionizedStatusId
Type
string?
expandable
Description
Whether the employee is a union member. SAT catalog c_Sindicalizado.
Type
enum:
Values
"Sí""No"
Name
position
Type
string?
Description
The employee's position.
Name
department
Type
string?
Description
The department where the employee works.
Name
bankAccount
Type
string?
Description
The bank account where the employee receives their payroll payments.
Name
subcontractorRfc
Type
string?
Description
The RFC of the taxpayer that subcontracts the employee (where the employee directly provides their services), when the employee is subcontracted.
Name
timePercentage
Type
number?
Description
The percentage of working time, when the employee is subcontracted.

Errors

Every case arrives as a validation failure on the field shown.

Status	When it happens	Message
400	baseSalaryForContributions is less than 0. It fails on BaseSalaryForContributions.	SalarioBaseCotApor debe ser mayor o igual a 0.
400	baseSalaryForContributions is greater than 999,999,999,999.999999. It fails on BaseSalaryForContributions.	SalarioBaseCotApor no puede ser mayor a 999999999999.999999.
400	integratedDailySalary is less than 0. It fails on IntegratedDailySalary.	SalarioDiarioIntegrado debe ser mayor o igual a 0.
400	integratedDailySalary is greater than 999,999,999,999.999999. It fails on IntegratedDailySalary.	SalarioDiarioIntegrado no puede ser mayor a 999999999999.999999.

Request

PUT

/api/v4/people/<personId>/employee

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/people/54fc14ae-c88f-4afc-996b-0574d63341e2/employee' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
  "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
  "employeeNumber": "12345ABC",
  "satContractTypeId": "02",
  "satTaxRegimeTypeId": "02",
  "satPaymentPeriodicityId": "02",
  "satPayrollStateId": "AGU",
  "socialSecurityNumber": "123456789012345",
  "laborRelationStartDate": "2022-01-15T00:00:00",
  "satWorkdayTypeId": "01",
  "satJobRiskId": "2",
  "satBankId": "012",
  "satUnionizedStatusId": "Sí",
  "department": "Sistemas",
  "position": "Programador Jr.",
  "seniority": "P7Y3M7D",
  "bankAccount": "12345678901234567890",
  "baseSalaryForContributions": 290.22,
  "integratedDailySalary": 46.47,
  "subcontractorRfc": null,
  "timePercentage": null
}'

Response

{
    "data": {
        "employerPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "employeePersonId": "54fc14ae-c88f-4afc-996b-0574d63341e2",
        "employeeNumber": "12345ABC",
        "socialSecurityNumber": "123456789012345",
        "laborRelationStartDate": "2022-01-15T00:00:00.000",
        "satContractType": {
            "id": "02",
            "description": "Contrato de trabajo para obra determinada",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satTaxRegimeType": {
            "id": "02",
            "description": "Sueldos (Incluye ingresos señalados en la fraccion I del articulo 94 de LISR)",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satWorkdayType": {
            "id": "01",
            "description": "Diurna",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satJobRisk": {
            "id": "2",
            "description": "Clase II",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satPaymentPeriodicity": {
            "id": "02",
            "description": "Semanal",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satBank": {
            "id": "012",
            "description": "BBVA BANCOMER",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satPayrollState": {
            "id": "AGU",
            "description": "Aguascalientes",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satUnionizedStatus": {
            "id": "Sí",
            "description": "SI",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "department": "Sistemas",
        "position": "Programador Jr.",
        "bankAccount": "12345678901234567890",
        "baseSalaryForContributions": 290.22,
        "integratedDailySalary": 46.47,
        "subcontractorRfc": null,
        "timePercentage": 0
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/people/<personId>/employee

Delete employee data

This endpoint deletes a person's employee data by the person's ID.

Request

DELETE

/api/v4/people/<personId>/employee

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/people/bef56254-0892-4558-95c3-f9c8729e4b0e/employee' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>' \
--data ''

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}