Skip to content

Verifiable API Documentation (26.2.0.4306)

Introduction

This document contains the official documentation for the latest version of the Verifiable API. Our solution has been built API-first. That means we first design our API's and build our own user interfaces on top of these API's afterwards. This results in a reusable API that can be used by 3rd parties to offer the exact same functionality as we can provide ourselves. Both the product and API are still subject to significant and potentially breaking changes, so please refer back to this documentation frequently. Any breaking change will be communicated ahead of time to our partners integrating with our API's.

Getting Started

This is a RESTful API that can be accessed using convential HTTP methods. It doesn't matter what programming language you use, there is already tooling available that can jumpstart you to access our API's. This documentation is based on OpenAPI 3.0 specifications and as such it is possible to dynamically generate a client in a language of your choice by simply loading our specification document in a tool such as Swagger Codegen. It is not necessary to generate such a client and it is also possible to simply use any HTTP client to access our API. You can refer to the reference below to find the correct HTTP method, endpoint and model to use.

Environments

When developing an integration with our API we typicially request you to use our staging environment for development and only start using production when your integration is stable and tested thoroughly. Please contact Verifiable support to be granted access to our environments.

Staging Base URL

https://api.discovery-staging.verifiable.com/

Production Base URL

https://api.discovery.verifiable.com/

Authentication

Most endpoints require authentication to be used. You can authenticate to the API by passing an access token in the Authentication header using the Bearer scheme. An access token can be requested by authenticating against one of the Authentication endpoints.

Example using password authentication endpoint

Request:

POST /auth/token/password HTTP/1.1
Content-Type: application/json
Host: https://<SERVER>
{
    "email": "john.doe@mail.com",
    "password": "secret"
}

Response:

HTTP/1.1 200 OK
Date: Fri, 25 Sep 2020 12:59:56 GMT
Content-Type: application/json; charset=utf-8
{
    "tokenId": "2e5db76c-4c48-4cce-b11f-23a57ac5824c",
    "token": "MtetyFcIW...xgXXX-Z4yy"
}

Example using access token

Request

GET /log/events HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Host: https://<SERVER>

An access token is bound to a single user in an organization. The access token should remain secret and be treated as if it were a password. We recommend you to create access tokens with a short time to live and frequently rotate them. Note that time to live requested might be lowered to a shorter duration based on your organization settings. These can be configured to enforce a suitable maximum time to live for your use-cases that facilitate users and service integrations.

Create a new provider

A provider must be created and associated with license numbers, NPI numbers or other identifiers that can be used to perform lookups to fetch associated data for this provider.

Example creating a new provider

To create a new provider that can be used for license lookups:

Request:

POST /providers HTTP/1.1
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Host: https://<SERVER>
{
    "firstName": "John",
    "lastName": "Doe"
}

Response:

HTTP/1.1 201 Created
Date: Fri, 25 Sep 2020 15:25:12 GMT
Content-Type: application/json; charset=utf-8
Location: https://<SERVER>/providers/9706f2ea-9c1d-49f3-9a57-871159878c9c
{
    "firstName": "John",
    "lastName": "Doe",
    "id": "9706f2ea-9c1d-49f3-9a57-871159878c9c",
    "licenses": []
}

Note: The id in the response is the Provider id. It can be used as a Path Parameter to attach licenses to this provider, using Attach License API. You will need to pass in a licenseTypeId, which can be obtained from the List Simplified License Types API. For more details on providers see Provider endpoints

Get license types

The list of license types which are supported for license verification.

Example get license types

Returns a list of all license types that are currently supported and used for license verifications.

Request

GET /licensetypes HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Host: https://<SERVER>

Response:

HTTP/1.1 200 OK
Date: Fri, 25 Sep 2020 15:32:47 GMT
Content-Type: application/json; charset=utf-8
{
    "nextOffset": "100",
    "nextCursor": "100",
    "pageSize": 100,
    "items": [
        {
            "id": "0059f76a-280a-377a-73e2-ddfe86f4113c",
            "name": "Medical Physician & Surgeon",
            "source": {
                "id": "72dcec62-a0d3-4af8-955d-07ecac8f1e4d",
                "name": "Missouri Division of ProfessionalRegistration",
                "state": "MO",
                "availability": "Available",
                "isDegraded": false,
                "url": "https://pr.mo.gov/licensee-search.asp"
            }
        },
    ],
    "sortedBy": "Id",
    "sortDirection": "Asc"
}

Note: id in response refers to licenseTypeId. It will be unique for each license type. Please see List Simplified License Types for more details.

