Create Provider

Step-by-step guide to adding a new provider to your clinic

Overview

Creating a provider involves either flagging an existing user as a provider or creating a new user with the provider flag enabled. This guide covers both scenarios.

Per-Clinic Providers: When you create a provider, they are flagged as a provider ONLY in the current clinic. The same user can be a regular staff member in other clinics.

Prerequisites

Before creating a provider:

1. Required Permissions

   You must have CLINIC_ADMIN role in the clinic where you’re creating the provider.

2. Clinic Context

   Ensure the correct clinic is selected in the clinic selector (top-right dropdown).

3. User Information

   Prepare the provider’s email, phone number, and full name.

Method 1: Flag Existing User as Provider

Use this method when the user already exists in your clinic (e.g., administrative staff becoming a provider).

1. Navigate to Users

   Go to Users section from the main menu.

2. Find the User

   Use search to locate the user by name or email.

3. Open Edit Dialog

   Click the Edit icon on the user’s card.

4. Enable Provider Flag

   Toggle Is Provider to true.

5. Save Changes

   Click Save to update the user’s profile.

API Request (Method 1)

PATCH /v1/users/{user_clinic_id}?clinic_id={clinic_id}

curl -X PATCH "https://api.clinic.example.com/v1/users/{user_clinic_id}?clinic_id={clinic_id}" \
  -H "Cookie: access_token={jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_provider": true
  }'

Response

{
  "id": "abc-123-def-456",
  "user_id": "user-789-xyz-012",
  "full_name": "Dr. María García",
  "email": "[e-mail]",
  "phone_e164": "[phone]",
  "is_provider": true,
  "clinic_role": "STAFF",
  "status": "approved",
  "created_at": "2025-12-01T10:30:00Z",
  "updated_at": "2026-01-17T09:15:00Z"
}

Existing Appointments: If the user had existing appointments scheduled BEFORE being flagged as a provider, those appointments remain valid. Future appointments will now be calculated using this user’s provider availability.

Method 2: Create New User as Provider

Use this method when hiring a new team member who will be a provider.

1. Navigate to Create User

   Go to Users → Create User or click the Add User button.

2. Fill User Information

   • Full Name: Provider’s full name
   • Email: Professional email address (must be unique globally)
   • Phone: E.164 format (e.g., [phone])
   • Role: Select clinic role (STAFF or CLINIC_ADMIN)
3. Enable Provider Flag

   Toggle Is Provider to true.

4. Set Initial Status

   Choose approved (active immediately) or pending (requires approval).

5. Submit Form

   Click Create User to save.

API Request (Method 2)

POST /v1/users?clinic_id={clinic_id}

curl -X POST "https://api.clinic.example.com/v1/users?clinic_id={clinic_id}" \
  -H "Cookie: access_token={jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "full_name": "Dr. Juan López",
    "phone_e164": "[phone]",
    "clinic_role": "STAFF",
    "is_provider": true,
    "status": "approved",
    "password": "SecurePassword123!"
  }'

Response

{
  "id": "def-456-ghi-789",
  "user_id": "user-012-abc-345",
  "full_name": "Dr. Juan López",
  "email": "[e-mail]",
  "phone_e164": "[phone]",
  "is_provider": true,
  "clinic_role": "STAFF",
  "status": "approved",
  "created_at": "2026-01-17T09:20:00Z",
  "updated_at": "2026-01-17T09:20:00Z"
}

Audit Logging: Provider creation is automatically logged in audit_logs with action USER_CREATED and details including is_provider: true.

Field Details

Email

Uniqueness Constraint

Email must be unique globally (across all clinics). Two users cannot share the same email address.

Error Example:

{
  "detail": "Email already in use"
}

Solution: Use a different email or identify the existing user and flag them as a provider instead (Method 1).

Format Validation

Email must be a valid email address format.

Valid: [e-mail], [e-mail]

Invalid: maria.garcia, juan@, @namsec.es

Phone Number

E.164 Format Required

Phone numbers MUST be in E.164 format: +[country code][number]

Examples:

• Spain: [phone]
• US: [phone]
• Mexico: [phone]

Invalid: 612345678, [phone], [phone]

Global Uniqueness

Phone numbers must be unique globally (across all clinics), similar to email.

Error Example:

{
  "detail": "Phone number already in use"
}

Normalization

The system uses normalize_phone_to_e164() to convert various formats:

# Input: "612345678" (Spain, assuming +34 prefix)
# Output: "[phone]"

# Input: "[phone]"
# Output: "[phone]"

Best Practice: Always provide phone numbers in E.164 format to avoid parsing issues.

Full Name

Per-Clinic Storage

Full name is stored in user_clinic_profiles.full_name, meaning:

• The same user can have different names in different clinics
• Name is tied to the user_clinic relationship, not the global users table

Example:

• Clinic A: “Dr. María García Rodríguez”
• Clinic B: “María García” (same user, informal name)

