Employees
Get Employee Information
Retrieve key information about a single W-2 employee by employeeID.
GET
/
employees
Get Employee Information
curl --request GET \
--url https://api.zeal.com/employees \
--header 'Authorization: <api-key>'import requests
url = "https://api.zeal.com/employees"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://api.zeal.com/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zeal.com/employees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.zeal.com/employees"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.zeal.com/employees")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zeal.com/employees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"employeeID": "1234567890",
"companyID": "1b5n28nrideucd24",
"onboarded": true,
"employment_status": "live",
"term_date": null,
"first_name": "erlich",
"last_name": "bachman",
"email": "erlich@zeal.com",
"dob": "1999-12-04",
"start_date": "2019-06-04",
"title": "Brand Ambassador",
"working_state": "CA",
"workLocationID": "531fece70b6d0b5d29c9f352",
"address": "320 Pancake Hollow Road",
"address_line2": null,
"city": "Highland",
"state": "NY",
"zip": "12528",
"phone_number": "+18214370987",
"default_wage": 20,
"default_pay_schedule": "weekly",
"default_ot_wage": 30,
"default_dt_wage": 40,
"ssn": "123456789",
"is_943": false,
"is_salary": true,
"salary": 100000,
"is_scheduleH": false,
"paycard_requested": false,
"paycard_enabled": false,
"kyc_status": "approved",
"ssn_verification_status": null,
"soc_code": "41-3011"
}
}{
"success": false,
"errors": [
{
"message": "Employee ID is not formatted correctly",
"code": 13
}
]
}This request uses the
employeeID attribute to return key information about the employee, contained within the Employee Object. This is the same underlying route as Get Employees, which lists/filters instead of looking up a single employee - the API doesn’t distinguish these with separate routes, so each page documents the query parameters for its own intended usage.
This applies to W-2 employees. For 1099 contractors, use the Get Contractor Information request instead.
Returns
| attribute | type | description |
|---|---|---|
| success | boolean | Response status |
| data | object | Retrieves the Employee Object for the requested employee |
| errors | array | Contains a list of error objects which consists of: message (error message) and code (error code, see Error codes) |
Authorizations
Query Parameters
Company ID of employer
Employee ID
Filter by Employee onboarded status
Filter by Employee employment status
Filter by Employee title
Filter by Employee date of birth
Filter by Employee start date
Filter by Employee email
Filter by Employee phone number
Filter by Employee default pay schedule
Available options:
daily, weekly, biweekly, semimonthly, monthly, quarterly Filter by whether Employee is 943 status
Filter by whether Employee is scheduleH status
Filter by Employee external ID
Filter by Employee work location ID
⌘I
Get Employee Information
curl --request GET \
--url https://api.zeal.com/employees \
--header 'Authorization: <api-key>'import requests
url = "https://api.zeal.com/employees"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://api.zeal.com/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zeal.com/employees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.zeal.com/employees"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.zeal.com/employees")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zeal.com/employees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"employeeID": "1234567890",
"companyID": "1b5n28nrideucd24",
"onboarded": true,
"employment_status": "live",
"term_date": null,
"first_name": "erlich",
"last_name": "bachman",
"email": "erlich@zeal.com",
"dob": "1999-12-04",
"start_date": "2019-06-04",
"title": "Brand Ambassador",
"working_state": "CA",
"workLocationID": "531fece70b6d0b5d29c9f352",
"address": "320 Pancake Hollow Road",
"address_line2": null,
"city": "Highland",
"state": "NY",
"zip": "12528",
"phone_number": "+18214370987",
"default_wage": 20,
"default_pay_schedule": "weekly",
"default_ot_wage": 30,
"default_dt_wage": 40,
"ssn": "123456789",
"is_943": false,
"is_salary": true,
"salary": 100000,
"is_scheduleH": false,
"paycard_requested": false,
"paycard_enabled": false,
"kyc_status": "approved",
"ssn_verification_status": null,
"soc_code": "41-3011"
}
}{
"success": false,
"errors": [
{
"message": "Employee ID is not formatted correctly",
"code": 13
}
]
}