Attach a license to a provider

To perform a license verification you must attach a license to a provider. The first time you do this will automatically trigger a license verification on that provider. Once attached you can re-verify the same license without reattaching it. A provider can have more than one license attached.

Example attach license to a provider

Request:

POST /providers/{providerId}/licenses HTTP/1.1
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Host: https://<SERVER>
{
    "licenseNumber": "123456",
    "licenseTypeId": "0059f76a-280a-377a-73e2-ddfe86f4113c"
}

Response:

HTTP/1.1 201 Created
Date: Fri, 25 Sep 2020 15:35:00 GMT
Content-Type: application/json; charset=utf-8
Location: https://<SERVER>/providers/9706f2ea-9c1d-49f3-9a57-871159878c9c?licenseId=bfb028f0-52ca-47f4-8181-6b4c8262d29c
{
    "providerId": "9706f2ea-9c1d-49f3-9a57-871159878c9c",
    "licenseNumber": "123456",
    "licenseType": {
        "id": "0059f76a-280a-377a-73e2-ddfe86f4113c",
        "name": "Registered Nurse - RN",
        "source": {
            "id": "679b4f9a-cc3c-49e8-b560-0d0a9af47fd3”,
            "name": "Missouri Division of ProfessionalRegistration",
            "state": "MO",
            "availability": "Available",
            "url": "https://pr.mo.gov/licensee-search.asp"
        }
    }
    "jobStatus": "Pending",
    "id": "b45cbeb0-873e-495b-8182-1b9a8b6d379d"
}

Note: Register a Webhook to get notified on HTTP endpoint, this prevents the need to poll the API for completion checks. For more details on Webhooks please see Webhooks endpoint and for details on attaching a license see Attach License endpoint.

Fetch created provider

Returns the data for a specific provider.

Example to fetch created provider

Request

GET /providers/{providerId} HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Host: https://<SERVER>

Response:

HTTP/1.1 200 OK
Date: Fri, 25 Sep 2020 15:36:30 GMT
Content-Type: application/json; charset=utf-8
{
    "firstName": "John",
    "lastName": "Doe",
    "id": "9706f2ea-9c1d-49f3-9a57-871159878c9c",
    "npis": [],
    "licenses": [
        {
            "providerId": "9706f2ea-9c1d-49f3-9a57-871159878c9c",
            "licenseNumber": "123456",
            "licenseType": {
                "id": "0059f76a-280a-377a-73e2-ddfe86f4113c",
                "name": "Registered Nurse - RN",
                "source": {
                    "id": "679b4f9a-cc3c-49e8-b560-0d0a9af47fd3”,
                    "name": "Missouri Division of ProfessionalRegistration",
                    "state": "MO",
                    "availability": "Available",
                    "url": "https://pr.mo.gov/licensee-search.asp"
                }
            }
            "jobStatus": "Idle",
            "currentVerificationStatus": "NeedsReview",
            "id": "b45cbeb0-873e-495b-8182-1b9a8b6d379d"
        }
    ]
}

Note: Response contains attached licenses, NPI details for the given provider. To get details of these individual items (a particular License or an NPI), use unique identifiers in each of these categories. For more details check Get specific license endpoint or Get specific NPI record. Further details on providers are at Providers endpoint.

Common Concepts

Pagination, filtering and sorting

Some endpoints can return a large list of data. To allow you to efficiently iterate through this data these endpoints offer pagination, sorting and filtering. The concept will be similar for each endpoint that supports it:

  • Pagination, filtering and sorting parameters are provided through the query string.
  • Pagination, filtering and sorting is only supported for endpoints that return lists of data.
  • Filters is only supported for certain endpoints. You can refer to the documentation of the endpoint to find out if filtering is supported.
  • The sortedBy and sortDirection parameters can be used to specify the sorting method.
  • The count parameter can be used to specify the page size. Please note that the maximum and default page size can differ per endpoint.
  • (Deprecated) The offset parameter influences the start of the page. For the first page you can always omit this parameter. For any subsequent page you can supply the value from the nextOffset parameter as returned by the server.
  • The cursor parameter influences the start of the page. For the first page you can always omit this parameter. For any subsequent page you can supply the value from the nextCursor or previousCursor parameter as returned by the server.

Example on how to make a paginated request:

GET /log/events?sortDirection=Asc&sortedBy=Timestamp&count=10 HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Host: https://<SERVER>

In addition to returning a list of items, a paginated response will also return nextCursor and/or previousCursor. The value of this property can be used to fetch the next or previous page by passing it in the cursor parameter.

Error handling

