What data and operations are available in the Day.io API?

The Day.io API allows external systems to integrate with the platform to query, create, and update information related to employees, punches, Requests, Schedules, and the company's organizational structure.

The main resources available include:

• Employees;
• Punches;
• Requests;
• Positions;
• Departments;
• Cost centers;
• Subsidiaries;
• Clients;
• Teams;
• Locations;
• Holiday Groups;
• Payment Groups;
• Pay Policies;
• Schedules.

Each operation is available through an endpoint. Before developing the integration, check the technical documentation for required fields, accepted formats, and updated examples.

Important: the API allows you to query punch records and Request data. However, it does not generate the ready-to-use files available under Reports, such as the Payroll Report, Summary, Clock Ins Report, or consolidated Request reports.

How to access the API credentials?

To use the API:

1. Access the Admin environment;
2. Open Integrations and Apps;
3. Select Learn about our API;
4. View the application credentials;
5. Copy the identifier and secret only when necessary.

Credentials should be restricted to the people responsible for developing and maintaining the integration.

How does authentication work?

The API uses a token to authenticate operations.

After generating the token, send it in protected requests using the header:

Authorization: Bearer TOKEN

The application secret should be treated as a password. Do not include it in public applications, shared spreadsheets, repositories, or error logs.

How to interpret the methods?

The same path may have different functions depending on the method used.

Employee endpoints

Employee endpoints allow you to create, update, search, deactivate, and reactivate profiles.

The search can use identifiers such as:

• UUID;
• Employee ID;
• CPF;
• Email;
• externalId;
• PIS;
• Phone number.

For bulk searches, use only one type of identifier in each request.

Depending on the fields accepted by the endpoint, the employee profile can also receive assignments related to the employee's structure, such as:

• Position;
• Department;
• Cost center;
• Supervisor;
• Payment Group;
• Pay Policy;
• Holiday Group;
• Subsidiary;
• Schedule;
• Locations.

First, query the endpoints for the required structures to obtain the correct identifiers.

Punch endpoints

The query can use filters such as:

• Start date;
• End date;
• Update date;
• Employee;
• Status;
• Classified punches only;
• Page;
• Number of results per page.

The statuses available in the documentation include:

• approved;
• pending;
• declined.

Use period filters and pagination to avoid very large queries.

Querying punches is not the same as generating a report

The /punches endpoint returns structured punch data. It does not generate a ready-to-use file with the calculations and presentation of reports such as:

• Payroll Report;
• Summary;
• Clock Ins Report;
• Hours Bank;
• Extra Hours;
• Late arrivals;
• Other files available under Reports.

The integrated system can use the returned data to build its own view, but that view does not automatically correspond to the official report generated by Day.io.

Request endpoints — Requests

The Requests endpoints allow you to create Requests, update their statuses, send attachments, and query requests.

Create Requests

Use:

POST /v2/public/integrations_api/requests

The operation receives a list of Requests in the requests field.

The information described in the documentation includes:

• externalId: custom Request identifier in the external system;
• employeeUuid: employee UUID;
• employeeExternalId: employee external identifier;
• employeeMatricula: employee ID;
• requestType: Request type;
• Information about the period and whether the request covers the entire day;
• Comment;
• Identification of the person creating the Request.

At least one of the following employee identifiers must be used:

• employeeUuid;
• employeeExternalId;
• employeeMatricula.

If more than one is sent, employeeUuid takes priority.

To identify the person creating the Request, use one of the following fields:

• createdByEmployeeUuid;
• createdByEmployeeExternalId.

If both are sent, createdByEmployeeUuid takes priority.

The requestType field must use an active Request type. The documentation provides examples such as:

• medical;
• vacation;
• custom.

Before creating the Request, confirm that the type is available to the company and that the dates correctly represent the requested period.

Update Request statuses

Use:

POST /v2/public/integrations_api/requests/status

The operation allows Requests to be updated to the following results:

• Approved;
• Ignored or canceled;
• Declined.

Requests can be identified by UUID:

• approvedUuids;
• ignoredUuids;
• declinedUuids.

They can also be identified by the external system ID:

• approvedExternalIds;
• ignoredExternalIds;
• declinedExternalIds.

You must also identify who is performing the update using one of the following fields:

• updatedByEmployeeUuid;
• updatedByEmployeeExternalId.

Within the same status object, use either UUIDs or external IDs. Do not send both formats at the same time, because the documentation indicates that this combination causes an error.

Send an attachment to a Request

Use:

POST /v2/public/integrations_api/requests/attachments

The upload is performed as multipart/form-data.

The fields described include:

To identify the Request, send:

• requestUuid; or
• requestExternalId.

If both are provided, requestUuid takes priority.

To identify who is sending the file, send:

• createdByEmployeeUuid; or
• createdByEmployeeExternalId.

If both are provided, createdByEmployeeUuid takes priority.

List an employee's Requests

Use:

GET /v2/public/integrations_api/requests/employees/:employeeUuid

The employeeUuid must be provided in the request path.

The query accepts filters such as:

The statuses shown in the documentation are:

• approved;
• ignored;
• declined.

The side parameter accepts:

• subject: employee the Request refers to;
• approver: employee responsible for approval.

List the company's Requests

Use:

GET /v2/public/integrations_api/requests

The query accepts filters such as:

Use pagination to browse all results when the company has many Requests.

The since filter can be used for incremental synchronizations, retrieving only requests updated after a given date.

Query the Request inbox

Use:

