Authentication

Two header-based authentication methods are required:

Header	Type	In	Description
x-api-key	token	header	API key credential
x-client-id	token	header	Client identifier credential

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination. Default 1. Range: 1 ≤ value ≤ 100.
perPage	integer	No	Number of items per page. Default 10. Range: 1 ≤ value ≤ 100.
externalId	string	No	Filter results by the foreign key identifier from the customer's system. Length: 1 ≤ length ≤ 100.
orderBy	string	No	Sort results by a single field and direction. Format: field:ASC or field:DESC (direction defaults to ASC if omitted). Valid fields: id, externalId, name.first, name.middle, name.last, name.full, email, dob, npi. name.full is present on every professional (derived for individuals, provided for companies) and sorts the whole mixed list alphabetically — it starts with the first name for individuals. Sorting by a name part groups full-name-only professionals together as empty values. Match: ^(id\|externalId\|name.first\|name.middle\|name.last\|name.full\|email\|dob\|npi)(:(ASC\|DESC))?$

Example Request — cURL

curl -X GET "https://api.propelus.com/v2/professionals?orderBy=name.last%3ADESC" \
  -H "x-api-key: <your-api-key>" \
  -H "x-client-id: <your-client-id>"

Example Request — JavaScript

fetch("https://api.propelus.com/v2/professionals?orderBy=name.last%3ADESC", {
  method: "GET",
  headers: {
    "x-api-key": "<your-api-key>",
    "x-client-id": "<your-client-id>"
  }
})

Responses

200 — Success

Returns a paginated list of professionals with full demographic detail; count is the number on the current page, total the total across all pages, with nextPage / prevPage links.

{
  "count": 0,
  "total": 0,
  "professionals": [
    {
      "id": "628fc8e2-ee7e-4779-9eb7-d980e7a92f3a",
      "externalId": "T-100",
      "dob": "19770428",
      "ssn": "000482915",
      "npi": "1739204857",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "st",
        "zip": "strin"
      },
      "email": "user@example.com",
      "customProperties": {
        "property1": "string",
        "property2": "string"
      },
      "name": {
        "prefix": "Dr.",
        "first": "string",
        "middle": "string",
        "last": "string",
        "suffix": "string",
        "full": "Jane A Smith"
      },
      "alias": {
        "prefix": "Dr.",
        "first": "string",
        "middle": "string",
        "last": "string",
        "suffix": "string",
        "full": "Jane A Smith"
      }
    }
  ],
  "nextPage": "/v2/professionals?page=3&perPage=10",
  "prevPage": "/v2/professionals?page=1&perPage=10"
}

Error Responses

Standardized error bodies. Validation-style errors include an errors array; each item contains detail, pointer, parameter, header, and code.

400 — Bad Request

{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}

401 — Unauthorized

{
  "status": 400,
  "code": "missing_fields",
  "detail": "string",
  "errors": [
    {
      "detail": "string",
      "pointer": "string",
      "parameter": "string",
      "header": "string",
      "code": "string"
    }
  ]
}

429 — Rate Limited

{
  "status": 429,
  "detail": "string",
  "code": "f5d62b05-370e-48be-a755-8675ca146431"
}

5XX — Server Error

{
  "status": 500,
  "detail": "string",
  "code": "unexpected_error"
}