All responses that do not indicate a success status code will return an error using the error model as specified by RFC 7807. The amount of details exposed by the error model varies and depends on the nature of the error. We attempt to include as much information as is necessary to be able to self-diagnose the problem that led to the error. Should this information not be enough, then we also supply a correlationId in the response. We kindly request you to make note of this value when contacting Verifiable support as this will help us to quickly locate more information on this error.

Example error result on a malformed request:

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "correlationId": "5e94110e-45a8-404c-831d-77eaeaa73ad6",
    "errors": {
        "$.firstName": [
            "The JSON value could not be converted to System.String. Path: $.firstName | LineNumber: 1 | BytePositionInLine: 18."
        ]
    }
}

Nullable properties

If an input parameter is required it is marked as such. If an input parameter is not marked as required and you do not wish or need to use it, you should omit the parameter completely in the request.

For response parameters you should always code defensively and assume that a parameter might be missing from the response. This could happen in case the parameter is not applicable (yet) or simply because the data is missing. By coding defensively and assuming that a parameter might be missing you also future proof your solution for potential future (otherwise) breaking changes.

Flexible data model

In some cases we collect data from external sources that are hard to fit in a single predefined schema. For these cases we have come up with a flexible data model that allows us to store structured data in 3 different ways:

  • Form
  • Table
  • Section

Table

Data that can be represented in a table structure. The keys of every element/object in the data array is expected to be the same.

{
   "type": "Table",
   "data": [
      {
         "Status Code": "CB",
         "Effective Date": "06/10/2016",
         "Description": "CANCELLED BY BOARD"
      },
      {
         "Status Code": "NA",
         "Effective Date": "06/10/2016",
         "Description": "NOT ACTIVE"
      }
   ]
}

Section

Sections are used to represent multiple different data representations. For example, additional properties can have three sections with section one being a Form, while the other two could be a table. Also note there could be sections with and without heading.

With section heading

{
   "type": "Section",
   "data": {
      "Discipline": {
         "type": "Form",
         "data": {
            "Discipline/Final Orders state": "ILLINOIS",
            "Date action was taken": "02/03/2020",
            "Against privilege to practice (PTP)": "N/A"
         }
      },
      "NPDB code": {
         "type": "Form",
         "data": {
            "NPDB code": "39 - LICENSE REVOCATION, SUSPENSION OR OTHER DISCIPLINARY ACTION TAKEN BY A FEDERAL, STATE OR LOCAL LICENSING AUTHORITY"
         }
      },
      "Actions": {
         "type": "Form",
         "data": {
            "Initial action date": "02/03/2020",
            "Effective date(s)": "02/03/2020 - INDEFINITE/UNSPECIFIED",
            "Is license automatically reinstated after the effective date(s)": "NOT SUPPLIED",
            "NPDB code": "1148 - DENIAL OF LICENSE RENEWAL"
         }
      }
   }
}

Without section heading

{
   "type": "Section",
   "data": [
      {
         "type": "Form",
         "data": {
            "Discipline/Final Orders state": "ILLINOIS",
            "Date action was taken": "02/03/2020",
            "Against privilege to practice (PTP)": "N/A"
         }
      },
      {
         "type": "Form",
         "data": {
            "NPDB code": "39 - LICENSE REVOCATION, SUSPENSION OR OTHER DISCIPLINARY ACTION TAKEN BY A FEDERAL, STATE OR LOCAL LICENSING AUTHORITY"
         }
      },
      {
         "type": "Form",
         "data": {
            "Initial action date": "02/03/2020",
            "Effective date(s)": "02/03/2020 - INDEFINITE/UNSPECIFIED",
            "Is license automatically reinstated after the effective date(s)": "NOT SUPPLIED",
            "NPDB code": "1148 - DENIAL OF LICENSE RENEWAL"
         }
      }
   ]
}

Form

A form is essentially a simple key/value collection, but it can also have nested flexible data.

Simple form

{
   "type": "Form",
   "data": {
      "Date of Birth": "1958",
      "Registration Date": "06/13/2016",
      "Disciplinary Status": "CANCELLED BY BOARD"
   }
}

Nested form

{
   "type": "Form",
   "data": {
      "Date of Birth": "1958",
      "Registration Date": "06/13/2016",
      "Disciplinary Status": "CANCELLED BY BOARD",
      "Status Change": {
         "type": "Table",
         "data": [
            {
               "Status Code": "CB",
               "Effective Date": "06/10/2016",
               "Description": "CANCELLED BY BOARD"
            },
            {
               "Status Code": "NA",
               "Effective Date": "06/10/2016",
               "Description": "NOT ACTIVE"
            }
         ]
      }
   }
}

