---
title: "Assign expert candidates"
method: POST
path: "/api/assign-expert"
tags: ["assign-expert"]
---

# Assign expert candidates

`POST /api/assign-expert`

Returns experts compatible with city and optional role/gender/approach/availability filters.

## Request body

- AssignExpertRequest — Assign expert request model.
  - `city_id` integer, required — City ID
  - `gender` 'female' | 'male', nullable — Optional expert gender filter
  - `role` 'psi' | 'nutri', nullable — Optional expert role filter
  - `location_type` 'online' | 'in_person', required — Required availability location filter
  - `approach` string, nullable — Optional approach text filter (matches expert bio)
  - `availability_days` string[], nullable — Optional availability weekday filter (array)
  - `availability_slots` string[], nullable — Optional time-of-day slot filter (array)
  - `availability_time_from` string, nullable — Optional lower bound time filter (HH:MM or HH:MM:SS)
  - `availability_time_to` string, nullable — Optional upper bound time filter (HH:MM or HH:MM:SS)
  - `age_min` integer, nullable — Optional minimum operator age
  - `age_max` integer, nullable — Optional maximum operator age

## Response `200`

Successful Response

- AssignExpertResponse — Assign expert response model.
  - `total` integer — Total matched experts
  - `items` AssignExpertItem[] — Matched experts list
    - `operator_id` string, uuid, required — Operator UUID
    - `first_name` string, nullable — Operator first name
    - `last_name` string, nullable — Operator last name
    - `email` string, nullable — Operator email
    - `city` string, nullable — Operator work city
    - `approach` string, nullable — Approach tag extracted from bio [approach]
    - `gender` 'female' | 'male', nullable — Operator gender
    - `profession` string, nullable — Operator profession
    - `call_duration` integer, nullable — Default call duration in minutes
    - `max_patients` string, nullable — Operator max patients threshold
    - `current_patients` integer — Current number of assigned patients
    - `matching_slots` integer — Number of matching availability slots
    - `next_available_slots` string[] — Next matching available slots ordered by slot datetime
    - `min_distance_km` string, nullable — Minimum distance in km from patient city
    - `ranking_score` number, nullable — Computed ranking score
    - `total_assigned` integer — Most recent total assigned patients metric
    - `active_patients` integer — Most recent active patients metric
    - `active_assigned_ratio` number, nullable — Active/assigned ratio (recent month)
    - `adherence_rate` number, nullable — Frequency compliance percentage
    - `patients_dropout` integer — Dropout patients count metric
    - `total_patients_metric` integer — Total patients metric used for ranking
    - `early_dropout_rate_60d` number, nullable — Dropout rate within first 60 days
    - `average_dropout_days` number, nullable — Average days before dropout
    - `days_since_last_assignment` number, nullable — Days since last assignment event
    - `last_assignment_date` string, date-time, nullable — Last assignment datetime
    - `support_call_date` string, date-time, nullable — First completed support/supervision call date used for assignment capacity windows
    - `assignment_capacity_remaining` integer — Remaining assignments available in the current capacity window
    - `priority_score` number, nullable — Final mixed priority score

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/corabea/corabea-api/revisions/13c1bce1bdc4/schema)