curl --request POST \
--url https://{env}.tartanhq.com/api/external/employee/ \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"encrypted_payload": "<JWE compact serialization string>"
}
'import requests
url = "https://{env}.tartanhq.com/api/external/employee/"
payload = { "encrypted_payload": "<JWE compact serialization string>" }
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({encrypted_payload: '<JWE compact serialization string>'})
};
fetch('https://{env}.tartanhq.com/api/external/employee/', 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/external/employee/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'encrypted_payload' => '<JWE compact serialization string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{env}.tartanhq.com/api/external/employee/"
payload := strings.NewReader("{\n \"encrypted_payload\": \"<JWE compact serialization string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{env}.tartanhq.com/api/external/employee/")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"encrypted_payload\": \"<JWE compact serialization string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{env}.tartanhq.com/api/external/employee/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"encrypted_payload\": \"<JWE compact serialization string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"status_code": 200,
"message": "Data received and encrypted successfully",
"data": "eyJfdfasdfasdfasdfaIjoiQUl6YVN5QmJHc0t3bVZ6SUU5a2VnPT0iLCJkYXRhIjoiU2FtcGxlIEVuY3J5cHRlZCBTdHJpbmcifQ=="
}{
"code": "<string>",
"message": "Invalid encrypted payload.",
"data": null,
"details": {}
}{
"code": "<string>",
"message": "Invalid token.",
"details": null
}{
"message": "Invalid connection_id or unauthorized access."
}{
"status": "failed",
"status_code": 500,
"message": "Error retrieving employee data.",
"data": null
}Get Employee Details
Returns a single employee, or a paginated list of employees, for a connection.
curl --request POST \
--url https://{env}.tartanhq.com/api/external/employee/ \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"encrypted_payload": "<JWE compact serialization string>"
}
'import requests
url = "https://{env}.tartanhq.com/api/external/employee/"
payload = { "encrypted_payload": "<JWE compact serialization string>" }
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({encrypted_payload: '<JWE compact serialization string>'})
};
fetch('https://{env}.tartanhq.com/api/external/employee/', 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/external/employee/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'encrypted_payload' => '<JWE compact serialization string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{env}.tartanhq.com/api/external/employee/"
payload := strings.NewReader("{\n \"encrypted_payload\": \"<JWE compact serialization string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{env}.tartanhq.com/api/external/employee/")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"encrypted_payload\": \"<JWE compact serialization string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{env}.tartanhq.com/api/external/employee/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"encrypted_payload\": \"<JWE compact serialization string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"status_code": 200,
"message": "Data received and encrypted successfully",
"data": "eyJfdfasdfasdfasdfaIjoiQUl6YVN5QmJHc0t3bVZ6SUU5a2VnPT0iLCJkYXRhIjoiU2FtcGxlIEVuY3J5cHRlZCBTdHJpbmcifQ=="
}{
"code": "<string>",
"message": "Invalid encrypted payload.",
"data": null,
"details": {}
}{
"code": "<string>",
"message": "Invalid token.",
"details": null
}{
"message": "Invalid connection_id or unauthorized access."
}{
"status": "failed",
"status_code": 500,
"message": "Error retrieving employee data.",
"data": null
}- Send
employee_idto get a single employee. - Leave out
employee_idto get a paginated list of employees. - If you leave out both
pageandsize, pagination is turned off and all employees are returned.
Request payload
The request body is an encrypted payload, sent asencrypted_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 buildencrypted_payload:
- Build the payload JSON above.
- Sign it as a JWT (JWS) using RS256 with your private key (
alg: RS256,typ: JWT). - Encrypt the signed JWT as a JWE using Tartan’s public key (
alg: RSA-OAEP-256,enc: A256GCM,cty: JWT). - Send the compact JWE string:
<protected-header>.<encrypted-key>.<iv>.<ciphertext>.<auth-tag>.
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
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.X-Request-ID response header. This endpoint is rate limited to 4 requests per second per user.
For field enums, refer the employee directory page.Authorizations
Create a Basic Auth token by base64-encoding username:password
Body
Compact JWE string containing the signed, encrypted payload.
"<JWE compact serialization string>"
Response
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.
success, failed "success"
200
"Data received and encrypted successfully"
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.
"eyJfdfasdfasdfasdfaIjoiQUl6YVN5QmJHc0t3bVZ6SUU5a2VnPT0iLCJkYXRhIjoiU2FtcGxlIEVuY3J5cHRlZCBTdHJpbmcifQ=="