API Rate Limiting

Overview

To ensure the stability and performance of the Verifiable Platform API for all users, we enforce rate limits on API requests. These limits help maintain fair access and high availability across all clients.

Rate Limits

API requests are rate limited to 10,000 requests per 5 minutes. If a client exceeds this limit, the API will return an HTTP 429 Too Many Requests response.

Verifiable may adjust rate limits in the future based on factors such as endpoint-specific traffic patterns or system load. Changes may include increasing or decreasing limits or introducing secondary rate limits for specific use cases. Any changes will be reflected in this documentation.

Example response:

HTTP/1.1 429 Too Many Requests
{
    "title": "You have exceeded the allowed rate limit of 10,000 per 5 mins. Try again later.",
    "status": 429
}
Download OpenAPI description
api.json
api.yaml
Languages
Servers
Production
https://api.discovery.verifiable.com
Staging
https://api.discovery-staging.verifiable.com

Authentication

These endpoint allow you to create and manage access tokens to be used in API calls. Unlike most other endpoints, when creating an access token, these do not require an access token to be used. Instead you authenticate via another secure mechanism and in exchange you retrieve an access token.

Operations

Definitions

Definitions for static data

Operations

Providers

Endpoints related to managing and listing providers. A provider must be created and associated with license numbers, NPI numbers or other identifiers that can be used to perform lookups to fetch associated data for this provider. The data registered on the provider will be matched against the data returned by these lookups and used to detect inconsistencies or problems in the data or licenses.

Operations

Create a new provider

Request

Creates a new provider that can be used to store information about this provider. Once a provider is created you can attach records, notes, documents and create other associations with this provider such as adding them to a Group or Payer.

Bodyapplication/json
firstNamestringnon-emptyrequired

The first (given) name of the provider.

Example: "string"
lastNamestringnon-emptyrequired

The last (family) name of the provider.

Example: "string"
dateOfBirthstring(date-time)

The date of birth of this provider.

Example: "2000-08-24"
genderstring

Provider's gender (optional).

Enum"Unknown""Male""Female""NonBinaryOrThirdGender""Other""PreferNotToSay"
ethnicityArray of strings

Provider's ethnicity (optional).

Items Enum"AmericanIndianOrAlaskaNative""Asian""BlackOrAfricanAmerican""HispanicOrLatino""NativeHawaiianOrOtherPacificIslander""White""PreferNotToSay""NoInformationToAnswer"
ssnstring

The social security number of this provider.

Example: "123456789"
npiinteger(int64)

The 10 digit National Provider Identifiers (NPI) of this provider

aliasesArray of objects(ProviderAliasRequestModel)

A list of aliases that this provider is also known by.

primaryPracticeStatestring

The primary practice state of the provider.

Enum"AL""AK""AZ""AR""CA""CO""CT""DE""DC""FL"
additionalPracticeStatesArray of strings

Additional practice states of the provider. Cannot include the primary practice state.

Items Enum"AL""AK""AZ""AR""CA""CO""CT""DE""DC""FL"
credentialingStatusstring

The name of credentialing status. The default value is 'Data Collection'.

emailsArray of objects(ProviderEmailRequestModel)

A list with provider emails.

addressesArray of objects(ProviderAddressRequestModel)

A list with provider addresses.

phonestring

Primary phone number associated with this provider

languagesArray of strings

A list of languages, other than English, this provider speaks.

credentialedDatestring(date-time)

Date this provider was originally credentialed

recredentialedDatesArray of strings(date-time)

A list of dates when this provider was re-credentialed.

nextCredentialingDatestring(date)

Date this provider should be credentialed next

providerTypeIdstring(uuid)

Provider type id associated with this provider.

segmentIdstring(uuid)

The segment identifier to assign this provider to. If not specified, the default segment will be used.

deactivatedboolean

If set to true, the provider will be deactivated. If set to false, the provider will be activated.

curl -i -X POST \
  https://api.discovery.verifiable.com/providers \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2000-08-24",
    "ssn": "123456789"
  }'

Responses

Created

Bodyapplication/json
idstring(uuid)

Unique identifier associated with this provider.

firstNamestringnon-emptyrequired

The first (given) name associated with this provider.

lastNamestringnon-emptyrequired

The last (family) name associated with this provider.

dateOfBirthstring(date-time)

The date of birth of this provider.

ssnstring

The social security number of this provider.

credentialingStatusstringnon-emptyrequired

