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

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

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