Provider Account APIs
You can manage Provider Accounts (sometimes called "practices"), Providers (often, but not always, physicians) and Provider Account Contacts through the following APIs.
To manage Provider Accounts:
- Create a Provider Account
- Update a Provider Account
- Delete a Provider Account
- Get Provider Accounts
- Get a Provider Account
To manage Providers:
To manage Provider Account Contacts:
- Create a Provider Account Contact
- Update a Provider Account Contact
- Delete a Provider Account Contact
- Get Provider Account Contacts
- Get a Provider Account Contact
Create a Provider Account
Use this endpoint to create a new provider account.
HTTP Request
POST /v3/organizations/{organizationID}/provider_accounts
Query Parameters
| Key | Required | Description |
|---|---|---|
organizationID |
yes | Internal organization identifier. Copy from URLs. (It's the 123 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts.) |
Request Body
{
"providerAccount": {
"name": "Practice 1",
"externalIdentifier": "5446",
"accountNumber": 55578,
...
}
}
| Field name | Required | Description |
name |
yes | The provider account's name |
externalIdentifier |
no | A reference to the provider account's identifier in an external system When this invisible value is set, the provider account cannot be modified in the UI in order to support the case where the provider account is being maintained in an external system. |
accountNumber |
no | The provider account's account number |
websiteUrl |
no | The provider account's web site address |
phoneNumber |
no | The provider account's primary phone number |
streetAddress |
no | The street address of the provider account Note that you cannot set the second line of the street address through the API. |
streetAddressCity |
no | The provider account's city |
streetAddressState |
no | The provider account's state (or region/province in the case of a non-U.S. address) |
streetAddressZipCode |
no | The provider account's zip code (or postal code) |
streetAddressCountry |
no | The provider account's country |
mailingAddress |
no | The mailing address of the provider account |
mailingAddressCity |
no | See above |
mailingAddressState |
no | See above |
mailingAddressZipCode |
no | See above |
mailingAddressCountry |
no | See above |
faxSignedReports |
no | Whether to fax signed reports |
faxNumber |
no | The number to fax to This must be 11 digits with no punctuation. |
salesReps |
no | An array of JSON objects that contain the internal identifiers of the sales reps to link to the provider account. Get the internal IDs from the URL. (It's the 456 from this: https://lab.ovation.io/orgs/123/administration/sales-reps/456.) "salesReps": [
{"id": 111},
{"id": 222},
...
]
|
Response
| Response code | Response body |
| 201 to indicate that the provider account endpoint was successfully created | JSON describing the created provider account |
| 401 to indicate an authentication error | |
| 422 to indicate an error with the request contents | The validation errors found |
Update a Provider Account
Use this endpoint to update an existing provider account.
HTTP Request
PUT /v3/organizations/{organizationID}/provider_accounts/{providerAccountID}
Query Parameters
| Key | Required | Description |
|---|---|---|
organizationID |
yes | Internal organization identifier. Copy from URLs. (It's the 123 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts.) |
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
Request Body
Use the same payload as defined above for creating provider accounts.
Response
| Response code | Response body |
| 200 to indicate that the provider account endpoint was successfully created | JSON describing the updated provider account |
| 401 to indicate an authentication error | |
| 422 to indicate an error with the request contents | The validation errors found |
Delete a Provider Account
Use this endpoint to delete a provider account.
HTTP Request
DELETE /v3/organizations/{organizationID}/provider_accounts/{providerAccountID}
Query Parameters
| Key | Required | Description |
|---|---|---|
organizationID |
yes | Internal organization identifier. Copy from URLs. (It's the 123 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts.) |
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
Response
| Response code | Response body |
| 200 to indicate that the provider account endpoint was successfully deleted | |
| 401 to indicate an authentication error |
Get Provider Accounts
Use this endpoint to get limited details for a selected set of provider accounts.
HTTP Request
GET /v3/organizations/{organizationID}/provider_accounts
Query Parameters
| Key | Required | Description |
|---|---|---|
organizationID |
yes | Internal organization identifier. Copy from URLs. (It's the 123 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts.) |
page |
no | Page number being requested Defaults to page 1 if not supplied |
perPage |
no | Number of provider accounts to return per page Maximum of 5000 and defaults to 5000 if not supplied |
name |
no | Name to filter by |
accountNumber |
no | Account Number to filter by |
externalIdentifier |
no | External Identifier to filter by |
Response
| Response code | Response body |
| 200 to indicate success | JSON describing the requested provider accounts |
| 401 to indicate an authentication error |
Get a Provider Account
HTTP Request
GET /v3/organizations/{organizationID}/provider_accounts/{providerAccountID}
Query Params
| Key | Required | Description |
|---|---|---|
organizationID |
yes | Internal organization identifier. Copy from URLs. (It's the 123 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts.) |
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
Response
This endpoint can return the following responses:
| Response code | Response body |
| 200 to indicate success | JSON describing the requested provider account |
| 401 to indicate an authentication error |
Add a Provider
Use this endpoint to associate a provider with a provider account.
HTTP Request
POST /v3/provider_accounts/{providerAccountID}/providers
Query Parameters
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
Request Body
{
"provider": {
"licensingRegistry": "NPI",
"registryIdentifier": "9999999999"
}
}
| Field name | Required | Description |
licensingRegistry |
no | Any of these accepted values: ‘NPI’, 'Australian Health Practitioner Registry', 'European Physician', 'ex-US / clinical trial', 'Philippines PRC', 'South American Physician' defaults to NPI (which is the NPPES registry) |
registryIdentifier |
yes | NPI number when the registry is NPI (NPPES); any appropriate identifier for all other registries |
name |
no | The name of the provider This value is ignored when the registry is NPI (NPPES) |
Response
| Response code | Response body |
| 201 to indicate that the provider was successfully added | JSON describing the created provider |
| 401 to indicate an authentication error | |
| 422 to indicate an error with the request contents | The validation errors found |
Remove a Provider
Use this endpoint to remove the association between a provider and a provider account.
HTTP Request
DELETE /v3/provider_accounts/{providerAccountID}/providers/{providerID}
Query Parameters
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
providerID |
yes | Internal provider account identifier. Copy from URLs. (It's the 789 in this example: https://lab-staging.ovation.io/orgs/123/administration/accounts/provider-accounts/456/providers/789.) |
Response
| Response code | Response body |
| 200 to indicate that the provider association was successfully removed | |
| 401 to indicate an authentication error |
Get Providers
Use this endpoint to get a selected set of providers that are associated with a specified provider account.
HTTP Request
GET /v3/provider_accounts/{providerAccountID}/providers
Query Parameters
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
page |
no | Page number being requested Defaults to page 1 if not supplied |
perPage |
no | Number of providers to return per page Maximum of 5000 and defaults to 5000 if not supplied |
licenseRegistry |
no | License Registry to filter by |
registryIdentifier |
no | Registry Identifier to filter by |
providerName |
no | Name to filter by |
Response
| Response code | Response body |
| 200 to indicate success | JSON describing the requested providers. For example {
"providers": [
{
"id": 123,
"name": "Some provider name",
"registryIdentifier": "123456789",
"providerAccountId": 456,
"licensingRegistry": "NPI"
},
{
"id": 234,
"name": "Another provider name",
"registryIdentifier": "987654321",
"providerAccountId": 456,
"licensingRegistry": "European Physician"
}
...
]
}<br>
|
| 401 to indicate an authentication error | |
Create a Provider Account Contact
Use this endpoint to create a provider account contact.
HTTP Request
POST /v3/provider_accounts/{providerAccountID}/provider_account_contacts
Query Parameters
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
Payload
{
"providerAccountContact": {
"externalIdentifier": null,
"firstName": "TestName",
"lastName": "LastName",
...
}
}
| Field name | Required | Description | |
externalIdentifier |
no | A reference to the provider account contact's identifier in an external system When this invisible value is set, the provider account contact cannot be modified in the UI in order to support the case where the provider account contact is being maintained in an external system. |
|
firstName |
no | Contact first name | |
lastName |
yes | Contact last name | |
email |
yes | Contact email | |
officePhoneNumber |
no | Contact office phone number Required if communicationPreference is "Office" |
|
cellPhoneNumber |
no | Contact phone number Required if communicationPreference is "Text" or "Cell" |
|
providerAccountIds |
no | Provider account IDs associated to contact Must be an array |
|
faxNumber |
no | Contact fax number | |
communicationPreference |
yes | Contact communication preference "Cell", "Email", "Office", "Text" |
|
primaryContact |
no | |
|
userId |
no | Ovation user ID associated to contact | |
faxSignedReports |
no | Fax signed reports from contact | |
emailReportReadyNotifications |
no | Notify contact's reports in ready status | |
role |
no | Provider Account Contact record "provider", "provider delegate" |
|
| associatedProviders | no | An array of JSON objects that contain the internal IDs of the providers to link to the provider account. Get the internal IDs from the URL. (It's the 789 from this: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts456/providers/789.) "associatedProviders": [
{"providerId": 111},
{"providerId": 222},
...
]
|
Response
| Response code | Response body |
| 201 to indicate that the provider account endpoint was successfully created | JSON describing the created provider |
| 401 to indicate an authentication error | |
| 422 to indicate an error with the request contents | The validation errors found |
Update a Provider Account Contact
Use this endpoint to update a provider account contact.
HTTP Request
PUT /v3/provider_accounts/{providerAccountID}/provider_account_contacts/{providerAccountContactID}
Query Params
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
providerAccountContactID |
yes | Internal provider account identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/administration/accounts/contacts/789?provider_account_id=456.) |
Payload
Use the same payload as defined above for creating provider account contacts.
Response
| Response code | Response body |
| 200 to indicate that the provider account contact was successfully updated | |
| 401 to indicate an authentication error |
Delete a Provider Account Contact
Use this endpoint to delete a provider account contact.
HTTP Request
DELETE /v3/provider_accounts/{providerAccountID}/provider_account_contacts/{providerAccountContactID}
Query Params
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
providerAccountContactID |
yes | Internal provider account identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/administration/accounts/contacts/789?provider_account_id=456.) |
Response
| Response code | Response body |
| 200 to indicate that the provider account contact was successfully deleted | |
| 401 to indicate an authentication error |
Get Provider Account Contacts
Use this endpoint to get limited details for a set of provider account contacts for a specified provider account.
HTTP Request
GET /v3/organizations/provider_accounts/{providerAccountID}/provider_account_contacts
Query Params
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
page |
no | Page number being requested Defaults to page 1 if not supplied |
perPage |
no | Number of providers to return per page Maximum of 5000 and defaults to 5000 if not supplied |
licenseRegistry |
no | License Registry to filter by |
registryIdentifier |
no | Registry Identifier to filter by |
providerName |
no | Name to filter by |
Response
| Response code | Response body |
| 200 to indicate success | JSON describing the requested provider account contacts |
| 401 to indicate an authentication error | |
Get a Provider Account Contact
Use this endpoint to get details for a single provider account contact.
HTTP Request
GET /v3/provider_accounts/{providerAccountID}/provider_account_contacts/{providerAccountContactID}
Query Params
| Key | Required | Description |
|---|---|---|
providerAccountID |
yes | Internal provider account identifier. Copy from URLs. (It's the 456 in this example: https://lab.ovation.io/orgs/123/administration/accounts/provider-accounts/456.) |
providerAccountContactID |
yes | Internal provider account identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/administration/accounts/contacts/789?provider_account_id=456.) |
Response
| Response code | Response body |
| 200 to indicate success | JSON describing the requested provider account contact |
| 401 to indicate an authentication error | |