Skip to main content

Step 1: Manage Professionals

Updated

The article explains managing professional records in Propelus using CRUD operations via API endpoints: List, Create, Read, Update, and Delete. Key fields include externalId (your system's ID) and professional_id (Propelus' ID). Creating a professional requires externalId, firstName, and lastName, with optional details enhancing monitoring accuracy. Deleting a professional stops monitoring and should be done only when monitoring is no longer needed.

 

The five operations

Operation Method & endpoint What it does
List GET /v1/professionals List every professional in your organization.
Create POST /v1/professionals Add a new professional.
Read GET /v1/professionals/{professionalId} Fetch one professional’s details.
Update PATCH /v1/professionals/{professionalId} Modify an existing professional.
Delete DELETE /v1/professionals/{professionalId} Remove a professional.
Two IDs, don’t mix them up
externalId is yours — the ID your system uses for this person. 
professionalId is Propelus’ auto-generated ID, returned when you create the record. 
You read, update, and delete using professionalId.
 

Create a professional

Only three fields are required — externalId, firstName, and lastName. Everything else is optional, but the more identity and identifier detail you provide, the more precisely monitoring can match this person to real records.

Name

Field Required What it is
firstName Required First name (≤ 200 chars).
lastName Required Last name (≤ 200 chars).
middleName Optional Middle name (≤ 200 chars).
namePrefix Optional Honorific before the name, e.g. Dr. (≤ 50).
nameSuffix Optional Suffix, e.g. Jr., Ph.D. (≤ 50).
alternateNamePrefix Optional Alias prefix.
alternateFirstName Optional Alias / alternate first name.
alternativeMiddleName Optional Alias / alternate middle name.
alternateLastName Optional Alias / alternate last name.
alternateNameSuffix Optional Alias / alternate suffix.

Identifiers

Field Required What it is
externalId Required Your own unique ID for this professional within your organization.
dob Optional Date of birth, YYYYMMDD — or YYYYMM for a partial date.
ssn Optional Social Security Number, exactly 9 digits.
npi Optional National Provider Identifier, 10 digits.
uei Optional Unique Entity Identifier, 12 characters.
dunsNumber Optional Data Universal Numbering System number (≤ 9).

Address & contact

Field What it is
addressLine1 / addressLine2 Street address, e.g. “123 Main St.” / “Apt. B”.
addressCity City (≤ 100).
addressState Two-letter state abbreviation, e.g. FL.
addressZip 5-digit ZIP code.
email / alternateEmail Email addresses (≤ 500 each).
customProperties A JSON object for any data you want to keep with the record — echoed back whenever this professional’s details are returned. Ideal for legacy or alternate IDs.
For your technical team
POST https://api.propelus.com/v1/professionals
{
  "externalId": "HR-4471",
  "namePrefix": "Dr.",
  "firstName": "John",
  "middleName": "Mycroft",
  "lastName": "Doe",
  "nameSuffix": "Ph.D.",
  "dob": "19741009",
  "npi": "1234567890",
  "addressState": "FL",
  "email": "john.doe@example.com",
  "customProperties": { "legacyHRID": "1234567" }
}
→ 201 Created — returns the record, including the Propelus professionalId.
 

List, Read, Update & Delete

Listing returns every professional in your organization — each as a full record including the id Propelus assigned, plus a size count. Narrow it with the optional filter query parameter (e.g. ?filter=externalId:<value>). For one professional, use their professionalId in the path. Update is a PATCH — send only the fields you’re changing.

GET         /v1/professionals?filter=externalId:<value> → 200, items[] + size
GET         /v1/professionals/{professionalId} → 200, full details
PATCH    /v1/professionals/{professionalId} → 200, send changed fields only
DELETE  /v1/professionals/{professionalId} → 200, removes the record
 
(!) DELETE stops monitoring
Removing a professional also tears down any monitoring attached to them. 
Delete only when you no longer need that person watched.
 

Where to go next

With your professionals in place, continue to Step 2: manage licenses — attaching the credentials you want watched.