The name of credentialing status. The default value is 'Data Collection'.

credentialedDatestring(date-time)

Date this provider was originally credentialed

nextCredentialingDatestring(date)

Date this provider should be credentialed next

npiinteger(int64)

The 10 digit National Provider Identifiers (NPI) of this provider.

deactivatedboolean

If set, the provider is deactivated. Verifications and profile imports can't be triggered for the inactive provider.

deactivatedAtstring(date-time)
aliasesArray of objects(ProviderAliasModel)

A list of aliases that this provider is also known by.

primaryPracticeStatestring

The primary practice state of the provider.

Enum"AL""AK""AZ""AR""CA""CO""CT""DE""DC""FL"
additionalPracticeStatesArray of strings

Additional practice states of the provider. Cannot include the primary practice state.

Items Enum"AL""AK""AZ""AR""CA""CO""CT""DE""DC""FL"
genderstring

Provider's gender (optional).

Enum"Unknown""Male""Female""NonBinaryOrThirdGender""Other""PreferNotToSay"
ethnicityArray of strings

Provider's ethnicity (optional).

Items Enum"AmericanIndianOrAlaskaNative""Asian""BlackOrAfricanAmerican""HispanicOrLatino""NativeHawaiianOrOtherPacificIslander""White""PreferNotToSay""NoInformationToAnswer"
addressesArray of objects(ProviderAddressModel)

If set, the provider's addresses will be updated with this value. To remove the addresses pass an empty array.

emailsArray of objects(ProviderEmailModel)

If set, the provider's emails will be updated with this value. To remove the emails pass an empty array.

phonestring

Primary phone number associated with this provider

languagesArray of strings

A list of languages, other than English, this provider speaks.

recredentialedDatesArray of strings(date-time)

A list of dates when this provider was re-credentialed.

providerTypeobject(ProviderTypeModel)
segmentobject(SegmentModel)
Example: {"id":"3516a6ba-c998-4bfb-9017-322f8cf63674","name":"acme-corp"}
createdAtstring(date-time)

Timestamp when this provider was created.

Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "firstName": "string",
  "lastName": "string",
  "dateOfBirth": "2019-08-24T14:15:22Z",
  "ssn": "string",
  "credentialingStatus": "string",
  "credentialedDate": "2019-08-24T14:15:22Z",
  "nextCredentialingDate": "2019-08-24",
  "npi": 0,
  "deactivated": true,
  "deactivatedAt": "2019-08-24T14:15:22Z",
  "aliases": [
    { … }
  ],
  "primaryPracticeState": "AL",
  "additionalPracticeStates": [
    "AL"
  ],
  "gender": "Unknown",
  "ethnicity": [
    "AmericanIndianOrAlaskaNative"
  ],
  "addresses": [
    { … }
  ],
  "emails": [
    { … }
  ],
  "phone": "string",
  "languages": [
    "string"
  ],
  "recredentialedDates": [
    "2019-08-24T14:15:22Z"
  ],
  "providerType": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string"
  },
  "segment": {
    "id": "3516a6ba-c998-4bfb-9017-322f8cf63674",
    "name": "acme-corp"
  },
  "createdAt": "2019-08-24T14:15:22Z"
}

List providers

Request

Returns a page of providers.

Query
statusstring

If set, the items will be filtered on providers with the specified status.

Enum"None""NeedsReview""ExpiresSoon""Expired""Monitored""NotMonitored""NotFoundLicenses""DisciplinaryActionLicenses""UnableToVerifyLicenses"
providerNamestring

If set, the items will be filtered on providers with the specified name or alias name.

credentialingStatusArray of strings

If set, the items will be filtered on providers with the specified credentialing status.

providerTypeIdstring(uuid)

If set, the items will be filtered on providers with the specified provider type.

npiinteger(int64)

If set, the items will be filtered on providers with the specified npi number.

deactivatedboolean

If set, the items will be filtered on providers with the specified deactivated status.

nextCredentialingDateOnOrAfterstring(date)

If set, the items will be filtered on providers with the specified next credentialing date that is equal to or greater than the date specified.

nextCredentialingDateOnOrBeforestring(date)

If set, the items will be filtered on providers with the specified next credentialing date that is equal to or less than the date specified.

sortedBystring

The property by which the returned data will be sorted.

Enum"Id""LastName""FirstName""CredentialingStatus""CredentialedDate"
sortobject

If set, the properties and directions the returned data will be sorted by.

cursorstring

The cursor to render the page requested. To load the first page send an empty cursor, then the system will generate the cursors to go to the next and/or previous pages automatically.

