Transfer employee ownership to a new person

Request

Suspends (or deletes) the existing employee account and provisions a new employee in its place, inheriting the same team and supervisor. Requires the caller to have PEOPLE_EDIT permission.

Security

oauth2ClientCredentials(Required scopes: employees:write)

org_wallet_refstring

Organization wallet reference, defaults to "1" if not provided

business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired

employee_idstring

ID of the existing employee to transfer ownership from. Either employee_id or external_id is required.

Example:"abc123xyz"

external_idstring

External employee ID (alternative identifier). Either employee_id or external_id is required.

Example:"ext-456"

namestringrequired

Full name of the new employee taking ownership

Example:"John Mwangi"

emailstringrequired

Email address of the new employee. Must not be in use by any active user.

Example:"john.mwangi@company.com"

phonestringrequired

Phone number of the new employee in international format. Must not be in use by any active user.

Example:"+254798765432"

new_statusstring

Status to set on the old employee record after the transfer completes. Defaults to SUSPENDED.

Default:"SUSPENDED"

Enum:"SUSPENDED""DELETED"

Example:"SUSPENDED"

curl -i -X POST \
  https://developer.boyahq.com/_mock/v2/openapi/employees/transfer-ownership \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -H 'org_wallet_ref: string' \
  -d '{
    "employee_id": "abc123xyz",
    "external_id": "ext-456",
    "name": "John Mwangi",
    "email": "john.mwangi@company.com",
    "phone": "+254798765432",
    "new_status": "SUSPENDED"
  }'

Responses

Ownership transferred successfully. Returns the new employee ID and the old employee's updated status.

Bodyapplication/json

new_employee_idstringrequired

Employee ID of the newly created employee

Example:"xyz789abc123"

old_employee_statusstringrequired

Status that was applied to the old employee record

Enum:"SUSPENDED""DELETED"

Example:"SUSPENDED"

Response

{
  "new_employee_id": "xyz789abc123",
  "old_employee_status": "SUSPENDED"
}