Expats

Overview

Expats endpoints provide CRUD operations, invitations, and status updates for expat resources.

Endpoint Summary

Method	Route	Purpose
`GET`	`/v1/data/expats`	List expats
`POST`	`/v1/data/expats`	Create expat
`POST`	`/v1/data/expats/invite`	Send expat invite
`PATCH`	`/v1/data/expats/status`	Update expat status
`GET`	`/v1/data/expats/{expatId}`	Get expat by ID
`PUT`	`/v1/data/expats/{expatId}`	Update expat
`DELETE`	`/v1/data/expats/{expatId}`	Delete expat

`GET /v1/data/expats`

Return the list of expats available in the authenticated tenant context.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Accept`	Yes	`application/json`

Query Parameters

Parameter	Type	Required	Description
`per_page`	`number`	No	Number of items per page.
`page`	`number`	No	Current page number.
`include`	`string`	No	Supported value: `details`.

Example Request

curl -X GET "{{BASE_URL}}/v1/data/expats" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (`200`)

{
  "success": true,
  "result": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 3,
    "total": 51,
    "items": [
      {
        "user": {
          "id": 501,
          "uuid": "a2b43f5c-3cb9-4e87-bfe3-9d34b2665f8a",
          "first_name": "Jane",
          "last_name": "Doe",
          "name": "Jane Doe",
          "email": "[email protected]",
          "entity_id": 101,
          "entity_uuid": "2f4ab561-8e64-45f8-a2dc-8044e08a963f",
          "entity_type": "expat",
          "primary_image_path": null,
          "is_primary": true,
          "phone_prefix": null,
          "phone_country": null,
          "phone_number": null,
          "phone": null,
          "status": "active",
          "status_reason": null,
          "created_at": "2026-03-11T08:17:14+00:00",
          "updated_at": "2026-04-29T08:12:53+00:00",
          "timezone": "Europe/Bucharest"
        },
        "id": 101,
        "primary_image_path": null,
        "client_id": 77,
        "employee_id": null,
        "company_name": "Example Client Ltd",
        "user_id": 501,
        "name": "Jane Doe",
        "email": "[email protected]",
        "payroll_id": null,
        "primary_citizenship_id": null,
        "status_id": 1,
        "status_name": "Active",
        "license": null,
        "country_code": "DE",
        "primary_citizenship": null,
        "contracting_legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
        "contracting_legal_entity": {
          "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
          "label": "XPath Germany GmbH"
        },
        "office_id": 12,
        "department_id": "HR",
        "segment_id": "f6f5e87f-a1fc-4ac2-9d9a-676bc94f0d3b",
        "designation": null
      }
    ],
    "filters": [],
    "resource_columns": []
  }
}

`POST /v1/data/expats`

Create a new expat resource.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`application/json`

Request Body Fields

Field	Type	Required	Description
`first_name`	`string`	Yes	Expat first name.
`last_name`	`string`	Yes	Expat last name.
`email`	`string`	Yes	Expat email (must be unique).
`contracting_legal_entity_id`	`string`	Yes	Contracting legal entity UUID.
`client_id`	`number`	Conditional	Required when client context is not inferred from authentication.
`phone_prefix`	`string`	No	Phone prefix.
`phone_number`	`string`	No	Phone number.
`country_code`	`string`	No	ISO country code (2 chars).
`details.department_name`	`string`	No	Department name.
`details.company_position`	`string`	No	Company position.
`primary_citizenship`	`string`	No	Primary citizenship code/value.

Example Request

curl -X POST "{{BASE_URL}}/v1/data/expats" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "contracting_legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "country_code": "DE",
    "details": {
      "department_name": "HR",
      "company_position": "Manager"
    }
  }'

Success Response (`200`)

{
  "success": true,
  "result": {
    "user": {
      "id": 501,
      "uuid": "a2b43f5c-3cb9-4e87-bfe3-9d34b2665f8a",
      "first_name": "Jane",
      "last_name": "Doe",
      "name": "Jane Doe",
      "email": "[email protected]",
      "entity_id": 101,
      "entity_uuid": "2f4ab561-8e64-45f8-a2dc-8044e08a963f",
      "entity_type": "expat",
      "primary_image_path": null,
      "is_primary": true,
      "phone_prefix": null,
      "phone_country": null,
      "phone_number": null,
      "phone": null,
      "status": "active",
      "status_reason": null,
      "created_at": "2026-03-11T08:17:14+00:00",
      "updated_at": "2026-04-29T08:12:53+00:00",
      "timezone": "Europe/Bucharest"
    },
    "id": 101,
    "primary_image_path": null,
    "client_id": 77,
    "employee_id": null,
    "company_name": "Example Client Ltd",
    "user_id": 501,
    "name": "Jane Doe",
    "email": "[email protected]",
    "payroll_id": null,
    "primary_citizenship_id": null,
    "status_id": 1,
    "status_name": "Active",
    "license": null,
    "country_code": "DE",
    "primary_citizenship": null,
    "contracting_legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "contracting_legal_entity": {
      "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "label": "XPath Germany GmbH"
    },
    "office_id": 12,
    "department_id": "HR",
    "segment_id": "f6f5e87f-a1fc-4ac2-9d9a-676bc94f0d3b",
    "designation": null,
    "address": null,
    "region": null,
    "city": null,
    "zip_code": null,
    "bank_name": null,
    "swift_code": null,
    "bank_account_number": null,
    "declined_reason": null,
    "details": {
      "marital_status_id": null,
      "marital_status": null,
      "education_form_id": null,
      "education_form": null,
      "office_id": 12,
      "manager_id": 223,
      "manager_email": "[email protected]",
      "manager_name": "John Manager",
      "department_name": "HR",
      "company_position": "Manager",
      "birth_date": null,
      "birth_country": null,
      "birth_city": null,
      "primary_language": null,
      "joined_at": null
    },
    "company_position": "Manager"
  }
}

Error Example

422 Unprocessable Entity

{
  "error": {
    "code": "validation_error",
    "message": "The request payload is invalid."
  }
}

`POST /v1/data/expats/invite`

Send invitation emails for one or more expats.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`application/json`

Request Body Fields

Field	Type	Required	Description
`expat_ids`	`array<number>`	Yes	List of expat IDs to invite.

Example Request

curl -X POST "{{BASE_URL}}/v1/data/expats/invite" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "expat_ids": [101, 102]
  }'

Success Response (`200`)

{
  "success": true,
  "result": []
}

`PATCH /v1/data/expats/status`

Update status for one or more expats.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`application/json`

Request Body Fields

Field	Type	Required	Description
`ids`	`array<number>`	Yes	Expat IDs to update.
`status_id`	`number`	Yes	Target status identifier.
`declined_reason`	`string`	Conditional	Required for declined/refused status values.

Example Request

curl -X PATCH "{{BASE_URL}}/v1/data/expats/status" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "ids": [101, 102],
    "status_id": 2
  }'

Success Response (`200`)

{
  "success": true,
  "result": {
    "status_id": 2,
    "status_name": "Active",
    "declined_reason": null
  },
  "message": "Updated successfully!"
}

`GET /v1/data/expats/{expatId}`

Return expat details for the provided identifier.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Accept`	Yes	`application/json`

