# HR Cloud Integration Documentation

This documentation for the HR Cloud integration describes the technical capabilities of this integration, including authorization, scopes/permissions, and utilized endpoints. For more information on how to integrate HR Cloud, visit our [connection instructions](https://docs.datagrail.io/docs/integrations/connection-instructions/hrcloud).

## Version 
This integration utilizes the MergeHR, Payroll, and Directory (HRIS) API **v1**.

## Base URL 
The base URL used for all HR Cloud API endpoints:

```
https://api.merge.dev/api/hris/v1
```

#### Endpoints Utilized 
DataGrail uses the following endpoints to authorize and test the connection:

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/employees` | Verify connection |  |

## Authentication & Authorization 
The DataGrail HR Cloud integration connects using **Merge API** authentication which requires an **API Key**.

**Sensitive Credentials**: Publicly exposing your API credentials can allow unauthorized access to HR Cloud API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

## Limits 
Limits in HR Cloud are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an `HTTP 429 Too Many Requests` error is returned. Requests succeed again after enough requests have emptied out of the bucket.
- DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
- DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

## Capabilities 
### Access 
DataGrail's **HR Cloud** integration provides **Asynchronous** Access capabilities for the following supported identifier category: **Email**.

#### Data Interactions 
For **Access** requests, DataGrail will take the following actions:
1. Search **employees** using configured identifiers.

#### Endpoints Utilized 
| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/employees` | Search employees |  |

### Deletion 
DataGrail's **HR Cloud** integration provides **Asynchronous** Deletion capabilities for the following supported identifier category: **Email**.

#### Data Interactions 
For **Deletion** requests, DataGrail will take the following actions:
1. Search **employees** using configured identifiers.
2. Update an **employee** to anonymize personal data.

#### Endpoints Utilized 
| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `https://corehr-api.hrcloud.com/v1/cloud/xEmployee` | Search employees |  |
| PUT | `https://corehr-api.hrcloud.com/v1/cloud/xEmployee` | Update an employee |  |

### Data Discovery 
DataGrail's **HR Cloud** integration provides data discovery capabilities based on the principle of finding any and all personal data that's stored in a data system.

#### Data Interactions 
For discovery requests, DataGrail will take the following actions:
1. Fetch available (enabled) objects from the following Merge! models:

**Supported Objects**  
- employees,  
- dependents,  
- bank_info,  
- employments,  
- employee_payroll_runs,  
- benefits,  
- time_off,  
- time_off_balances,  
- timesheet_entries,  
- locations,

2. Sample data for the next analysis and classification.

#### Endpoints Utilized 
| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/bank-info` | Fetch BankInfo objects |  |
| GET | `/benefits` | Fetch benefits |  |
| GET | `/dependents` | Fetch dependents |  |
| GET | `/employee-payroll-runs` | Fetch EmployeePayrollRun objects |  |
| GET | `/employees` | Fetch employees |  |
| GET | `/employments` | Fetch employments |  |
| GET | `/locations` | Fetch locations |  |
| GET | `/time-off` | Fetch TimeOff objects. |  |
| GET | `/time-off-balances` | Fetch TimeOffBalance objects. |  |
| GET | `/timesheet-entries` | Fetch TimesheetEntry objects. |  |

If you have any questions, please reach out to your dedicated Account Manager or contact us at [support@datagrail.io](mailto:support@datagrail.io).

**Disclaimer**: The information contained in this message does not constitute legal advice. We would advise seeking professional counsel before acting on or interpreting any material.