countinteger(int32)

The number of items to include in a single page.

sortDirectionstring

The direction the returned data will be sorted by.

Enum"Asc""Desc"
offsetinteger(int32)Deprecated

The offset for the page to start.

curl -i -X GET \
  https://api.discovery.verifiable.com/providers

Responses

Success

Bodyapplication/json
sortobject

The properties and directions the data is sorted by.

Example: {"Id":"Asc","FirstName":"Asc","LastName":"Asc","CredentialingStatus":"Desc"}
previousCursorstring

The value to use for cursor to get to the previous paginated page. null will be returned if it's the first page.

Example: "string"
nextCursorstring

The value to use for cursor to get to the next paginated page. null will be returned if it's the last page.

Example: "string"
pageSizeinteger(int32)

The maximum number of items included in this page.

countinteger(int32)

The number of items in this page.

totalCountinteger(int32)

The total number of items in all pages combined.

itemsArray of objects(ProviderModel)

The providers in the current page.

Example: [{"id":"497f6eca-6276-4993-bfeb-53cbbbba6f08","firstName":"string","lastName":"string","dateOfBirth":"2019-08-24T14:15:22.0000000Z","ssn":"***","credentialingStatus":"string","credentialedDate":"2019-08-24T14:15:22.0000000Z","npi":0,"aliases":[{"id":"9b4c12e8-02c5-4107-a524-c02416d43079","firstName":"string","lastName":"string"}],"addresses":[{"id":"e57c9ee4-807d-456a-bf32-623280064ca5","state":"AL","zipCode":"string","city":"string","addressLine1":"string","addressLine2":"string","type":"Unspecified"}],"emails":[{"id":"1d46ecfe-5ce4-4b9c-aaba-3543e15d36d1","email":"string","type":"Unspecified"}],"phone":"string","languages":["string"],"recredentialedDates":["2019-08-24T14:15:22.0000000Z"],"providerType":{"id":"497f6eca-6276-4993-bfeb-53cbbbba6f08","name":"string"}}]
sortedBystring

The property by which the data is sorted.

Enum"Id""LastName""FirstName""CredentialingStatus""CredentialedDate"
Example: "Id"
sortDirectionstring

The direction in which the data is sorted.

Enum"Asc""Desc"
Example: "Asc"
nextOffsetinteger(int32)Deprecated

The value to use for offset to get the next page following the current page or null if this page is the last.

Response
application/json
{
  "previousCursor": "string",
  "nextCursor": "string",
  "nextOffset": 0,
  "pageSize": 0,
  "count": 0,
  "totalCount": 0,
  "items": [
    { … }
  ],
  "sortedBy": "Id",
  "sortDirection": "Asc",
  "sort": {
    "Id": "Asc",
    "FirstName": "Asc",
    "LastName": "Asc",
    "CredentialingStatus": "Desc"
  }
}

Get an existing provider

Request

Returns the data for a specific provider.

Path
providerIdstring(uuid)required

Identifier of the provider to get the data for.

curl -i -X GET \
  'https://api.discovery.verifiable.com/providers/{providerId}'

Responses

Success

Bodyapplication/json
idstring(uuid)

Unique identifier associated with this provider.

firstNamestringnon-emptyrequired

The first (given) name associated with this provider.

lastNamestringnon-emptyrequired

The last (family) name associated with this provider.

dateOfBirthstring(date-time)

The date of birth of this provider.

ssnstring

The social security number of this provider.

credentialingStatusstringnon-emptyrequired

The name of credentialing status. The default value is 'Data Collection'.

credentialedDatestring(date-time)

Date this provider was originally credentialed

nextCredentialingDatestring(date)

Date this provider should be credentialed next

npiinteger(int64)

The 10 digit National Provider Identifiers (NPI) of this provider.

deactivatedboolean

If set, the provider is deactivated. Verifications and profile imports can't be triggered for the inactive provider.

deactivatedAtstring(date-time)
aliasesArray of objects(ProviderAliasModel)

A list of aliases that this provider is also known by.

primaryPracticeStatestring

The primary practice state of the provider.

Enum"AL""AK""AZ""AR""CA""CO""CT""DE""DC""FL"
additionalPracticeStatesArray of strings

Additional practice states of the provider. Cannot include the primary practice state.

Items Enum"AL""AK""AZ""AR""CA""CO""CT""DE""DC""FL"
genderstring

Provider's gender (optional).

Enum"Unknown""Male""Female""NonBinaryOrThirdGender""Other""PreferNotToSay"
ethnicityArray of strings