Multi-Clinic Name Updates

When a patient exists in Clinic A as “Manuel López” and books in Clinic B as “Eduardo Cassanovas”, the system:

1. Associates the user to Clinic B (creates new user_clinic)
2. Updates the global name to “Eduardo Cassanovas” (respects most recent input)

See docs/FIX_MULTI_CLINIC_PATIENT_NAME_UPDATE.md for full details.

Clinic Role

STAFF

Standard team member with access to their clinic’s data.

CLINIC_ADMIN

Can manage clinic configuration, users, providers, and services.

ADMIN

System administrator with access to ALL clinics (global role).

Role Independence: A user can be CLINIC_ADMIN in Clinic A and STAFF in Clinic B. Roles are per-clinic, stored in user_clinics.clinic_role_id.

Status

approved

Active Provider: Can deliver services immediately. Availability slots are generated.

pending

Awaiting Approval: Provider is not yet active. No availability slots generated. Use for onboarding.

suspended

Temporarily Inactive: Provider is suspended (leave, disciplinary action). No availability slots.

Post-Creation Steps

After creating a provider, complete their setup:

1. Configure Work Hours

   Navigate to Configure Schedule to set the provider’s working hours.

   Without work hours: Provider will have NO availability (no slots generated).

2. Assign Services

   Navigate to Assign Services to link the provider to services they deliver.

   Without service assignments: Provider won’t appear when patients book specific services.

3. Verify Availability

   Test availability by simulating an appointment booking for a service assigned to this provider.

4. Notify Provider

   Send login credentials and onboarding information to the new provider.

Common Errors

403 Forbidden - Cannot Manage Clinic

Cause: You don’t have CLINIC_ADMIN role in the selected clinic.

Solution: Contact your system administrator to grant you CLINIC_ADMIN permissions for this clinic.

400 Bad Request - Email Already in Use

Cause: A user with this email already exists globally.

Solution:

1. Search for the existing user in the Users section
2. If they exist in your clinic, use Method 1 to flag them as a provider
3. If they exist in another clinic but not yours, add them to your clinic first (Create UserClinic association)

400 Bad Request - Phone Already in Use

Cause: A user with this phone number already exists globally.

Solution: Similar to email conflict. Locate the existing user and either flag them as a provider or verify the phone number is correct.

400 Bad Request - Invalid Phone Format

Cause: Phone number is not in E.164 format.

Solution: Reformat the phone number to E.164. Examples:

• Spain: +34 + 9-digit number
• US: +1 + 10-digit number
• Mexico: +52 + 10-digit number

Validation Logic

The system performs several validations when creating a provider:

# From app/api/v1/users.py (simplified)

# 1. Check email uniqueness (global)
existing_user = await db.scalar(select(User).where(User.email == email))
if existing_user:
    raise HTTPException(status_code=400, detail="Email already in use")

# 2. Check phone uniqueness (global)
existing_phone = await db.scalar(select(User).where(User.phone_e164 == phone))
if existing_phone:
    raise HTTPException(status_code=400, detail="Phone already in use")

# 3. Normalize phone to E.164
normalized_phone = normalize_phone_to_e164(phone_e164)
if not normalized_phone:
    raise HTTPException(status_code=400, detail="Invalid phone format")

# 4. Validate clinic access
if not current_user.can_manage_clinic(clinic_id):
    raise HTTPException(status_code=403, detail="Cannot manage this clinic")

# 5. Create user + user_clinic + user_clinic_profile
# ... (database operations)

Database Changes

Creating a provider modifies three tables:

1. users Table (Global Identity)

INSERT INTO users (id, email, phone_e164, password_hash, is_active)
VALUES (
  'user-012-abc-345',
  '[e-mail]',
  '[phone]',
  '<bcrypt_hash>',
  true
);

2. user_clinics Table (Clinic Association + Provider Flag)

INSERT INTO user_clinics (id, user_id, clinic_id, is_provider, clinic_role_id, status)
VALUES (
  'def-456-ghi-789',
  'user-012-abc-345',  -- FK to users
  'clinic-abc-123',
  true,  -- PROVIDER FLAG
  'role-staff-uuid',
  'approved'
);

3. user_clinic_profiles Table (Per-Clinic PII)

INSERT INTO user_clinic_profiles (user_clinic_id, full_name, notes, preferences)
VALUES (
  'def-456-ghi-789',  -- FK to user_clinics (PK = FK, 1:1 relationship)
  'Dr. Juan López',
  NULL,
  '{}'::jsonb
);

GDPR Compliance: PII (full_name, notes) is stored separately in user_clinic_profiles to enable GDPR-compliant deletion without losing access audit trail.

Next Steps

Configure Schedule

Set up the provider’s work hours (REQUIRED for availability)

Assign Services

Link the provider to services they deliver

View Providers

See the updated providers list with your new provider

Test Availability

Verify the provider appears in appointment booking