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:

To manage Providers:

To manage Provider Account Contacts:

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/organizations/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}/providers

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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.