Path Parameters

Parameter	Type	Required	Description
`expatId`	`number`	Yes	Expat identifier.

Example Request

curl -X GET "{{BASE_URL}}/v1/data/expats/{{EXPAT_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (`200`)

{
  "success": true,
  "result": {
    "user": {
      "id": 501,
      "uuid": "a2b43f5c-3cb9-4e87-bfe3-9d34b2665f8a",
      "first_name": "Jane",
      "last_name": "Doe",
      "name": "Jane Doe",
      "email": "[email protected]",
      "entity_id": 101,
      "entity_uuid": "2f4ab561-8e64-45f8-a2dc-8044e08a963f",
      "entity_type": "expat",
      "primary_image_path": null,
      "is_primary": true,
      "phone_prefix": null,
      "phone_country": null,
      "phone_number": null,
      "phone": null,
      "status": "active",
      "status_reason": null,
      "created_at": "2026-03-11T08:17:14+00:00",
      "updated_at": "2026-04-29T08:12:53+00:00",
      "timezone": "Europe/Bucharest"
    },
    "id": 101,
    "primary_image_path": null,
    "client_id": 77,
    "employee_id": null,
    "company_name": "Example Client Ltd",
    "user_id": 501,
    "name": "Jane Doe",
    "email": "[email protected]",
    "payroll_id": null,
    "primary_citizenship_id": null,
    "status_id": 1,
    "status_name": "Active",
    "license": null,
    "country_code": "DE",
    "primary_citizenship": null,
    "contracting_legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "contracting_legal_entity": {
      "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "label": "XPath Germany GmbH"
    },
    "office_id": 12,
    "department_id": "HR",
    "segment_id": "f6f5e87f-a1fc-4ac2-9d9a-676bc94f0d3b",
    "designation": null,
    "allowed_actions": {
      "delete": true,
      "update": true
    },
    "address": null,
    "region": null,
    "city": null,
    "zip_code": null,
    "bank_name": null,
    "swift_code": null,
    "bank_account_number": null,
    "declined_reason": null,
    "details": {
      "marital_status_id": null,
      "marital_status": null,
      "education_form_id": null,
      "education_form": null,
      "office_id": 12,
      "manager_id": 223,
      "manager_email": "[email protected]",
      "manager_name": "John Manager",
      "department_name": "HR",
      "company_position": "Manager",
      "birth_date": null,
      "birth_country": null,
      "birth_city": null,
      "primary_language": null,
      "joined_at": null
    },
    "company_position": "Manager"
  }
}

