Change an employee's personal and contact details

curl --request PATCH \
  --url https://api.v3.andteam.com/v1/employees/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'If-Match: <if-match>' \
  --data '
{
  "preferredName": "<string>",
  "personalEmail": "jsmith@example.com",
  "mobile": "<string>",
  "homeAddress": {
    "line1": "<string>",
    "unitNumber": "<string>",
    "complexName": "<string>",
    "suburb": "<string>",
    "city": "<string>",
    "province": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "requestedBy": "<string>"
}
'

import requests

url = "https://api.v3.andteam.com/v1/employees/{id}"

payload = {
    "preferredName": "<string>",
    "personalEmail": "jsmith@example.com",
    "mobile": "<string>",
    "homeAddress": {
        "line1": "<string>",
        "unitNumber": "<string>",
        "complexName": "<string>",
        "suburb": "<string>",
        "city": "<string>",
        "province": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
    },
    "dateOfBirth": "2023-12-25",
    "nationality": "<string>",
    "requestedBy": "<string>"
}
headers = {
    "If-Match": "<if-match>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'If-Match': '<if-match>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({
    preferredName: '<string>',
    personalEmail: 'jsmith@example.com',
    mobile: '<string>',
    homeAddress: {
      line1: '<string>',
      unitNumber: '<string>',
      complexName: '<string>',
      suburb: '<string>',
      city: '<string>',
      province: '<string>',
      postalCode: '<string>',
      country: '<string>'
    },
    dateOfBirth: '2023-12-25',
    nationality: '<string>',
    requestedBy: '<string>'
  })
};

fetch('https://api.v3.andteam.com/v1/employees/{id}', 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}"

	payload := strings.NewReader("{\n  \"preferredName\": \"<string>\",\n  \"personalEmail\": \"jsmith@example.com\",\n  \"mobile\": \"<string>\",\n  \"homeAddress\": {\n    \"line1\": \"<string>\",\n    \"unitNumber\": \"<string>\",\n    \"complexName\": \"<string>\",\n    \"suburb\": \"<string>\",\n    \"city\": \"<string>\",\n    \"province\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"requestedBy\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("If-Match", "<if-match>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/merge-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "employeeNumber": "<string>",
  "firstName": "<string>",
  "preferredName": "<string>",
  "lastName": "<string>",
  "workEmail": "<string>",
  "workPhone": "<string>",
  "jobTitle": "<string>",
  "department": "<string>",
  "orgUnits": [
    {
      "level": "<string>",
      "name": "<string>"
    }
  ],
  "location": "<string>",
  "companyId": "<string>",
  "managerId": "<string>",
  "employmentType": "<string>",
  "status": "upcoming",
  "startDate": "<string>",
  "lastDay": "<string>",
  "updatedAt": "2023-11-07T05:31:56Z",
  "positionNumber": "<string>",
  "positionTitle": "<string>",
  "reportsToPositionId": "<string>",
  "personalEmail": "<string>",
  "mobile": "<string>",
  "homeAddress": {
    "line1": "<string>",
    "unitNumber": "<string>",
    "complexName": "<string>",
    "suburb": "<string>",
    "city": "<string>",
    "province": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "dateOfBirth": "<string>",
  "nationality": "<string>",
  "gender": "<string>",
  "race": "<string>",
  "eeDesignation": "<string>",
  "disability": true,
  "medicalAidMember": true
}

{
  "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>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 0,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "code": "<string>",
      "detail": "<string>"
    }
  ],
  "fields": [
    "<string>"
  ],
  "existingId": "<string>",
  "step": "<string>"
}

PATCH

employees

{id}

Change an employee's personal and contact details

curl --request PATCH \
  --url https://api.v3.andteam.com/v1/employees/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'If-Match: <if-match>' \
  --data '
{
  "preferredName": "<string>",
  "personalEmail": "jsmith@example.com",
  "mobile": "<string>",
  "homeAddress": {
    "line1": "<string>",
    "unitNumber": "<string>",
    "complexName": "<string>",
    "suburb": "<string>",
    "city": "<string>",
    "province": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "dateOfBirth": "2023-12-25",
  "nationality": "<string>",
  "requestedBy": "<string>"
}
'

import requests

url = "https://api.v3.andteam.com/v1/employees/{id}"

payload = {
    "preferredName": "<string>",
    "personalEmail": "jsmith@example.com",
    "mobile": "<string>",
    "homeAddress": {
        "line1": "<string>",
        "unitNumber": "<string>",
        "complexName": "<string>",
        "suburb": "<string>",
        "city": "<string>",
        "province": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
    },
    "dateOfBirth": "2023-12-25",
    "nationality": "<string>",
    "requestedBy": "<string>"
}
headers = {
    "If-Match": "<if-match>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'If-Match': '<if-match>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({
    preferredName: '<string>',
    personalEmail: 'jsmith@example.com',
    mobile: '<string>',
    homeAddress: {
      line1: '<string>',
      unitNumber: '<string>',
      complexName: '<string>',
      suburb: '<string>',
      city: '<string>',
      province: '<string>',
      postalCode: '<string>',
      country: '<string>'
    },
    dateOfBirth: '2023-12-25',
    nationality: '<string>',
    requestedBy: '<string>'
  })
};

