File a promotion, transfer or re-grade
curl --request POST \
--url https://api.v3.andteam.com/v1/employees/{id}/job-changes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"effectiveDate": "2023-12-25"
}
'import requests
url = "https://api.v3.andteam.com/v1/employees/{id}/job-changes"
payload = { "effectiveDate": "2023-12-25" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({effectiveDate: '2023-12-25'})
};
fetch('https://api.v3.andteam.com/v1/employees/{id}/job-changes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.v3.andteam.com/v1/employees/{id}/job-changes"
payload := strings.NewReader("{\n \"effectiveDate\": \"2023-12-25\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
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))
}{
"wouldBe": {
"status": "awaiting_approval"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
],
"knockOns": {
"reportsMove": 4503599627370495
},
"pay": {
"wouldBe": {
"status": "awaiting_approval"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
]
}
}{
"id": "<string>",
"employeeId": "<string>",
"companyId": "<string>",
"type": "promotion",
"effectiveDate": "2023-12-25",
"status": "awaiting_approval",
"changes": {
"jobTitleId": "<string>",
"departmentId": "<string>",
"costCentreId": "<string>",
"gradeId": "<string>",
"locationId": "<string>",
"orgUnitIds": [
"<string>"
],
"managerId": "<string>"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
],
"requestedVia": {
"keyId": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"decidedAt": "2023-11-07T05:31:56Z",
"payChangeId": "<string>"
}{
"id": "<string>",
"employeeId": "<string>",
"companyId": "<string>",
"type": "promotion",
"effectiveDate": "2023-12-25",
"status": "awaiting_approval",
"changes": {
"jobTitleId": "<string>",
"departmentId": "<string>",
"costCentreId": "<string>",
"gradeId": "<string>",
"locationId": "<string>",
"orgUnitIds": [
"<string>"
],
"managerId": "<string>"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
],
"requestedVia": {
"keyId": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"decidedAt": "2023-11-07T05:31:56Z",
"payChangeId": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}Job history
File a promotion, transfer or re-grade
Needs the Job history field group’s Write switch. Filed through andteam’s own Change job as the key’s requester: the HRIS’s fields, the approval chain, the self-approval guard and the audit trail all apply. With the tenant’s job change approval chain the answer is 202 and nothing is written to the job until the last step approves; with none, 201. A pay block files the pay change with it in one transaction (it also needs Pay’s Write switch). A field the HRIS owns is 409 field-locked; a change already waiting is 409 pending-change-exists with existingId; a step nobody can decide is 409 approval-chain-unresolvable with step. andteam never sends a letter for an API change: HR is shown it as a letter to send.
POST
/
employees
/
{id}
/
job-changes
File a promotion, transfer or re-grade
curl --request POST \
--url https://api.v3.andteam.com/v1/employees/{id}/job-changes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"effectiveDate": "2023-12-25"
}
'import requests
url = "https://api.v3.andteam.com/v1/employees/{id}/job-changes"
payload = { "effectiveDate": "2023-12-25" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({effectiveDate: '2023-12-25'})
};
fetch('https://api.v3.andteam.com/v1/employees/{id}/job-changes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.v3.andteam.com/v1/employees/{id}/job-changes"
payload := strings.NewReader("{\n \"effectiveDate\": \"2023-12-25\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
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))
}{
"wouldBe": {
"status": "awaiting_approval"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
],
"knockOns": {
"reportsMove": 4503599627370495
},
"pay": {
"wouldBe": {
"status": "awaiting_approval"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
]
}
}{
"id": "<string>",
"employeeId": "<string>",
"companyId": "<string>",
"type": "promotion",
"effectiveDate": "2023-12-25",
"status": "awaiting_approval",
"changes": {
"jobTitleId": "<string>",
"departmentId": "<string>",
"costCentreId": "<string>",
"gradeId": "<string>",
"locationId": "<string>",
"orgUnitIds": [
"<string>"
],
"managerId": "<string>"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
],
"requestedVia": {
"keyId": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"decidedAt": "2023-11-07T05:31:56Z",
"payChangeId": "<string>"
}{
"id": "<string>",
"employeeId": "<string>",
"companyId": "<string>",
"type": "promotion",
"effectiveDate": "2023-12-25",
"status": "awaiting_approval",
"changes": {
"jobTitleId": "<string>",
"departmentId": "<string>",
"costCentreId": "<string>",
"gradeId": "<string>",
"locationId": "<string>",
"orgUnitIds": [
"<string>"
],
"managerId": "<string>"
},
"steps": [
{
"id": "<string>",
"label": "<string>",
"approvers": [
"<string>"
],
"status": "waiting"
}
],
"requestedVia": {
"keyId": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"decidedAt": "2023-11-07T05:31:56Z",
"payChangeId": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 0,
"detail": "<string>",
"instance": "<string>",
"errors": [
{
"pointer": "<string>",
"code": "<string>",
"detail": "<string>"
}
],
"fields": [
"<string>"
],
"existingId": "<string>",
"step": "<string>"
}Authorizations
apiKeyoauth
Authorization: Bearer atk_live_… (a sandbox's keys are atk_test_…). Created in the API keys section of the Integrations settings; the secret is shown once.
Headers
Unique per request; reuse it only to retry the same request with the same body. Remembered 24 hours.
Maximum string length:
255Optional: the employee's ETag, to refuse early when the record changed since you read it.
Path Parameters
The employee id.
Query Parameters
One of the key's companies.
true: answer 200 with what would happen (the approval steps and who they resolve to, the knock-ons), and write nothing.
Body
application/json
Promotion, transfer or re-grade. A correction or a change of terms is made in andteam (422, code not-supported).
Available options:
promotion, transfer, regrade The day the new job starts, after the current position began. Past or today: applied at once when the tenant has no approval chain; later: scheduled.
Pattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$A value id from /v1/lookups/job-titles.
Required string length:
1 - 128A value id from /v1/lookups/departments.
Required string length:
1 - 128A value id from /v1/lookups/cost-centres.
Required string length:
1 - 128A value id from /v1/lookups/grades.
Required string length:
1 - 128A location id from /v1/locations.
Required string length:
1 - 128Org unit ids from /v1/org-units, at most one per level.
Maximum array length:
10Required string length:
1 - 260Who they report to from that date: an employee id, or null for no one. Left out: their current manager.
Required string length:
1 - 128The pay change that comes with the job, filed with it in one transaction (a promotion's pay is a promotion, a transfer's or re-grade's an adjustment). Needs the Pay field group's Write switch.
Show child attributes
Show child attributes
Optional: the andteam user id or work email of the person this is requested by (the hiring manager in your ATS, say), instead of the key's requester. They are checked for the same permission over this employee; if the check fails the request is refused (requester-not-allowed), never put back on the key's requester.
Required string length:
1 - 320