`PUT /v1/data/expats/{expatId}`

Update an existing expat.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`application/json`

Path Parameters

Parameter	Type	Required	Description
`expatId`	`number`	Yes	Expat identifier.

Request Body Fields

Field	Type	Required	Description
`user_id`	`number`	Yes	Linked user identifier.
`status_id`	`number`	Yes	Expat status identifier.
`contracting_legal_entity_id`	`string`	Yes	Contracting legal entity UUID.
`details`	`object`	Yes	Expat details object.
`client_id`	`number`	Conditional	Required when client context is not inferred from authentication.
`first_name`	`string`	No	Expat first name.
`last_name`	`string`	No	Expat last name.
`email`	`string`	No	Expat email (must be unique).
`phone_prefix`	`string`	No	Phone prefix.
`phone_number`	`string`	No	Phone number.
`details.manager_id`	`number`	No	Manager user identifier.

Example Request

curl -X PUT "{{BASE_URL}}/v1/data/expats/{{EXPAT_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "user_id": 501,
    "status_id": 1,
    "contracting_legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "first_name": "Jane",
    "last_name": "Smith",
    "details": {
      "manager_id": 223
    }
  }'

Success Response (`200`)

{
  "success": true,
  "result": {
    "user": {
      "id": 501,
      "uuid": "a2b43f5c-3cb9-4e87-bfe3-9d34b2665f8a",
      "first_name": "Jane",
      "last_name": "Smith",
      "name": "Jane Smith",
      "email": "[email protected]",
      "entity_id": 101,
      "entity_uuid": "2f4ab561-8e64-45f8-a2dc-8044e08a963f",
      "entity_type": "expat",
      "primary_image_path": null,
      "is_primary": true,
      "phone_prefix": null,
      "phone_country": null,
      "phone_number": null,
      "phone": null,
      "status": "active",
      "status_reason": null,
      "created_at": "2026-03-11T08:17:14+00:00",
      "updated_at": "2026-04-29T08:12:53+00:00",
      "timezone": "Europe/Bucharest"
    },
    "id": 101,
    "primary_image_path": null,
    "client_id": 77,
    "employee_id": null,
    "company_name": "Example Client Ltd",
    "user_id": 501,
    "name": "Jane Smith",
    "email": "[email protected]",
    "payroll_id": null,
    "primary_citizenship_id": null,
    "status_id": 1,
    "status_name": "Active",
    "license": null,
    "country_code": "DE",
    "primary_citizenship": null,
    "contracting_legal_entity_id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
    "contracting_legal_entity": {
      "id": "df6f8c4b-b35f-4f2a-9f96-968bd61b3e81",
      "label": "XPath Germany GmbH"
    },
    "office_id": 12,
    "department_id": "HR",
    "segment_id": "f6f5e87f-a1fc-4ac2-9d9a-676bc94f0d3b",
    "designation": null,
    "allowed_actions": {
      "delete": true,
      "update": true
    },
    "address": null,
    "region": null,
    "city": null,
    "zip_code": null,
    "bank_name": null,
    "swift_code": null,
    "bank_account_number": null,
    "declined_reason": null,
    "details": {
      "marital_status_id": null,
      "marital_status": null,
      "education_form_id": null,
      "education_form": null,
      "office_id": 12,
      "manager_id": 223,
      "manager_email": "[email protected]",
      "manager_name": "John Manager",
      "department_name": "HR",
      "company_position": "Manager",
      "birth_date": null,
      "birth_country": null,
      "birth_city": null,
      "primary_language": null,
      "joined_at": null
    },
    "company_position": "Manager"
  }
}

