Employees

Before You Start

Read the following guides before proceeding:

Overview

An employee is a person acting inside one corporation. The employee record holds the identity used for
card embossing and delivery, the role that resolves into permissions, and the wallet address the person
signs with.

Employees are created by invitation, not by registration. The invite creates the record in status
Invited; the person claims it by logging in with their own wallet and email, which binds those values
and moves the record to Active.

Invited → Active ←→ Disabled

Step 1: Invite an Employee

POST /api/v1/employees/invite

Requires EmployeeSu or EmployeeManage.

Request body:

{
  "first_name": "Alex",
  "last_name": "Grey",
  "email": "[email protected]",
  "role_id": "7386b48f-df9c-49fe-8ccc-38b5b0b55932",
  "phone": "+447700900123",
  "department": "Finance",
  "job_title": "Analyst",
  "manager_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "residence_address": {
    "line1": "10 Downing Street",
    "line2": "Flat 2",
    "city": "London",
    "state": "",
    "country": "GB",
    "postal_code": "SW1A 2AA"
  }
}

Response:

{}

Personal data on the employee record is what gets embossed on their cards. Card issuance uses
the employee's "<first_name> <last_name>", truncated to 25 characters, and ignores the
name_on_card field in the issuance request, whenever first_name, last_name, email and
phone are all present. Since all four are required at invite, that is every employee — to emboss a
corporate name such as Acme Inc IT instead, issue the card without employee_id. See
Issuing a Card.

Field Validation

Names are restricted to unaccented Latin letters. José, Müller and O'Brien-Smith behave
differently: the apostrophe and hyphen are allowed, accented characters are not. Transliterate before
sending, and keep the transliterated form — it is what will be printed on the card.

Code

const response = await fetch(`${baseUrl}/api/v1/employees/invite`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${corporationToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'Alex',
    last_name: 'Grey',
    email: '[email protected]',
    role_id: roleId,
    phone: '+447700900123'
  })
});

response = requests.post(
    f"{base_url}/api/v1/employees/invite",
    headers={
        "Authorization": f"Bearer {corporation_token}",
        "Content-Type": "application/json",
    },
    json={
        "first_name": "Alex",
        "last_name": "Grey",
        "email": "[email protected]",
        "role_id": role_id,
        "phone": "+447700900123",
    },
)

body, _ := json.Marshal(map[string]string{
    "first_name": "Alex",
    "last_name":  "Grey",
    "email":      "[email protected]",
    "role_id":    roleID,
    "phone":      "+447700900123",
})

req, _ := http.NewRequest("POST", baseURL+"/api/v1/employees/invite", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+corporationToken)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Step 2: The Employee Claims the Record

There is no accept-invitation endpoint. The invited person calls
POST /api/v1/corporations/login with a partner token and their own X-User-Wallet and
X-User-Email. The handler finds the Invited record by email, binds the wallet address and email to
it, and returns a corporation token.

Two conditions must hold:

• The record is still in status Invited and carries no wallet address. A record already bound to a
  wallet is refused with 401 and Employee registration is already completed.
• The record is not Disabled — refused with 401 and Employee is disabled.

See Authentication.

List Employees

GET /api/v1/employees

Requires EmployeeSu, EmployeeManage or EmployeeView.

Query parameters:

Response:

{
  "employees": [
    {
      "id": "64120850-73a1-4df5-a074-d463258c9deb",
      "corporation_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
      "owner_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
      "email": "[email protected]",
      "first_name": "Alex",
      "last_name": "Grey",
      "phone": "+447700900123",
      "department": "Finance",
      "job_title": "Analyst",
      "manager_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
      "manager_name": "John Smith",
      "role_id": "7386b48f-df9c-49fe-8ccc-38b5b0b55932",
      "status": "Active",
      "residence_address": {
        "line1": "10 Downing Street",
        "line2": "Flat 2",
        "city": "London",
        "state": "",
        "country": "GB",
        "postal_code": "SW1A 2AA"
      },
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:05:00Z"
    }
  ]
}

Search Employees

GET /api/v1/employees/search

Requires EmployeeSu, EmployeeManage or EmployeeView.

Query parameters:

Providing manager_address alone returns that manager's reports. Providing neither is rejected with
Search term must contain at least 2 characters.

The response shape matches GET /api/v1/employees.

Read One Employee

GET /api/v1/employees/{employeeId}

Path parameters:

The route declares no permission, but the handler enforces one: a caller may always read their own
record. Reading anyone else's requires Su, EmployeeSu, EmployeeManage or EmployeeView — without
one, the call returns 403 with Insufficient permission to read this employee.

The record must belong to the caller's corporation. An employee id from another corporation returns
401 with Employee does not belong to corporation, not 404 — the same response as a non-existent
id, so it cannot be used to probe for other tenants' ids.

The response shape matches one item of GET /api/v1/employees.

Update Personal Data

PUT /api/v1/employees/{employeeId}

Requires EmployeeSu or EmployeeManage.

Request body:

{
  "first_name": "Alex",
  "last_name": "Grey",
  "phone": "+447700900123",
  "department": "Treasury",
  "job_title": "Senior Analyst",
  "manager_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "residence_address": {
    "line1": "10 Downing Street",
    "city": "London",
    "country": "GB",
    "postal_code": "SW1A 2AA"
  }
}

Response:

{}

An update may omit phone, but it may not clear it. Phone is required on every employee, so
sending "phone": "" is rejected with 400 — omit the field entirely to leave the current value
alone.

email is bound at invitation and is the employee's login identity. Sending a new value here changes
nothing and returns 200 — it does not report that the field was ignored. To move an employee to a
different address, delete the record and invite again.

Updating personal data does not re-emboss existing cards. The name on an issued card is fixed at
issuance.

Change an Employee's Role

PUT /api/v1/employees/{employeeId}/role

Requires EmployeeSu or EmployeeManage.

Request body:

{
  "role_id": "31eba1db-0809-4d44-a479-0b696c4a2603"
}

Response:

{}

The change takes effect at the employee's next login. Permissions are resolved from the role when
the corporation token is minted and frozen into it. An employee holding a live token keeps their old
permissions until it expires or they log in again. Where a role change is a revocation, treat the
token lifetime as the revocation delay.

Delete an Employee

DELETE /api/v1/employees/{employeeId}

Requires EmployeeSu or EmployeeManage.

Response:

{}

Three deletions are refused with 401:

Deleting an employee does not close their cards. Close or block cards first — see
Managing a Card.

Error Handling

{
  "error_reason": "ErrorGeneral",
  "error_description": "Request failed validation",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "first_name", "details": "First name is invalid" }
  ]
}

Employee validation errors carry the field name as the error_details key, not as a field entry.
Read error_details[].key to find which field failed.

Validation Errors (400)

Authorization Errors (401, 403)

Server Errors (500)