Get Employee Information

GET

employees

curl --request GET \
  --url https://api.zeal.com/employees \
  --header 'Authorization: <api-key>'

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))

}

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

Authorization

string

header

required

Query Parameters

companyID

string

required

Company ID of employer

employeeID

string

Employee ID

onboarded

boolean

Filter by Employee onboarded status

employment_status

string

Filter by Employee employment status

title

string

Filter by Employee title

dob

string

Filter by Employee date of birth

start_date

string

Filter by Employee start date

string

Filter by Employee email

phone_number

string

Filter by Employee phone number

default_pay_schedule

enum<string>

Filter by Employee default pay schedule

Available options:

daily,

weekly,

biweekly,

semimonthly,

monthly,

quarterly

is_943

boolean

Filter by whether Employee is 943 status

is_scheduleH

boolean

Filter by whether Employee is scheduleH status

external_id

string

Filter by Employee external ID

workLocationID

string

Filter by Employee work location ID

Response

200

success

boolean

default:true

Example:

true

data

object

Show child attributes

Get Employee Information

curl --request GET \
  --url https://api.zeal.com/employees \
  --header 'Authorization: <api-key>'

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))

}

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
    }
  ]
}

Introduction

Webhooks

Zeal Components

Companies

Company Onboarding

Reserve Accounts

Customer Accounts (Early Access)

Taxable Locations

Work Locations

Employees

Employee Deduction Templates

Employee Onboarding

Bank Accounts

Custom Attributes

Paperwork API

Employee Checks

Contractors

Contractor Onboarding

Contractor Payment Deductions

Payment Items

Contractor Payments

Paycards

Instant Pay

Employer Checks

Preview

Embedded HR

Reports

Documents

Get Employee Information

Returns

Authorizations

Query Parameters

Response

​Returns

Authorizations

Query Parameters

Response

Returns