Provider's ethnicity (optional).

Items Enum"AmericanIndianOrAlaskaNative""Asian""BlackOrAfricanAmerican""HispanicOrLatino""NativeHawaiianOrOtherPacificIslander""White""PreferNotToSay""NoInformationToAnswer"
addressesArray of objects(ProviderAddressModel)

If set, the provider's addresses will be updated with this value. To remove the addresses pass an empty array.

emailsArray of objects(ProviderEmailModel)

If set, the provider's emails will be updated with this value. To remove the emails pass an empty array.

phonestring

Primary phone number associated with this provider

languagesArray of strings

A list of languages, other than English, this provider speaks.

recredentialedDatesArray of strings(date-time)

A list of dates when this provider was re-credentialed.

providerTypeobject(ProviderTypeModel)
segmentobject(SegmentModel)
Example: {"id":"3516a6ba-c998-4bfb-9017-322f8cf63674","name":"acme-corp"}
createdAtstring(date-time)

Timestamp when this provider was created.

Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "firstName": "string",
  "lastName": "string",
  "dateOfBirth": "2019-08-24T14:15:22Z",
  "ssn": "string",
  "credentialingStatus": "string",
  "credentialedDate": "2019-08-24T14:15:22Z",
  "nextCredentialingDate": "2019-08-24",
  "npi": 0,
  "deactivated": true,
  "deactivatedAt": "2019-08-24T14:15:22Z",
  "aliases": [
    { … }
  ],
  "primaryPracticeState": "AL",
  "additionalPracticeStates": [
    "AL"
  ],
  "gender": "Unknown",
  "ethnicity": [
    "AmericanIndianOrAlaskaNative"
  ],
  "addresses": [
    { … }
  ],
  "emails": [
    { … }
  ],
  "phone": "string",
  "languages": [
    "string"
  ],
  "recredentialedDates": [
    "2019-08-24T14:15:22Z"
  ],
  "providerType": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string"
  },
  "segment": {
    "id": "3516a6ba-c998-4bfb-9017-322f8cf63674",
    "name": "acme-corp"
  },
  "createdAt": "2019-08-24T14:15:22Z"
}

ProvidersInfo

Endpoints related to managing and listing providers' info. Education, insurance, training and CAQH login info can be added to providers. Education, liability insurance, and training can have multiple entries. They can be created via POST, modified by PATCH, and removed by DELETE methods. CAQH login info is a single entry per provider and can be created or replaced by PUT, removed by DELETE and modified by PATCH method.

Operations

ProviderProfiles

These endpoints let you import a provider’s profile data from different sources (such as a provider’s National Provider Identifier (NPI) record). This allows you to build a more complete picture of a provider within Verifiable and gives you easy access to the latest provider profile data across multiple sources.

In order to import an external profile, each source has its own list of required parameters. A provider must first have the required data in their Verifiable profile before you can run an import.

Once a request is created, fetching a profile is fast and typically takes seconds to return. You can check the status of an import request using the "Get an existing provider profile import" endpoint.

Operations

Notes

These endpoints allow you to create and manage provider notes.

Operations

Files

Endpoints for binary file access. When any of the other APIs return file paths, these file paths are referring to the path parameter in the following API's. File paths are unique per organization, but the same path can exist in multiple organizations.

Operations

Facilities

Endpoints related to managing and retrieving Facility data. These APIs allow you to create, update, and retrieve facilities and their associated metadata. Each facility record includes key identifiers such as address, group tax ID, contact information, Medicaid number, and Medicare number. This data can be used for lookups, verification, and detecting inconsistencies in facility records or affiliations. In addition to core facility management, these endpoints support retrieving reference data related to facilities, such as license types, accreditations, Medicare enrollment types, and taxonomies.

Operations

FacilitiesInfo

Endpoints related to managing and retrieving detailed Facility Info. These APIs allow you to manage key information associated with a facility, including NPI numbers, DEA registrations, liability insurance policies, licenses, accreditations, CMS certifications, and Medicare enrollments. Most Facility Info types can have multiple entries per facility and support full CRUD operations via standard HTTP methods (POST, PATCH, DELETE, and GET).

Operations

FacilitiesSpecialties

Endpoints related to managing and retrieving Facility Specialties. These APIs allow you to associate specialties with a specific facility, retrieve a list of assigned specialties, view details for an individual specialty, and remove specialties as needed. Each specialty is linked to a facility using unique identifiers in the API path. In addition to specialty management, the APIs support retrieving detailed information linked to each facility specialty. This includes endpoints for listing all associated info items, with optional filtering by type to support more targeted queries.

