Skip to main content

​
Upgrading a User to Prescriber

A common scenario is creating a user with basic access and later upgrading them to have prescriber capabilities. This workflow shows how to transform an rx_reader into a provider with full prescriber details.
1

Create User with Basic Access

Start by creating a user with the rx_reader role for basic prescription reading access.
POST /v1/organizations/{organizationId}/users
{
  "given_name": "Ben",
  "family_name": "Smith",
  "email": "user-email@my-practice.com",
  "access_roles": ["rx_reader"]
}
The rx_reader role allows users to view and read prescriptions but not create them.
2

Update User Roles

Upgrade the user’s access level by changing their role to provider.
PUT /v1/organizations/{organizationId}/users/{userId}/roles
{
  "access_roles": ["provider"]
}
Adding a provider role, then switching to non-provider role and then switching back to provider role may cause issues due to dependencies on downstream third party services
3

Add Provider Details

Complete the provider setup by adding professional details and prescriber information.
PUT /v1/organizations/{organizationId}/users/{userId}
{
  "provider_details": {
    "given_name": "Ben",
    "family_name": "Smith",
    "date_of_birth": "1975-12-25",
    "sex": "M",
    "phone": "0432333333",
    "hpii_number": "8003614900000000",
    "prescriber_type": "M",
    "prescriber_number": "1234567",
    "qualifications": "MD"
  }
}
Required Provider Fields:
  • hpii_number: Healthcare Provider Identifier Individual number
  • prescriber_type: Prescriber type (M/N/D/P/T)
  • prescriber_number: Unique prescriber identification number
  • qualifications: Professional qualifications (MD, RN, etc.)

​
Other Common Workflows

​
Creating a Provider from Scratch

If you know the user will be a provider from the beginning: 
POST /v1/organizations/{organizationId}/users
{
  "given_name": "Sarah",
  "family_name": "Johnson",
  "email": "sarah.johnson@clinic.com",
  "access_roles": ["provider"],
  "date_of_birth": "1980-03-15",
  "sex": "F",
  "phone": "0455666777",
  "hpii_number": "8003614900000001",
  "prescriber_type": "M",
  "prescriber_number": "2345678",
  "qualifications": "MBBS"
}

​
Downgrading Provider Access

To remove provider privileges while keeping basic access: 
PUT /v1/organizations/{organizationId}/users/{userId}/roles
{
  "access_roles": ["rx_reader"]
}
Provider details are retained when downgrading roles and can be reactivated by upgrading the role back to provider.

​
Disabling a User

To permanently disable a user’s access to the platform: 
PUT /v1/organizations/{organizationId}/users/{userId}/disable
This is a destructive action. Disabling a user will:
  • Mark the user as disabled in the database
  • Downgrade all roles to member
  • Disable their Cognito authentication account
This action cannot be reversed via the API.
No request body is required. The endpoint is idempotent — disabling an already-disabled user returns a 200 response.

​
Best Practices

Validation

Always validate HPII and prescriber numbers before creating provider accounts

Role Management

Start with minimal permissions and upgrade as needed for security

Data Consistency

Ensure provider details match official registration records

Audit Trail

Role changes are logged for compliance and audit purposes