> ## Documentation Index > Fetch the complete documentation index at: https://docs.hypersync.tartanhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Employee Details > Returns a single employee, or a paginated list of employees, for a connection. * Send `employee_id` to get a single employee. * Leave out `employee_id` to get a paginated list of employees. * If you leave out both `page` and `size`, pagination is turned off and all employees are returned. ## Request payload The request body is an encrypted payload, sent as `encrypted_payload`. Before encryption, the payload is this JSON: | Field | Type | Required | Description | | - | - | - | - | | `connection_id` | string (UUID) | Yes | Connection ID provided by Tartan | | `employee_id` | string | No | Send it to fetch a single employee; leave it out to fetch a list | | `page` | integer | No | Page number. Defaults to 1 | | `size` | integer | No | Page size. Defaults to 25 | | `download` | boolean | No | Return all employees without pagination. Defaults to true when neither `page` nor `size` is sent | ## Encryption To build `encrypted_payload`: 1. Build the payload JSON above. 2. Sign it as a JWT (JWS) using **RS256** with your private key (`alg: RS256`, `typ: JWT`). 3. Encrypt the signed JWT as a JWE using Tartan's public key (`alg: RSA-OAEP-256`, `enc: A256GCM`, `cty: JWT`). 4. Send the compact JWE string: `....`. Tartan decrypts the request with its private key and verifies the signature with your registered public key. If your organization has a public key registered with Tartan, the `data` in the response is encrypted the same way and must be decrypted with your private key. Otherwise `data` is returned as plain JSON. ## Status codes Some outcomes return HTTP `200` with the real result in the body's `status_code`: `404` when the employee is not found, and `428` when your public key is not configured. Always check `status` and `status_code` in the body. A request ID is returned in the `X-Request-ID` response header. This endpoint is rate limited to 4 requests per second per user. For field enums, refer the [employee directory](/api-reference/employees/get-employees-v2) page. ## OpenAPI ````yaml POST /api/external/employee/ openapi: 3.0.0 info: title: Employee List API description: Retrieve a paginated list of employees from the organization. version: 1.0.0 servers: - url: https://{env}.tartanhq.com description: Dynamic environment-based server variables: env: default: dev security: [] paths: /api/external/employee/: post: summary: Get Employee Details description: >- Returns a single employee, or a paginated list of employees, for a connection. requestBody: required: true content: application/json: schema: type: object required: - encrypted_payload properties: encrypted_payload: type: string description: Compact JWE string containing the signed, encrypted payload. example: responses: '200': description: > Request processed. Check `status_code` in the body: `200` means success, `404` means the employee was not found, `428` means your public key is not configured. content: application/json: schema: type: object properties: status: type: string enum: - success - failed example: success status_code: type: integer example: 200 message: type: string example: Data received and encrypted successfully data: description: > Encrypted JWE string if your organization has a public key registered, otherwise plain JSON. Once decrypted, it is a single employee object when `employee_id` was sent, or `{ "data": [employees], "pageInfo": {...} }` for a list. `null` when `status` is `failed`. oneOf: - $ref: '#/components/schemas/EmployeeEncrypted' - $ref: '#/components/schemas/Employee' - type: object properties: data: type: array items: $ref: '#/components/schemas/Employee' pageInfo: type: object nullable: true nullable: true '400': description: Validation failed, or the encrypted payload could not be decrypted content: application/json: schema: type: object properties: code: type: string message: type: string example: Invalid encrypted payload. data: nullable: true example: null details: type: object '401': description: Unauthorized – invalid or missing credentials content: application/json: schema: type: object properties: code: type: string message: type: string example: Invalid token. details: nullable: true example: null '403': description: >- The connection does not belong to your application, or your role is not allowed to call this API content: application/json: schema: type: object properties: message: type: string example: Invalid connection_id or unauthorized access. '429': description: Rate limit exceeded (4 requests per second per user) '500': description: Internal Server Error content: application/json: schema: type: object properties: status: type: string example: failed status_code: type: integer example: 500 message: type: string example: Error retrieving employee data. data: nullable: true example: null security: - basicAuth: [] - bearerAuth: [] components: schemas: EmployeeEncrypted: type: string example: >- eyJfdfasdfasdfasdfaIjoiQUl6YVN5QmJHc0t3bVZ6SUU5a2VnPT0iLCJkYXRhIjoiU2FtcGxlIEVuY3J5cHRlZCBTdHJpbmcifQ== Employee: type: object properties: id: type: string example: '7' employeeId: type: string example: '5' name: type: string example: Manas Mallik email: type: string format: email nullable: true example: manas@tartanhq.com personalEmail: type: string format: email nullable: true example: manas.mallik@gmail.com doj: type: string format: date example: '2021-06-01' dob: type: string format: date nullable: true example: '1983-06-08' status: type: string enum: - Active - Inactive - Terminated example: Active employmentType: type: string nullable: true example: Permanent gender: type: string example: Male pan: type: string description: Masked PAN nullable: true example: '************' aadhar: type: string description: Masked Aadhaar nullable: true example: '************' uan: type: string description: Masked UAN nullable: true example: '************' mobileNumber: type: string description: Masked mobile number nullable: true example: '************' maritalStatus: type: string nullable: true example: Married nationality: type: string nullable: true example: Indian fatherName: type: string nullable: true example: Ritesh Mallik bloodGroup: type: string nullable: true example: AB +ve designation: type: string example: NOT AVAILABLE department: type: string example: Engineering grade: type: string example: D-3 groupName: type: string example: NOT AVAILABLE costCenter: type: string example: NOT AVAILABLE companyName: type: string example: NOT AVAILABLE terminationDate: type: string nullable: true format: date example: '' manager: type: string example: Meet Semlani managerEmail: type: string format: email nullable: true example: NOT AVAILABLE managerEmail2: type: string format: email nullable: true example: NOT AVAILABLE managerEmail3: type: string format: email nullable: true example: NOT AVAILABLE managerEmail4: type: string format: email nullable: true example: NOT AVAILABLE managerEmail5: type: string format: email nullable: true example: NOT AVAILABLE countryCode: type: string example: IN bankDetails: type: object properties: accountNumber: type: string nullable: true example: '************' ifscCode: type: string nullable: true example: '************' bankName: type: string nullable: true example: SBI currentAddress: type: object properties: addressPincode: type: string nullable: true example: '560080' addressCity: type: string nullable: true example: Banglore addressCountry: type: string nullable: true example: India addressState: type: string nullable: true example: Karnataka addressLine: type: string example: Sadashiva Nagar Armane Nagar permanentAddress: type: object properties: addressPincode: type: string nullable: true example: '226001' addressCity: type: string nullable: true example: Luknow addressCountry: type: string nullable: true example: India addressState: type: string nullable: true example: Uttar Pradesh addressLine: type: string example: Yarana Nagar Luknow jobLocation: type: object properties: pincode: type: string example: NOT AVAILABLE city: type: string example: NOT AVAILABLE employeeMetadata: type: object properties: marriageDate: type: string nullable: true example: NOT AVAILABLE dependentDetails: type: array items: type: object properties: name: type: string example: Sohan Negi relation: type: string example: Father dob: type: string nullable: true example: NOT AVAILABLE email: type: string nullable: true example: NOT AVAILABLE gender: type: string nullable: true example: NOT AVAILABLE mobileNumber: type: string nullable: true example: NOT AVAILABLE profession: type: string nullable: true example: NOT AVAILABLE salaryDetails: type: object properties: ctc: type: object properties: basic: type: number example: 50000 dearnessAllowance: type: number example: 9000.9 hra: type: number example: 25000.5 gratuity: type: number example: 2000.7 medicalAllowance: type: number example: 2000.7 travelAllowance: type: number example: 2000.7 specialAllowance: type: number nullable: true example: null otherAllowance: type: number nullable: true example: null flexiBasketAllowance: type: number nullable: true example: null grossPay: type: number nullable: true example: null taxRegime: type: string nullable: true example: null fixedPay: type: number nullable: true example: null bonus: type: object properties: joining: type: number example: 80000 referral: type: number nullable: true example: null retention: type: number nullable: true example: null performance: type: number nullable: true example: null relocation: type: number nullable: true example: null misc: type: number nullable: true example: null deductions: type: object properties: pf: type: number example: 1800 esi: type: number nullable: true example: null professionalTax: type: number nullable: true example: null labourWelfareFund: type: number nullable: true example: null misc: type: number nullable: true example: null nps: type: number nullable: true example: null monthly: type: object properties: month: type: number example: 2 year: type: number example: 2025 basic: type: number nullable: true example: null dearnessAllowance: type: number nullable: true example: null hra: type: number nullable: true example: null medicalAllowance: type: number nullable: true example: null travelAllowance: type: number nullable: true example: null specialAllowance: type: number nullable: true example: null flexiBasketAllowance: type: number nullable: true example: null gratuity: type: number example: 1600 otherAllowance: type: number nullable: true example: null taxRegime: type: string nullable: true example: null fixedPay: type: number nullable: true example: null grossPay: type: number nullable: true example: null bonus: type: object properties: joining: type: number example: 20000 referral: type: number nullable: true example: null retention: type: number nullable: true example: null performance: type: number nullable: true example: null relocation: type: number example: 28907.17 misc: type: number nullable: true example: null deductions: type: object properties: pf: type: number nullable: true example: null esi: type: number nullable: true example: null professionalTax: type: number example: 300 labourWelfareFund: type: number nullable: true example: null tds: type: number nullable: true example: null medicalClaimDeduction: type: number nullable: true example: null groupTermInsuranceDeductions: type: number nullable: true example: null earlyWageDeduction: type: number nullable: true example: null misc: type: number example: 162023.24 nps: type: number example: 1234.34 reimbursements: type: number example: 93321.33 securitySchemes: basicAuth: type: http scheme: basic description: Create a Basic Auth token by base64-encoding username:password bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.