Operations

Licenses

These endpoints allow you to add licenses to a provider and perform license lookups. Please note that a license lookup may take some time depending on the load and performance of the external data source. It is generally recommended to wait at least 2 seconds before polling for an update or use one of the notification mechanisms we provide (TBD).

License verification result will have the basic information about the license such as license number, licenseType, status, issued date, expiry date, etc. In addition, the disciplinary actions and other additional information that is captured from the source site is represented through the disciplinaryActions and additionalProperties fields. The disciplinary actions and additional properties fields describe the type of data that is getting represented and are using the Flexible Data Model.

Operations

Datasets

Endpoints related to scanning datasets and reading resulting matches. The supported datasets will grow over time and can be discovered via the ListDatasets endpoint. A dataset scan is asynchronous, but most scans will result in near immediate completion. A webhook of type DatasetScanCompleted is triggered upon completion, but you can also check the completion status by querying the GetDatasetScan operation.

Operations

DEA

These endpoints allow you to add DEA registration numbers to a provider and perform DEA registration lookups. Unlike license verifications a DEA registration lookup is done immediately.

Operations

BoardCertifications

These endpoints allow you to add board certifications to a provider and perform certification lookups. Please note that a lookup may take some time depending on the load and performance of the external data source. It is generally recommended to wait at least 2 seconds before polling for an update or use one of the notification mechanisms we provide (TBD).

Board certification verification result will have the basic information about the certification such as name, issued date, expiry date, etc. In addition, other additional information that is captured from the source site is represented through the additionalProperties fields. The additional properties fields describe the type of data that is getting represented and are using the Flexible Data Model.

Operations

Monitoring

Endpoints to allow you to enable/disable monitoring or update monitoring settings for monitorable data.

Operations

Alerts

Endpoints to list and dismiss active alerts. Alerts are triggered when an important event occurs that warrants user involvement. An alert can be considered dismissed if it has a dismissal timestamp and note.

Operations

CredentialingRequests

These endpoints allow you to create and get credentialing requests. A credentialing request is a workflow that supports the creation of a credentialing packet. You can create a request for Verifiable's NCQA-certified CVO services to process or you can choose to self manage the workflow. By default, a CVO credentialing request will be created unless self managed is specified. Once a request has been created you cannot change between self managed and CVO. Multiple credentialing events can be created and managed for a provider.

When a CVO credentialing request is created, the request will be sent directly to the Verifiable CVO team to begin processing. You can check the status of the request by querying the GetCredentialingRequest or ListCredentialingRequests operations.

To keep track of the request, events are created to manage each stage of the credentialing request process using the CreateCredentialingRequestEvent operation. You can also fetch specific events using the GetCredentialingRequestEvent operation.

Operations

Integrations

These endpoints are used for our integrations with 3rd party services. They are not intended to be consumed directly by most clients. Please contact us for more information on our integration possibilities.

Operations

Webhooks

Endpoints to allow you to create and manage webhooks that will be called when a special event occurs. On this special event Verifiable will attempt to make an HTTP POST to the URL specified in the webhook. The payload of this request can vary, depending on the type. The type is included in the X-WebhookType header. This allows you to register multiple webhooks on the same endpoint and still be able to distinguish the webhook types. The webhook dispatcher expects the remote server to return an HTTP success status code. If it cannot be delivered, it will retry the callback a maximum of 3 times.

By default, we do not allow you to use insecure URLs for callbacks. You can optionally create a webhook that allows insecure URLs for testing purposes. We recommend you to use an HTTPS callback with a valid SSL certificate so that the integrity of the callback is ensured. For added security we will pass the webhook id (which is only known to the creator) in the X-WebhookId header, and we will pass an optional secret in the X-Secret header.

To be able to uniquely track webhook messages we also include the X-TraceId header. This will contain a unique value that doesn't change for every attempt we make to send a specific message. You can use this to keep a log of all messages that you have successfully processed.

You can refer to Webhook Callbacks to find the model that is included in the payload of the HTTP request to the callback URL.

Operations

Audit

Each API call that results in data being created, updated or deleted will result in one or more entries in the audit log. Using the endpoints provided in this section it is possible to list entries in this log.

Operations

Users

Endpoints related to managing and listing users.

Operations

Reports

Operations

Dataset Records

This section contains an overview of the models used by the different dataset types. These models can also be discovered via the ListDatasets operation.

Webhook Callbacks

This section contains an overview of the models that are in the HTTP POST payload of a webhook callback. Refer to Webhooks for more information on how to register a webhook.