Providers V1 — Developer Guide

Returns a paginated list of providers filtered by the provided criteria.

⚠️ Rate Limited: This endpoint is rate limited. See the rate limiting guide for details.

✅ Recommended: Use lastId cursor pagination for large result sets (see below). Combine with lastModified filters to scope changes over time.

When filtering by lastModified, results are returned in descending order (newest first). Use lastId with date filters for stable cursor pagination.

Combine filters with commas, for example: filter=location.id==64000000000004,lastModified>2025-01-01T00:00:00.000Z.

Note: A very wide lastModified range with no other scoping can return 408 (timeout) on large tenants. Narrow your filter and retry.

Fetch providers modified since a date:

GET /api/v1/providers?filter=lastModified>=2025-01-01T00:00:00.000Z

Fetch providers at a specific location:

GET /api/v1/providers?filter=location.id==64000000000004

Fetch specific providers by ID:

GET /api/v1/providers?filter=id->[1000000020702,1000000020703]

lastId uses the provider's id as a cursor. Pass the largest id from the previous page as lastId for the next request.

When lastId is present, meta.pagination.total is not included in the response. Use GET /v1/providers/totalcount when you need a record count. See also Bulk GET — Total Count Behavior.

Send the first request without lastId:

GET /api/v1/providers?pageSize=500&filter=lastModified>2025-01-01T00:00:00.000Z

Use the id of the last object in the data array as lastId:

GET /api/v1/providers?lastId=1000000020703&pageSize=500&filter=lastModified>2025-01-01T00:00:00.000Z

Continue until data is empty or you have retrieved all records you need.

Returns the number of provider records matching a filter.

GET /api/v1/providers/totalcount

Uses the same filter syntax and filter keys as bulk GET. Only Organization-ID and filter apply — pagination query parameters are not used on this endpoint.

GET /api/v1/providers/totalcount?filter=lastModified>=2025-01-01T00:00:00.000Z,location.id==64000000000004

{
  "data": {
    "totalCount": 42
  },
  "warnings": [],
  "errors": []
}

Returns a single provider by its ID.

GET /api/v1/providers/1000000020702

A provider that does not exist in your organization returns 404 with ProviderV1 not found.

Creates a new provider. Returns 201 with the created resource in data.

All create requests require:

When isPrimaryProvider is true, or when specialty is not HYGIENIST, these fields are also required:

DENTALPUBLICHEALTH, DENTALSPECIALTY, DENTIST, DENTAL, ENDODONTICS, FEDERALLYQUALIFIEDHEALTHCENTER, GENERALPRACTICE, HYGIENIST, MULTISPECIALTY, ORTHODONTICS, ORALMAXILLOFACIALPATHOLOGY, ORALMAXILLOFACIALRADIOLOGY, ORALMAXILLOFACIALSURGERY, PEDIATRICDENTISTRY, PERIODONTICS, PROSTHODONTICS, SINGLESPECIALTY

{
  "firstName": "John",
  "lastName": "Doe",
  "shortName": "JD-DDS",
  "specialty": "DENTIST",
  "isPrimaryProvider": true,
  "npi": "1234567893",
  "stateId": "DDS-12345",
  "tin": "123456789",
  "color": "ffffff",
  "address1": "123 Main St",
  "address2": "Suite 100",
  "city": "Salt Lake City",
  "state": "UT",
  "postalCode": "84103"
}

{
  "firstName": "Jane",
  "lastName": "Smith",
  "shortName": "J-HYG",
  "specialty": "HYGIENIST",
  "isPrimaryProvider": false,
  "color": "ffffff",
  "address1": "123 Main St",
  "city": "Salt Lake City",
  "state": "UT",
  "postalCode": "84103"
}

{
  "firstName": "John",
  "lastName": "Doe",
  "shortName": "JD-DDS",
  "specialty": "DENTIST",
  "isPrimaryProvider": true,
  "npi": "1234567893",
  "stateId": "DDS-12345",
  "tin": "123456789",
  "address1": "123 Main St",
  "city": "Salt Lake City",
  "state": "UT",
  "postalCode": "84103",
  "user": {
    "id": 12000006542062
  }
}

Updates an existing provider. Only fields included in the request body are changed; omitted fields remain unchanged.

Returns 200 with the updated resource. By default, the response includes only modified fields (responseFields=MODIFIED). Use ?responseFields=ALL when you need the full resource after update.

PUT /api/v1/providers/1000000020702?responseFields=ALL

{
  "user": {
    "id": 12000006542062
  }
}

{
  "address1": "456 Oak Ave",
  "address2": null,
  "city": "Provo",
  "state": "UT",
  "postalCode": "84604"
}

{
  "insuranceCarriers": [
    { "id": 1000000020702 },
    { "id": 1000000020703 }
  ]
}

{
  "signatureOnFile": true
}

The request body or parameters are invalid. See field-level errors below.

Error: firstName must be longer than or equal to 1 characters (or same for lastName).

Error: specialty must have a value in [...]

Error: You cannot make provider primary without setting his npi (and similar for stateId, tin).

Error: You cannot make provider non-HYGIENIST without setting his npi (and similar for stateId, tin).

Error: Linked model for property 'user' should be plain object with id of UserV1

Error: Linked model with id '<id>' of type 'UserV1' not found

Error: userId <id> is incorrect. This user is already assigned to another provider

Error: You cannot change user for provider

Error: You cannot unassign user from provider for now, please contact support in case of need

Error: Linked model for property 'feeSchedule' should be plain object with id of FeeScheduleV1

Error: You cannot deactivate a provider for now, please contact support in case of need

Error: You cannot set isPrimaryProvider to false because he has patients

Error: Provider is assigned to location. Field <fieldName> is readonly

Error: insuranceCarriers must be an array

Error: Each element in array should be an object and contain 'id' key...

Error: Linked models with ids [...] of type 'InsuranceCarrierV1' not found

Error: Validation errors when required address fields are nulled or emptied.

Error: Invalid hex color value.

Warning: Property 'location' is read-only. Assignment is ignored.

Warning: Property 'isNonPersonEntity' is read-only. Assignment is ignored.