Create or Update Employee

Creates a new employee, or updates an existing one (upsert).

Matching order for an existing employee in the given companyCode:

1. If externalReferenceId is provided, match by externalReferenceId + company.
2. Otherwise (or if no row has that externalReferenceId), match by email + company.

Email may be changed only when the employee was matched by externalReferenceId. When matched by email alone, other fields are updated but the stored email is left unchanged. A request with a new email and no matching externalReferenceId creates a new employee.

Authentication

This endpoint requires authentication. See Authentication for details.

Parameters

Parameter	Type	Required	Description
firstName	string	Yes	The first name of the employee
lastName	string	Yes	The last name of the employee
email	string	Yes	Employee's email address (unique per company). Stored and matched in lowercase. Updatable only when matching by externalReferenceId
phone	string	No	Phone number with country code
governmentDNI	string	Create only	Government-issued identification number. Required when creating a new employee; optional when updating an existing one
cpf	string	Create + BR	Brazilian tax identification number. Required when creating a new employee with countryCode BR; optional otherwise and on update
address	string	Yes	Primary address of the employee
addressExtraInfo	string	No	Additional address information
postCode	string	Yes	Postal/ZIP code
countryCode	string	Yes	Two-letter ISO country code
companyCode	string	Yes	Company code for the employee's company
city	string	Yes	Geocoding input only. On resolve, stored city is taken from Google (may differ from this value)
externalReferenceId	string	No	External system reference ID for the employee (unique per company when set). Preferred upsert identity when provided

Request

Production URL: https://orchestrator.tecspal.com/
Sandbox URL: https://orchestrator-dev.tecspal.com/
Endpoint: POST /employees

Example Request

{
  "request": "employees",
  "vendor": "tecspal",
  "verb": "POST",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john_doe@email.com",
    "phone": "+598 99999999",
    "governmentDNI": "DNI123456",
    "address": "Plaza Independencia 848, Montevidéu, Uruguai",
    "addressExtraInfo": "Praça Independência",
    "postCode": "11100",
    "countryCode": "UY",
    "companyCode": "DM1",
    "city": "Montevidéu",
    "externalReferenceId": "HR-EMP-00123"
  }
}

Example: update email via externalReferenceId

Same externalReferenceId and companyCode, new email — updates the existing employee (same id) and changes the email.

{
  "request": "employees",
  "vendor": "tecspal",
  "verb": "POST",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe.new@email.com",
    "phone": "+598 99999999",
    "governmentDNI": "DNI123456",
    "address": "Plaza Independencia 848, Montevidéu, Uruguai",
    "addressExtraInfo": "Praça Independência",
    "postCode": "11100",
    "countryCode": "UY",
    "companyCode": "DM1",
    "city": "Montevidéu",
    "externalReferenceId": "HR-EMP-00123"
  }
}

Response Schema

Property	Type	Description
statusCode	number	HTTP status code of the response (200)
message	string	Description of the response status
envelop	object	Object containing the employee data

Employee Properties

Property	Type	Description
id	string	Unique identifier of the employee
createdAt	string	Date/time when the employee was created (ISO 8601)
updatedAt	string	Date/time when the employee was last updated (ISO 8601)
firstName	string	First name of the employee
lastName	string	Last name of the employee
email	string	Email address of the employee
status	string	Current status (ACTIVE, DEACTIVATED)
phone	string	Phone number including country code
governmentDNI	string	Government-issued identification number
cpf	string | null	Brazilian ID (nullable)
address	string	Primary address of the employee
addressExtraInfo	string	Additional address information (nullable)
city	string | null	City of residence (from Google when the address was last resolved)
postCode	string	Postal or ZIP code
countryCode	string	Country code in ISO 3166-1 alpha-2 format
externalReferenceId	string | null	External system reference ID (nullable)

Example Response

{
  "statusCode": 200,
  "message": "Request successful",
  "envelop": {
    "id": "0a86b6c2-7373-42fa-a44a-70857cef0f90",
    "createdAt": "2025-04-10T14:58:05.119Z",
    "updatedAt": "2025-04-10T14:58:05.119Z",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john_doe@email.com",
    "status": "ACTIVE",
    "phone": "+598 99999999",
    "governmentDNI": "DNI123456",
    "cpf": null,
    "address": "Plaza Independencia 848, Montevidéu, Uruguai",
    "addressExtraInfo": "Praça Independência",
    "city": "Montevidéu",
    "postCode": "11100",
    "countryCode": "UY",
    "externalReferenceId": "HR-EMP-00123"
  }
}

Error Responses

Bad Request (400)

{
  "statusCode": 400,
  "message": "Invalid request data",
  "error": "Bad Request",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Creating a new employee without governmentDNI returns 400 with message governmentDNI is required when creating a new employee. Creating a new Brazilian employee (countryCode BR) without cpf returns 400 with message cpf is required when creating a new employee with countryCode BR. These checks do not apply when updating an existing employee.

Updating email via externalReferenceId to an address already used by another employee in the same company returns 400 with message email already belongs to another employee in this company. Assigning an externalReferenceId that already belongs to another employee in the same company returns 400 with message externalReferenceId already belongs to another employee in this company.

Unauthorized (401)

{
  "statusCode": 401,
  "message": "Unauthorized access",
  "error": "Unauthorized"
}

Notes

• Upsert identity: when externalReferenceId is provided, match by externalReferenceId + company first; otherwise match by email + company. Both are unique per company (not globally). Emails are trimmed and lowercased before match and storage.
• Email is updatable only when the existing row was matched by externalReferenceId. Matching by email alone updates other fields and sets status to ACTIVE, but does not change the stored email. Without a matching externalReferenceId, a different email creates a new employee.
• On update, governmentDNI and cpf may be omitted; existing values are kept. Optional externalReferenceId can be set or updated on create and upsert (subject to uniqueness per company).
• When creating a new employee, governmentDNI is required. cpf is required only when countryCode is BR.
• Address fields are re-validated/geocoded when address, city, postCode, or countryCode change (and always on create). The search string sent to Google is address, city, postCode, countryCode.
• On successful geocoding, the stored city is always taken from Google's address components. The request city is only used as input for the search string. If Google cannot resolve a city, the request fails with 400.
• Phone numbers should include the country code and + symbol when provided.
• New employees are created with ACTIVE status by default.