Get Employee Directory

Returns a list of employees for the given organization, with support for pagination, filtering, and update tracking.

GET /api/v2/employee_list

Get Employee List (v2)

cURL

curl --request GET \
  --url https://{env}.tartanhq.com/api/v2/employee_list \
  --header 'Authorization: <api-key>'

import requests

url = "https://{env}.tartanhq.com/api/v2/employee_list"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://{env}.tartanhq.com/api/v2/employee_list', 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://{env}.tartanhq.com/api/v2/employee_list",
  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://{env}.tartanhq.com/api/v2/employee_list"

	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://{env}.tartanhq.com/api/v2/employee_list")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{env}.tartanhq.com/api/v2/employee_list")

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

200

{
  "requestId": "0712451b-6672-4293-a7a6-6b75f5b15590",
  "corporateReferenceId": "f8302566-7464-492a-a485-e8998f97a07f",
  "message": "success",
  "pageInfo": {
    "totalPages": 4,
    "totalItems": 97,
    "items": 25,
    "next": true,
    "previous": false
  },
  "data": [
    {
      "id": "7",
      "employeeId": "5",
      "name": "Manas Mallik",
      "email": "[e-mail]",
      "personalEmail": "[e-mail]",
      "doj": "2021-06-01",
      "dob": "1983-06-08",
      "status": "Active",
      "employmentType": "Permanent",
      "gender": "Male",
      "pan": "************",
      "aadhar": "************",
      "uan": "************",
      "mobileNumber": "************",
      "maritalStatus": "Married",
      "nationality": "Indian",
      "fatherName": "Ritesh Mallik",
      "bloodGroup": "AB +ve",
      "designation": "NOT AVAILABLE",
      "department": "Engineering",
      "grade": "D-3",
      "groupName": "NOT AVAILABLE",
      "costCenter": "NOT AVAILABLE",
      "companyName": "NOT AVAILABLE",
      "terminationDate": "",
      "manager": "Meet Semlani",
      "managerEmail": "NOT AVAILABLE",
      "managerEmail2": "NOT AVAILABLE",
      "managerEmail3": "NOT AVAILABLE",
      "managerEmail4": "NOT AVAILABLE",
      "managerEmail5": "NOT AVAILABLE",
      "countryCode": "IN",
      "bankDetails": {
        "accountNumber": "************",
        "ifscCode": "************",
        "bankName": "SBI"
      },
      "currentAddress": {
        "addressPincode": "560080",
        "addressCity": "Banglore",
        "addressCountry": "India",
        "addressState": "Karnataka",
        "addressLine": "Sadashiva Nagar Armane Nagar"
      },
      "permanentAddress": {
        "addressPincode": "226001",
        "addressCity": "Luknow",
        "addressCountry": "India",
        "addressState": "Uttar Pradesh",
        "addressLine": "Yarana Nagar Luknow"
      },
      "jobLocation": {
        "pincode": "NOT AVAILABLE",
        "city": "NOT AVAILABLE"
      },
      "employeeMetadata": {
        "marriageDate": "NOT AVAILABLE"
      },
      "dependentDetails": [
        {
          "name": "Sohan Negi",
          "relation": "Father",
          "dob": "NOT AVAILABLE",
          "email": "NOT AVAILABLE",
          "gender": "NOT AVAILABLE",
          "mobileNumber": "NOT AVAILABLE",
          "profession": "NOT AVAILABLE"
        }
      ],
      "salaryDetails": {
        "ctc": {
          "basic": 50000,
          "dearnessAllowance": 9000.9,
          "hra": 25000.5,
          "gratuity": 2000.7,
          "medicalAllowance": 2000.7,
          "travelAllowance": 2000.7,
          "specialAllowance": null,
          "otherAllowance": null,
          "flexiBasketAllowance": null,
          "grossPay": null,
          "taxRegime": null,
          "fixedPay": null,
          "bonus": {
            "joining": 80000,
            "referral": null,
            "retention": null,
            "performance": null,
            "relocation": null,
            "misc": null
          },
          "deductions": {
            "pf": 1800,
            "esi": null,
            "professionalTax": null,
            "labourWelfareFund": null,
            "misc": null,
            "nps": null
          }
        },
        "monthly": {
          "month": 2,
          "year": 2025,
          "basic": null,
          "dearnessAllowance": null,
          "hra": null,
          "medicalAllowance": null,
          "travelAllowance": null,
          "specialAllowance": null,
          "flexiBasketAllowance": null,
          "gratuity": 1600,
          "otherAllowance": null,
          "taxRegime": null,
          "fixedPay": null,
          "grossPay": null,
          "bonus": {
            "joining": 20000,
            "referral": null,
            "retention": null,
            "performance": null,
            "relocation": 28907.17,
            "misc": null
          },
          "deductions": {
            "pf": null,
            "esi": null,
            "professionalTax": 300,
            "labourWelfareFund": null,
            "tds": null,
            "medicalClaimDeduction": null,
            "groupTermInsuranceDeductions": null,
            "earlyWageDeduction": null,
            "misc": 162023.24,
            "nps": 1234.34
          },
          "reimbursements": 93321.33
        }
      }
    }
  ]
}

{
  "requestId": "d28dfd7b-d9f3-40b6-86c8-eb1684bcdf0e",
  "message": "error",
  "data": {
    "page": [
      "This field is required."
    ],
    "size": [
      "This field is required."
    ],
    "org": [
      "This field is required."
    ]
  }
}

{
  "requestId": "5eb3b3f9-6d8c-49c2-9b12-1027b8a6af58",
  "message": "Invalid token.",
  "data": null
}

{
  "message": "Source Permission denied",
  "data": {}
}

{
  "requestId": "be2915d5-fc30-4d13-bcca-3d62aefac2a0",
  "message": "Internal Server Error",
  "data": null
}

Enum Mapping

If an unexpected value is received for any enum-based key, and it doesn’t match any value in the enum mapping, the value will be set to null.

Field name	Tartan Enum value / Format
dob	%Y-%m-%d
doj	%Y-%m-%d
terminationDate	%Y-%m-%d
dependentDetails.dob	%Y-%m-%d
status	["Active", "Not Active"]
employmentType	["Permanent", "Contract", "Probation/Intern"]
gender	["Male", "Female", "Other"]
maritalStatus	["Single", "Married", "Divorced", "Widowed"]
dependentDetails.gender	["Male", "Female", "Other"]

Authorizations

Authorization · string · header · required

Query Parameters

org · string · required

The organization identifier.

page · integer

The page number to fetch.

size · integer

Number of employees to return per page.

from_date · string<date-time>

Return employees updated after this date.

source · string

Data source (e.g., db, hrms).

filter · string

Filter in the format field:value, e.g., status:active.

Response

200

application/json

Successful response

requestId · string

Example:

"0712451b-6672-4293-a7a6-6b75f5b15590"

corporateReferenceId · string

Example:

"f8302566-7464-492a-a485-e8998f97a07f"

message · string

Example:

"success"

pageInfo · object

Show child attributes

data · object[]

Show child attributes