Staff Management API

External integration

The staff management API is used to administer all staff members who have access to the Altafid platform within a tenant. This includes both direct tenant staff and partner staff assigned to the tenant. All endpoints are under the /api/tenant-staff base path.

Staff categories: TENANT_STAFF are users directly employed or registered under the tenant. PARTNER_STAFF are users assigned through a partner relationship. Both categories are managed through the same set of endpoints.

Read endpoints

Endpoint	Purpose	Roles
`GET /api/tenant-staff/all`	All staff for the current tenant (tenant and partner combined).	`SYSTEM_ADMIN`, `TENANT_ADMIN`, `PARTNER_ADMIN`
`GET /api/tenant-staff/all/paginated`	Paginated version of the all-staff list.	`SYSTEM_ADMIN`, `TENANT_ADMIN`, `PARTNER_ADMIN`
`GET /api/tenant-staff/all/by-category/{category}`	Staff filtered by category: `TENANT_STAFF` or `PARTNER_STAFF`.	`SYSTEM_ADMIN`, `TENANT_ADMIN`, `PARTNER_ADMIN`
`GET /api/tenant-staff/{tenantUuid}/all`	All staff for a specific tenant (system admin use).	`SYSTEM_ADMIN`
`GET /api/tenant-staff/{staffUuid}`	Single staff member by UUID.	`SYSTEM_ADMIN`, `TENANT_ADMIN`, `PARTNER_ADMIN`, `TENANT_STAFF`

curl "https://api.altafid.dev.altafid.net/api/tenant-staff/all" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_ADMIN"

A staff member response (TenantStaffDTO):

{
  "tenantStaffUuid": "TS019C06688AA57248B9EA5325DBDFC48E",
  "tenantUuid": "T019A16FF372A70B5A9307B00CE85E4DA",
  "firstName": "Carlos",
  "middleName": null,
  "paternalLastName": "Mendoza",
  "maternalLastName": "Reyes",
  "userEmail": "carlos.mendoza@conpat.com",
  "email": "carlos.mendoza@conpat.com",
  "staffType": "ADMIN",
  "legalResidence": "MX",
  "timeZone": "America/Mexico_City",
  "platformLanguage": "SPANISH",
  "commissionCurrency": "MXN",
  "contactPhone": { "countryCode": "+52", "number": "5512345678" },
  "jobPosition": "Senior Advisor",
  "dateOfBirth": "1985-06-15",
  "currentResidence": "Mexico City",
  "isActive": true,
  "createdAt": "2025-03-01T09:00:00",
  "updatedAt": "2026-01-10T14:30:00"
}

Create staff

POST/api/tenant-staff

Creates a new tenant staff member. The user account (credentials) is created at the same time. Returns 201 Created with the full staff DTO. Requires SYSTEM_ADMIN or TENANT_ADMIN.

{
  "tenantUuid": "T019A16FF372A70B5A9307B00CE85E4DA",
  "firstName": "Ana",
  "paternalLastName": "Garcia",
  "maternalLastName": "Lopez",
  "userEmail": "ana.garcia@conpat.com",
  "email": "ana.garcia@conpat.com",
  "password": "SecurePass123!",
  "confirmPassword": "SecurePass123!",
  "staffType": "ADVISOR",
  "staffRole": "ADVISOR",
  "legalResidence": "MX",
  "currentResidence": "Guadalajara",
  "timeZone": "America/Mexico_City",
  "platformLanguage": "SPANISH",
  "commissionCurrency": "MXN",
  "contactPhone": { "countryCode": "+52", "number": "3312345678" },
  "jobPosition": "Financial Advisor",
  "dateOfBirth": "1990-09-22"
}

Field	Required	Notes
`tenantUuid`	Yes	Must be a valid tenant UUID.
`firstName`	Yes	2–50 characters.
`paternalLastName`	Yes	1–50 characters.
`userEmail`	Yes	Login email; max 100 characters.
`email`	Yes	Contact email; max 100 characters.
`password`	Yes	8–100 characters.
`confirmPassword`	Yes	Must match `password`.
`staffType`	Yes	`ADMIN`, `ADVISOR`, or `MANAGER`.
`staffRole`	Yes	Currently must be `ADVISOR`.
`legalResidence`	Yes	Country code.
`timeZone`	Yes	IANA timezone string.
`platformLanguage`	Yes	Platform display language.
`commissionCurrency`	Yes	ISO 4217 currency code.

Update staff

PUT/api/tenant-staff/{tenantStaffUuid}

Updates an existing staff member. Partial updates are supported — only send the fields you intend to change. Requires SYSTEM_ADMIN, TENANT_ADMIN, or PARTNER_ADMIN. Returns the updated TenantStaffDTO on success, or 409 if the email is already in use by another account.

Search staff

GET/api/tenant-staff/search?name={query}

Case-insensitive fuzzy match on first name and last name. Returns a paginated list of matching staff members. Supports standard page, size, and sort query parameters.

curl "https://api.altafid.dev.altafid.net/api/tenant-staff/search?name=garcia&page=0&size=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_ADMIN"

Delete staff

DELETE/api/tenant-staff/{tenantStaffUuid}

Deletes a staff member using a soft-delete workflow. The staff UUID in the path must match the UUID in the request body. Requires TENANT_ADMIN or PARTNER_ADMIN.

{
  "staffUuidToDelete": "TS019C06688AA57248B9EA5325DBDFC48E"
}

Credential management

Two endpoints manage the login credentials of an existing staff member. Neither requires a special role beyond standard admin access.

Endpoint	Purpose	Response
POST `/api/tenant-staff/{tenantStaffUuid}/credentials/reset`	Triggers a password reset email to the staff member's registered email address.	`202 Accepted`
PUT `/api/tenant-staff/{tenantStaffUuid}/credentials/create`	Sets a new password directly (admin override, no email flow).	`204 No Content`

Request body for direct password set:

{
  "password": "NewSecurePass123!"
}

Password requirements: minimum 8 characters. The server validates the password field is present; the same length and character constraints that apply on creation apply here.