GET /v2/public/integrations_api/requests/employees/:employeeUuid/inbox

This operation queries the Request inbox of the employee specified in employeeUuid.

The query accepts:

The side parameter accepts:

• subject;
• approver.

This operation can be used to query Requests related to the employee or Requests waiting for their action as an approver.

Querying Requests is not the same as exporting a report

The Requests endpoints return structured data for use by the integration.

They do not automatically generate:

• Request PDFs;
• Consolidated Request spreadsheets;
• A report with the same presentation as the platform;
• A ready-to-use file from the Reports area.

Therefore, you can query and process Requests through the API, but you cannot ask the API to generate the same file provided through the interface.

Position endpoints

Positions can be identified by the Day.io UUID or the externalId used by the integrated system.

Department endpoints

For assignment operations, confirm the department, employees, and identifier type used.

Cost center endpoints

These endpoints can be used to synchronize the organizational structure with the source system.

Subsidiary endpoints

A subsidiary can have employees and Locations assigned to it.

Client endpoints

In this context, Clients represent companies served by the company registered in Day.io.

Check the accepted Location types before creating the assignment.

Team endpoints

When the integration creates Supervisors and their direct reports, create the Supervisor first so the assignment can be completed.

Location endpoints

Locations can use information such as:

• Name;
• Code;
• Type;
• Address;
• Latitude;
• Longitude;
• Radius.

Check the formats accepted by the operation before creating or updating a Location.

Holiday Group endpoints

For assignment operations, check the date on which the addition or removal should begin.

Company and group query endpoints

These queries can be used to obtain the identifiers required before creating or updating employees.

Schedule endpoints

For assignments, check:

• The company;
• The Schedule;
• The employees;
• The Start date;
• The identifiers used.

Example flow for synchronizing Requests

An integration can follow this sequence:

1. Generate the authentication token;
2. Locate the employee;
3. Confirm the Request type that will be used;
4. Create the Request with an externalId;
5. Store the identifier returned by the operation;
6. Send the attachment when necessary;
7. Query the employee's or company's Requests;
8. Update the status when the integration is responsible for that operation;
9. Use since in subsequent queries to retrieve only recent changes.

Tips and troubleshooting

• Authentication failed: generate a new token and check the credentials and Authorization header;
• The employee was not found: review the UUID, externalId, or employee ID used;
• The Request was created for the wrong person: check the priority between the identifiers sent;
• The status update returned an error: do not mix UUIDs and external IDs in the same status object;
• The attachment was not sent: check whether the request uses multipart/form-data and whether the Request and sender were identified;
• The query did not return all Requests: review page and per_page;
• I need to retrieve only recent changes: use the since parameter;
• I need to query one person's Requests: use the endpoint with employeeUuid;
• I need to query all company Requests: use GET /v2/public/integrations_api/requests;
• I need to query Requests awaiting an approver: use the inbox endpoint with side=approver;
• I need to download a Request spreadsheet: the API allows you to query the data, but does not generate the file;
• I need to download a Payroll Report: use the Reports area of the platform.

Best practices

• Use externalId to maintain the link between systems;
• Check whether the employee already exists before creating them;
• Do not use only name, phone number, or email as a permanent identifier;
• Store the externalId of each Request created through the integration;
• Do not mix UUIDs and external IDs in status updates;
• Use pagination for list queries;
• Use since for incremental synchronizations;
• Restrict punch and Request queries to the required periods;
• Do not record the application secret in logs;
• Protect attachments and returned personal data;
• Test the integration with a small number of records before performing bulk operations;
• Check the documentation before adding new fields or operations.

Frequently asked questions

1. Can I generate attendance reports through the API?

   No. The API does not generate files such as the Payroll Report, Summary, or Clock Ins Report.

2. Can I query punch records through the API?

   Yes. Use GET /punches. The response contains punch data, not a ready-to-use report.

3. Can I create Requests through the API?

   Yes. Use:

   POST /v2/public/integrations_api/requests

4. Can I query an employee's Requests?

   Yes. Use:

   GET /v2/public/integrations_api/requests/employees/:employeeUuid

5. Can I query all company Requests?

   Yes. Use:

   GET /v2/public/integrations_api/requests

6. Can I query an approver's Request inbox?

   Yes. Use the inbox endpoint and specify the employee:

   GET /v2/public/integrations_api/requests/employees/:employeeUuid/inbox

7. Can I approve, cancel, or decline Requests through the API?

   Yes. Use the status update endpoint:

   POST /v2/public/integrations_api/requests/status

8. Can I send attachments to a Request?

   Yes. Use:

   POST /v2/public/integrations_api/requests/attachments

9. Can I identify the employee by Employee ID?

   When creating a Request, the documentation allows you to use employeeUuid, employeeExternalId, or employeeMatricula.

10. What happens if I send more than one employee identifier?

    employeeUuid takes priority over the external identifier and Employee ID.

11. Can I use UUIDs and external IDs when updating the status?

    Use only one of the formats within the same status object. Sending both causes an error.

12. Can I download a Request report through the API?

    No. The API returns structured data, but does not generate a PDF or consolidated spreadsheet.

13. How can I query only recently updated Requests?

    Use the since parameter in the query endpoints.

14. Does the API return all results in a single request?

    Not always. Use page and per_page to browse the results.

15. What is externalId used for?

    It maintains the link between the record created in Day.io and the corresponding record in the external system.

16. Where can I find the complete fields for each operation?

    Check the technical API documentation for the current fields, examples, and rules.