1. Employee
Payflow API
Spain
  • Spain
  • Colombia
  • Peru
  • Guides
    • API Integration guide
  • Definitions
    • Employees
      • Employee Statuses
      • Salary Concepts
    • Payments
      • Payment Lifecycle
  • Explore our Public API
    • Auth & Health
      • Health
      • Test an API Key
    • Company
      • Retrieve your Company Details
    • Employee
      • Retrieve an Employee
        GET
      • Retrieve all Employees
        GET
      • Retrieve all Employees (V1.1)
        GET
      • Create an Employee
        POST
      • Upsert Employees in Bulk
        POST
      • Update an Employee by Personal ID
        PUT
      • Update an Employee by Payflow ID
        PUT
      • Update an Employee by Payroll ID
        PUT
    • Leaves
      • Retrieve all Employees on Leave
      • Create an Employee Leave
      • Remove an Employee Leave
    • Payments
      • Retrieve a Payment
      • Retrieve all Payments
      • Retrieve Employee Payments
      • Calculate Employee Available Amount
      • Request a Payment
      • Subscribe to Payment Updates
      • Mark Payments as Informed
    • Flexflow
      • Retrieve all Flexflow Transactions
      • Retrieve Employee Flexflow Transactions
  • Notifications Structure
    • Payment Updates
  • Schemas
    • Company
      • Company Response
    • Employee
      • ES | Create Employee Request
      • ES | Update Employee Request
      • ES | Employee Response
      • Create Employee Leave Request
    • Payment
      • Payment Response
      • Payment Response Convoluted
      • Payment Update
    • Flexflow
      • Employee Flexflow Transactions
    • Error
      • Generic Error Response
  1. Employee

Upsert Employees in Bulk

Production
https://api-public.payflow.es
Production
https://api-public.payflow.es
POST
https://api-public.payflow.es
/employees
Creates or updates company employees in bulk.
Each employee is matched by personalId. If an employee with the same personalId already exists in the company, that employee is updated. If the personalId does not exist, a new employee is created.
Because this is a bulk operation, invalid employee records do not cause the whole request to fail with a 4xx error. Instead, validation errors are returned per employee in the response body. An empty response array means all employees were processed successfully.
All rules from the Create an Employee endpoint apply to each employee in the payload.
Best Practices
This endpoint supports the api-version header. We recommend using api-version: 1.1 for improved stability and performance.
The maximum request size is 500 employees, but we recommend syncing employees in batches of 50 for optimal performance and to avoid saturation.

Required rules#

Each employee must belong to a subsidiary. Provide either subsidiary or subsidiaryCode.
At least one valid contact method (email or phone) must be provided.

Salary handling#

Employees require a salary to access the EWA and Flexible Compensation benefits.
You may provide either grossSalary or netSalary.
If netSalary is provided, it is used as the source of truth for internal calculations and grossSalary is ignored.
If only grossSalary is provided, netSalary is calculated automatically.
Learn more
See the Salary Concepts guide for more information.

Validation behavior#

Invalid email, phone or IBAN values are automatically set to null.
All employees in the request body should have unique personalId and email values. If duplicate values are sent in the same request, only the last repeated record is processed.

About optional fields
Omit optional fields that you do not want to set instead of sending placeholder values such as null, "", or 0, including for salary fields, as these may cause validation errors.

Request

Authorization
API Key
Add parameter in header
authorization
Example:
authorization: ********************
or
Header Params

Body Params application/json

Examples

Responses

🟢200
application/json
Bodyapplication/json

Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api-public.payflow.es/employees' \
--header 'api-version: 1.1' \
--header 'authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "payrollId": "Emp01",
        "firstName": "John",
        "lastName": "Doe",
        "documentType": "DNI",
        "personalId": "12345678X",
        "iban": "ES0000000000000000000000",
        "grossSalary": 1500,
        "restrictedAmount": 0,
        "startDate": "2025-06-01",
        "email": "john.doe@payflow.es",
        "address": "Employee address",
        "phone": "+34 600 00 00 00",
        "status": "active",
        "subsidiary": "1"
    },
    {
        "payrollId": "Emp02",
        "firstName": "Jane",
        "lastName": "Doe",
        "documentType": "DNI",
        "personalId": "12345678Y",
        "iban": "ES1000000000000000000000",
        "grossSalary": 1400,
        "restrictedAmount": 0,
        "startDate": "2025-06-01",
        "email": "jane.doe@payflow.es",
        "address": "Employee address",
        "phone": "+34 610 00 00 00",
        "status": "active",
        "subsidiary": "1"
    },
    {
        "payrollId": "Emp03",
        "firstName": "Jack",
        "lastName": "Doe",
        "documentType": "DNI",
        "personalId": "12345678Z",
        "iban": "ES2000000000000000000000",
        "grossSalary": 1250,
        "restrictedAmount": 0,
        "startDate": "2025-06-01",
        "email": "jack.doe@payflow.es",
        "address": "Employee address",
        "phone": "+34 620 00 00 00",
        "status": "active",
        "subsidiary": "1"
    }
]'
Response Response Example
{
    "created": [
        {
            "personalId": "12345678X",
            "id": 1
        }
    ],
    "updated": [
        {
            "personalId": "12345678Y",
            "id": 2
        }
    ],
    "error": [
        {
            "personalId": "12345678Z",
            "message": "Employee is on the blacklist"
        }
    ]
}
Modified at 2026-05-14 18:46:05
Previous
Create an Employee
Next
Update an Employee by Personal ID
Built with