`DELETE /v1/data/expats/{expatId}`

Delete an expat.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer {{ACCESS_TOKEN}}`
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`application/json`

Path Parameters

Parameter	Type	Required	Description
`expatId`	`number`	Yes	Expat identifier.

Request Body Fields

Field	Type	Required	Description
`reason`	`string`	Yes	Deletion reason.

Example Request

curl -X DELETE "{{BASE_URL}}/v1/data/expats/{{EXPAT_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "reason": "No longer needed"
  }'

Success Response (`200`)

{
  "success": true,
  "result": []
}

Overview​

Endpoint Summary​

GET /v1/data/expats​

Headers​

Query Parameters​

Example Request​

Success Response (200)​

POST /v1/data/expats​

Headers​

Request Body Fields​

Example Request​

Success Response (200)​

Error Example​

POST /v1/data/expats/invite​

Headers​

Request Body Fields​

Example Request​

Success Response (200)​

PATCH /v1/data/expats/status​

Headers​

Request Body Fields​

Example Request​

Success Response (200)​

GET /v1/data/expats/{expatId}​

Headers​

Path Parameters​

Example Request​

Success Response (200)​

PUT /v1/data/expats/{expatId}​

Headers​

Path Parameters​

Request Body Fields​

Example Request​

Success Response (200)​

DELETE /v1/data/expats/{expatId}​

Headers​

Path Parameters​

Request Body Fields​

Example Request​

Success Response (200)​

Overview

Endpoint Summary

`GET /v1/data/expats`

Headers

Query Parameters

Example Request

Success Response (`200`)

`POST /v1/data/expats`

Headers

Request Body Fields

Example Request

Success Response (`200`)

Error Example

`POST /v1/data/expats/invite`

Headers

Request Body Fields

Example Request

Success Response (`200`)

`PATCH /v1/data/expats/status`

Headers

Request Body Fields

Example Request

Success Response (`200`)

`GET /v1/data/expats/{expatId}`

Headers

Path Parameters

Example Request

Success Response (`200`)

`PUT /v1/data/expats/{expatId}`

Headers

Path Parameters

Request Body Fields

Example Request

Success Response (`200`)

`DELETE /v1/data/expats/{expatId}`

Headers

Path Parameters

Request Body Fields

Example Request

Success Response (`200`)