fetch('https://api.v3.andteam.com/v1/employees/{id}', 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}"

	payload := strings.NewReader("{\n  \"preferredName\": \"<string>\",\n  \"personalEmail\": \"jsmith@example.com\",\n  \"mobile\": \"<string>\",\n  \"homeAddress\": {\n    \"line1\": \"<string>\",\n    \"unitNumber\": \"<string>\",\n    \"complexName\": \"<string>\",\n    \"suburb\": \"<string>\",\n    \"city\": \"<string>\",\n    \"province\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"dateOfBirth\": \"2023-12-25\",\n  \"nationality\": \"<string>\",\n  \"requestedBy\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("If-Match", "<if-match>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/merge-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "employeeNumber": "<string>",
  "firstName": "<string>",
  "preferredName": "<string>",
  "lastName": "<string>",
  "workEmail": "<string>",
  "workPhone": "<string>",
  "jobTitle": "<string>",
  "department": "<string>",
  "orgUnits": [
    {
      "level": "<string>",
      "name": "<string>"
    }
  ],
  "location": "<string>",
  "companyId": "<string>",
  "managerId": "<string>",
  "employmentType": "<string>",
  "status": "upcoming",
  "startDate": "<string>",
  "lastDay": "<string>",
  "updatedAt": "2023-11-07T05:31:56Z",
  "positionNumber": "<string>",
  "positionTitle": "<string>",
  "reportsToPositionId": "<string>",
  "personalEmail": "<string>",
  "mobile": "<string>",
  "homeAddress": {
    "line1": "<string>",
    "unitNumber": "<string>",
    "complexName": "<string>",
    "suburb": "<string>",
    "city": "<string>",
    "province": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "dateOfBirth": "<string>",
  "nationality": "<string>",
  "gender": "<string>",
  "race": "<string>",
  "eeDesignation": "<string>",
  "disability": true,
  "medicalAidMember": true
}

{
  "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>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 0,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "pointer": "<string>",
      "code": "<string>",
      "detail": "<string>"
    }
  ],
  "fields": [
    "<string>"
  ],
  "existingId": "<string>",
  "step": "<string>"
}

Authorizations

Authorization

string

header

required

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

If-Match

string

required

The ETag of the record as you read it. A stale one is 412 and nothing is written.

Path Parameters

string

required

The employee id.

Query Parameters

company_id

string

One of the key's companies.

Body

application/merge-patch+json

preferredName

string | null

Needs Personal details (Write).

Maximum string length: 100

personalEmail

string<email> | null

Needs Personal contact (Write).

Pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

mobile

string | null

Needs Personal contact (Write). Such as +27 82 555 0142.

Maximum string length: 20

homeAddress

object | null

Needs Personal contact (Write). Merged part by part: a part sent as null is removed, a part left out is kept.

Show child attributes

dateOfBirth

string<date> | null

Needs Personal details (Write).

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])))$

nationality

string | null

Needs Personal details (Write). ISO 3166 two-letter code.

Pattern: ^[A-Z]{2}$

requestedBy

string

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

Response

Changed. The employee as the key reads it, with its new ETag.

string

required

The employee id. Stable for the life of the record.

employeeNumber

string | null

required

firstName

string | null

required

preferredName

string | null

required

lastName

string | null

required

workEmail

string | null

required

workPhone

string | null

required

jobTitle

string | null

required

department

string | null

required

orgUnits

object[]

required

The structure levels below Company that the person sits in, outermost first.

Show child attributes

location

string | null

required

companyId

string

required

The company that employs the person. Needs a key that holds this company.

managerId

string | null

required

The manager's employee id, from the position the person holds.

employmentType

string | null

required

status

enum<string>

required

upcoming: the hire is final and the start date is ahead. active: started and not yet left. left: the last day has passed or access has ended.

Available options:

upcoming,

active,

left

startDate

string | null

required

The first day of work, as a date in the company's time zone.

Pattern: ^\d{4}-\d{2}-\d{2}$

lastDay

string | null

required

The last day of work, as a date in the company's time zone. Null until a termination is recorded.

Pattern: ^\d{4}-\d{2}-\d{2}$

updatedAt

string<date-time>

required

When any field of this record last changed. Use it with updated_since.

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])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

positionNumber

string | null

positionTitle

string | null

reportsToPositionId

string | null

personalEmail

string | null

mobile

string | null

homeAddress

object | null

Show child attributes

dateOfBirth

string | null

Pattern: ^\d{4}-\d{2}-\d{2}$

nationality

string | null

gender

string | null

race

string | null

eeDesignation

string | null

disability

boolean | null

medicalAidMember

boolean | null

Directory

Organisation

Positions

Time off

Job history

Leave

Certifications

Pay

Performance

Documents

Hires

Authentication

Reference

Webhooks

Change an employee's personal and contact details

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response