Introduction

Welcome to the documentation of our RESTful Onboarding API hosted by MedAllies!

This API supports all resources and components that manage the Onboarding process. These include the creation and maintenance of Organizations and Direct Accounts, and connecting Direct accounts with specific Organizations; otherwise known as Memberships.

Memberships are formed by adding either a new Direct Account or existing account information associated with to a designated existing organization. It is important to remember that an organization must exist before any direct Direct Accounts can be created and associated with the organization.

Each resource consumes and produces defined datatypes represented as JSON structures. Some datatypes can contain other datatypes, referred to in this document as "sub-datatypes". Metadata about these datatypes can be retrieved programmatically through the Metadata resource, containing information about the datatype such as field names, descriptions, default values, and whether the fields are required or not for add and modification operations. The Metadata resource is the only resource that does not require authentication, all other resources will require authentication. For more detailed information about datatypes and the use of their metadata, see the section "Resource Datatypes and Metadata".

Many of the methods in the resources support special query directives that allow the developer to have better control over how much information they want returned to them. For example, a query directive that specifies which fields should be included in the returned data, and another that specifies that minimum data to be returned. For more detailed information about query directives, see the section "Query Directives".

The API also provides filtered searches for data through a mechanism that allows for flexible definition of search criteria from the very simple to the very complicated. For more detailed information about filtered searches and how to construct them, see the section "Filtering Searches".

Dates

All date values returned by a resource are ISO 8601 which is human readable and has common support across all languages. The time zone is coordinated universal time (UTC).

All date strings sent in requests should be formatted as: yyyy-MM-ddTHH:mm:ssZ; for example: 2016-05-14T11:45:00Z.

Endpoint

https://api.medalliesdirect.com:9543/OnBoard/

Authentication

MedAllies uses API keys in order to grant access to the API.

You should keep your API keys private and store them securely. Your API key/value pairs must be included in all API requested to the server in a header that looks like the following:

All resources require an assigned MedAllies application key placed in the HTTP header using the key

"X-MedAllies-App-Key", except resource metadata requests.

Key: Content-Type Value: application/json
Key: Authorization Value: < Authorization Type >:< User-name + Hashed or Encrypted Password >
Auth Example:
Key: Authorization Value: Basic VXNlcm5hbWU6UGFzc3dvcmQ

Response Representations

Successful responses from all resources will return an HTTP code as documented for that resource method and, as warranted, a JSONObject also as documented for that resource method. Some resource methods will return more than one set of data elements, defined by the resource's documented datatype. These resources will have the following response body representations:

{
   "count":< ... total data count ... >,
   "items":[ ... JSONArray of resource data ... ]
}

Note that "count" is the total number of possible resources available regardless of any supplied offset or limit values provided in the request.

Query Directives

For resources that support them (as documented by the resource below), the query string of the URL can contain one or more of the following directives which provide added instructions to the resource about the action being provided or the data to return.

_fields

This directive, when provided with a comma separated list of field names, will cause the resulting returned data to return only data for the specified fields. Note that it is not permissible to specify a field as collapsible and request one of its values in the same query. Sub-datatypes are supported by specifying them with a dot ("."), so for example, "vendor.name" will return only the organization's vendor's name. All datatypes that have an "id" field, will always return the datatype's id, regardless of the values supplied with _fields. This directive only affects items returned.

_collapse

This directive, when provided with a comma separated list of datatype field names will cause the resulting returned data to "collapse" to a shortened version of the specified sub-data. For example, the organization datatype has a sub-datatype of vendor. By default all the vendor information associated with a specific organization will be returned with the organization data. If the query includes this directive with a value of vendor, then the vendor data will be collapsed to a shortened form. All collapsed datatypes will minimally have a URI reference to the data that was collapsed.

Using a ‘*' for the value with _collapse will force all sub-entities to be returned collapsed if they support that feature.

Note: When combining _fields with _collapse, you must specify the collapsible field in the _fields list or that collapsed data will not be returned. Only the data specified in the _fields will be returned.

_count

Generally when retrieving a number of data from a resource, the resource will return a JSON object that contains the total count of data found for the request as well as a set of data (note that this set of data returned may be limited by providing other query directives as supported by the resource, such as _fields, and may be smaller than the total count returned). This directive will cause the resource to only return the total count of resources found.

_items

Generally when retrieving a number of data from a resource, the resource will return a JSON object that contains a set of data or "items" as well as the total count of data found for the request. This directive will cause the resource to only return those items the resource found based on any limiting criteria supplied by the initial request.

API EndPoints

Find Metadata of Datatype

Example of Request Body for getting the metadata of Datatype:

{
    "dataType": "Vendor",
    "metadata": [
         {
            "modifyDataAttribute": 0,
            "filterable": true,
            "fieldType": "EndPointType",
            "description": "",
            "addDataAttribute": 2,
            "sortable": true,
            "idField": false,
            "fieldTypeMetadata": {
                "EndPointType": [
                    {
                        "modifyDataAttribute": 0,
                        "filterable": true,
                        "fieldType": "String",
                        "description": "",
                        "addDataAttribute": 0,
                        "sortable": true,
                        "idField": false,
                        "defaultValue": "",
                        "fieldName": "name"
                    },
                    {
                        "modifyDataAttribute": 0,
                        "filterable": true,
                        "fieldType": "Number",
                        "description": "",
                        "addDataAttribute": 0,
                        "sortable": true,
                        "idField": false,
                        "defaultValue": "",
                        "fieldName": "code"
                    }
                ]
            },
            "defaultValue": "",
            "fieldName": "endpointType"
    ]
}

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/metadata/vendor

Description:

Returns a list of all fields and information about those fields for a supplied datatype; see section on "Resource Datatypes and Metatdata" for more information.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a JSON representation of data.

Supported Query Directives: _html

NOTE: The _html Query Directive is unique to this resource, and when provided returns an HTML summary page of the requested datatype's metadata.

Error Codes

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/metadata/errorCodes

Example of Request Body for getting error codes:

{
    "errorCodes": [
        {
            "codeString": "REST_UNAUTH_ACCESS",
            "code": 100
        },
        {
            "codeString": "REST_INVALID_PARAM",
            "code": 101
        },
        {
            "codeString": "REST_MISSING_REQ_PARAM",
            "code": 102
        },
        .
        .
        .
        .
    ]
}

Description:

Returns a list of all the error codes and a human readable error code name.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a JSON representation of data: { "errorCodes":[ { "codeString":..., "code":... }, ... }

Supported Query Directives: _html

None

Get Vendor By Id

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/vendors/56

Example of Request Body for getting the vendor by Id:

{
    "product": "Vendor Name",
    "id": 56,
    "endpointType": {
        "name": "XD",
        "code": 3
    },
    "rootDomain": "vendordirect.net",
    "name": "VendorName",
    "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/vendors/56"
}

Description:

Method : GET

Returns vendor data for the supplied id.

Query Parameters

Parameter : id

Description: The id of the vendor to retrieve.

Type : Integer

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the data for the request id as a JSON representation matching the field names returned by a get resource metadata operation for the "Vendor" datatype. See the section on "Resource Datatypes and Metatdata" for more information.

Supported Query Directives: _html

None

Get Vendors (non filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/vendors?offset=5&limit=10

Example of Request Body for getting vendors list (non filterable):

{
    "count": 1,
    "items": [
        {
            "product": "Vendor Product Name",
            "id": 63,
            "endpointType": {
                "name": "XD",
                "code": 3
            },
            "rootDomain": "vendordirect.net",
            "name": "Vendor",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/vendors/63"
        }
    ]
}

Description:

Method : GET

Returns a defined number of vendor data based on optionally submitted criteria.

Query Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _count, _items

Get Vendors (filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/vendors

Example Request Body

{
   "offset":< ... offset value ... >,
   "limit":< ... limit value ... >,
   "sortOn":{ ... JSONObject representation of sort criteria ... },
   "filterOn":{ ... JSONObject representation of filter criteria ... }
}

Example of Response Body for getting the Vendors (filterable):

{
    "count": 1,
    "items": [
        {
            "product": "Vendor Product Name",
            "id": 63,
            "endpointType": {
                "name": "XD",
                "code": 3
            },
            "rootDomain": "vendordirect.net",
            "name": "Vendor",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/vendors/63"
        }
    ]
}

Description:

Method : POST

Returns a defined number of vendor data based on optionally submitted criteria.

Request Body Fields

Successful Response Representation: Returns an HTTP code of 200 (OK) and a response body containing the total number of resources that meet the "filterOn" criteria, and a JSON representation of resource data matching the field names returned by a get resource metadata operation for the "Vendor" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _count, _items

Get Organization by Id

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2

Example of Response Body for getting the organization of id 2:

{
    "creationDateTime": "2016-10-07T16:46:23Z",
    "practiceCity": "City name",
    "status": {
        "name": "Enabled",
        "code": 1
    },
    "organizationName": "Organization Name",
    "vendor": {
        "product": "Product name",
        "id": 45,
        "endpointType": {
            "name": "XD",
            "code": 3
        },
        "rootDomain": "productdirect.net",
        "name": "Product Name"
    },
    "npi": 1234567890,
    "typeCode": 1,
    "lastUpdateDateTime": "2020-02-24T17:20:01Z",
    "tin": "123456789",
    "id": 2,
    "practiceStreet2": "Suite 001",
    "practiceStreet1": "Westage Business Drive",
    "practiceState": "NY",
    "directAbbreviation": "tag",
    "telephoneNumber": "(999) 999-9999",
    "domain": {
        "id": 2,
        "domainName": "tag.medalliesdirect.net"
    },
    "practiceZip": "34776",
    "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2",
    "specialization": "Multi-Specialty",
    "endpointUri": "https://direct.healthcare.com/XDRService"
}

Description:

Method : GET

Returns organization information for the supplied id

Query Parameters

Successful Response Representation: Returns an HTTP code of 200 (OK) and a response body containing the total number of resources that meet the "filterOn" criteria, and a JSON representation of resource data matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements. Supported Query Directives: _html

_fields, _collapse

Get Organizations (non-filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations?offset=5&limit=10

Example of Response Body for getting the organizations list (non filterable):

{
    "count": 19,
    "items": [
        {
            "creationDateTime": "2016-10-07T16:46:23Z",
            "practiceCity": "City name",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "organizationName": "Organization Name",
            "vendor": {
                "product": "Product name",
                "id": 45,
                "endpointType": {
                    "name": "XD",
                    "code": 3
                },
                "rootDomain": "productdirect.net",
                "name": "Product Name"
            },
            "npi": 1234567890,
            "typeCode": 1,
            "lastUpdateDateTime": "2020-02-24T17:20:01Z",
            "tin": "123456789",
            "id": 2,
            "practiceStreet2": "Suite 001",
            "practiceStreet1": "Westage Business Drive",
            "practiceState": "NY",
            "directAbbreviation": "tag",
            "telephoneNumber": "(999) 999-9999",
            "domain": {
                "id": 2,
                "domainName": "tag.medalliesdirect.net"
            },
            "practiceZip": "34776",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2",
            "specialization": "Multi-Specialty",
            "endpointUri": "https://direct.healthcare.com/XDRService"
        },
        .
        .
        .
    ]
}

Description:

Method : GET

Returns a defined number of organization data based on optionally submitted criteria

Query Parameters

Successful Response Representation: Returns an HTTP code of 200 (OK) and a response body containing the data for the request id as a JSON representation matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information.

Supported Query Directives: _html

_fields, _collapse, _count, _items

Get Organizations (filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations

Example of Request Body for getting the organizations list(filterable):

{
   "offset":< ... offset value ... >,
   "limit":< ... limit value ... >,
   "sortOn":{ ... JSONObject representation of sort criteria ... }
}

Example of Response Body for getting the organizations list:

{
    "count": 19,
    "items": [
        {
            "creationDateTime": "2016-10-07T16:46:23Z",
            "practiceCity": "City name",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "organizationName": "Organization Name",
            "vendor": {
                "product": "Product name",
                "id": 45,
                "endpointType": {
                    "name": "XD",
                    "code": 3
                },
                "rootDomain": "productdirect.net",
                "name": "Product Name"
            },
            "npi": 1234567890,
            "typeCode": 1,
            "lastUpdateDateTime": "2020-02-24T17:20:01Z",
            "tin": "123456789",
            "id": 2,
            "practiceStreet2": "Suite 001",
            "practiceStreet1": "Westage Business Drive",
            "practiceState": "NY",
            "directAbbreviation": "tag",
            "telephoneNumber": "(999) 999-9999",
            "domain": {
                "id": 2,
                "domainName": "tag.medalliesdirect.net"
            },
            "practiceZip": "34776",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2",
            "specialization": "Multi-Specialty",
            "endpointUri": "https://direct.healthcare.com/XDRService"
        },
        .
        .
        .
    ]
}

Description:

Method : POST

Returns a defined number of organization data based on optionally submitted criteria.

Request Body Fields

Successful Response Representation: Returns an HTTP code of 200 (OK) and a response body containing the data for the request id as a JSON representation matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information.

Supported Query Directives: _html

_fields, _collapse, _count, _items

Create Organization

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/add

Example of Request Body for creating an organization:

Request Body: 
A JSON representation of the required writable fields matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information.

This resource method also supports creating more than one organization at a time by submitting a JSON representation such as:
   {
       "items": [
          { < ... data for Organization 1 ... > },
          { < ... data for Organization 2 ... > },
          { < ... data for Organization 3 ... > },
          { < ... data for Organization n ... > },
          ... 
       ]
   }

Example of Response Body for creating an organization ( need to modify ):

{
    "count": 19,
    "items": [
        {
            "creationDateTime": "2016-10-07T16:46:23Z",
            "practiceCity": "City name",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "organizationName": "Organization Name",
            "vendor": {
                "product": "Product name",
                "id": 45,
                "endpointType": {
                    "name": "XD",
                    "code": 3
                },
                "rootDomain": "productdirect.net",
                "name": "Product Name"
            },
            "npi": 1234567890,
            "typeCode": 1,
            "lastUpdateDateTime": "2020-02-24T17:20:01Z",
            "tin": "123456789",
            "id": 2,
            "practiceStreet2": "Suite 001",
            "practiceStreet1": "Westage Business Drive",
            "practiceState": "NY",
            "directAbbreviation": "tag",
            "telephoneNumber": "(999) 999-9999",
            "domain": {
                "id": 2,
                "domainName": "tag.medalliesdirect.net"
            },
            "practiceZip": "34776",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2",
            "specialization": "Multi-Specialty",
            "endpointUri": "https://direct.healthcare.com/XDRService"
        },
        .
        .
        .
    ]
}

Description:

Method : POST

Returns a defined number of organization data based on optionally submitted criteria.

Request Body Fields

Successful Response Representation:

Returns an HTTP code of 201 (CREATED) and a response body containing the data for the newly created resource as a JSON representation matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _collapse

Modify Organization

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/modify

Example of Request Body for modifying the organizations list:

Request Body: 
A JSON representation of one or more writable fields matching the field names returned by a get resource metadata operation for the "Organization" datatype. This resource method supports partial resource updates, supplying only those fields that need to be changed. The id field is always a required value when accessing this resource method. See the section on "Resource Datatypes and Metatdata" for more information.

This resource method also supports modifying more than one organization at a time by submitting a JSON representation such as:
   {
       "items": [
          { < ... data for Organization 1 ... > },
          { < ... data for Organization 2 ... > },
          { < ... data for Organization 3 ... > },
          { < ... data for Organization n ... > },
          ... 
       ]
   }

Example of Response Body for getting the organizations list:

{
    "count": 19,
    "items": [
        {
            "creationDateTime": "2016-10-07T16:46:23Z",
            "practiceCity": "City name",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "organizationName": "Organization Name",
            "vendor": {
                "product": "Product name",
                "id": 45,
                "endpointType": {
                    "name": "XD",
                    "code": 3
                },
                "rootDomain": "productdirect.net",
                "name": "Product Name"
            },
            "npi": 1234567890,
            "typeCode": 1,
            "lastUpdateDateTime": "2020-02-24T17:20:01Z",
            "tin": "123456789",
            "id": 2,
            "practiceStreet2": "Suite 001",
            "practiceStreet1": "Westage Business Drive",
            "practiceState": "NY",
            "directAbbreviation": "tag",
            "telephoneNumber": "(999) 999-9999",
            "domain": {
                "id": 2,
                "domainName": "tag.medalliesdirect.net"
            },
            "practiceZip": "34776",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2",
            "specialization": "Multi-Specialty",
            "endpointUri": "https://direct.healthcare.com/XDRService"
        },
        .
        .
        .
    ]
}

Description:

Method : POST: /organizations/modify

Modifies a resource with the information supplied in the request body.

Request Body Fields

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the data for the updated resource as a JSON representation matching the field names returned by a get resource metadata operation for the "Organization" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _collapse

Deactivate Organizations

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/deactivate?orgId=45

Description:

Method : GET

Deactivates one or more resources based on submitted parameters. Organizations that are being deactivated will also have all their member accounts deactivated.

Query Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK).

Supported Query Directives: _html

none

Activate Organizations

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/activate?orgId=45

Description:

Method : GET

Activates one or more resources based on submitted parameters. Organizations that are reactivated once deactivated will not have also have any related member accounts reactivated. Member accounts must be reactivated separately.

Query Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK).

Supported Query Directives: _html

none

Get Organization Memberships (non-filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2/memberships?offset=4&limit=265

Example of Response Body for getting the organization memberships list(non-filterable):

{
    "count": 265,
    "items": [
        {
            "directAddressLocalPart": "exampleName",
            "createDateTime": "2016-10-07T16:46:37Z",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "businessEmail": "exampleName@business.email.com",
            "account": {
                "id": 5,
                "createDateTime": "2016-10-07T16:46:36Z",
                "lastName": "Tyus",
                "telephoneNumber": "(913) 622-3395",
                "accountType": "nonProvider",
                "gender": "Female",
                "credentials": "AB",
                "lastUpdateDateTime": "2020-02-20T03:03:18Z",
                "firstName": "Example",
                "specialty": "Emergency Medical Technician, Basic"
            },
            "publishable": true,
            "lastUpdateDateTime": "2017-04-17T13:54:09Z",
            "directAddress": "example@tag.medalliesdirect.org",
            "organizationId": 2,
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/2/memberships/5"
        },
        .
        .
        .
    ]
}

Description:

Method : GET

Returns a defined number of accounts that have a membership with the specified organization.

Query Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data matching the field names returned by a get resource metadata operation for the "OrganizationMembership" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _collapse, _count, _items

Get Organization Memberships (filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/2/memberships

Example of Request Body for getting Organization Memberships(filterable):

{
   "offset":< ... offset value ... >,
   "limit":< ... limit value ... >,
   "sortOn":{ ... JSONObject representation of sort criteria ... }
}

Example of Response Body for getting the organization memberships list:

{
    "count": 265,
    "items": [
        {
            "directAddressLocalPart": "exampleName",
            "createDateTime": "2016-10-07T16:46:37Z",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "businessEmail": "exampleName@business.email.com",
            "account": {
                "id": 5,
                "createDateTime": "2016-10-07T16:46:36Z",
                "lastName": "Tyus",
                "telephoneNumber": "(913) 622-3395",
                "accountType": "nonProvider",
                "gender": "Female",
                "credentials": "AB",
                "lastUpdateDateTime": "2020-02-20T03:03:18Z",
                "firstName": "Example",
                "specialty": "Emergency Medical Technician, Basic"
            },
            "publishable": true,
            "lastUpdateDateTime": "2017-04-17T13:54:09Z",
            "directAddress": "example@tag.medalliesdirect.org",
            "organizationId": 2,
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/2/memberships/5"
        },
        .
        .
        .
    ]
}

Description:

Method : POST

Returns a defined number of accounts that have a membership with the specified organization and based on other optionally submitted criteria.

Query Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources that meet the "filterOn" criteria, and a JSON representation of resource data matching the field names returned by a get resource metadata operation for the "OrganizationMembership" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _collapse, _count, _items

Add Organization Membership

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/add

Example of Request Body (minimal data, required fields only):

For Department:
{
    "organizationId":< ... >,
    "account":{
        "accountType":"department",
        "departmentName":"< ... >"
    }
}

For Provider:
{
    "organizationId":< ... >,
    "account":{
        "accountType":"provider",
        "npin":"< ... >"
    }
}

For NonProvider:
{
    "organizationId":< ... >,
    "account":{
        "accountType":"nonProvider",
        "firstName":"< ... >",
        "lastName":"< ... >",
        "gender":"< ... >"
    }
}

Example of Response Body for adding an organization membership :

{
    "count": 265,
    "items": [
        {
            "directAddressLocalPart": "exampleName",
            "createDateTime": "2016-10-07T16:46:37Z",
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "businessEmail": "exampleName@business.email.com",
            "account": {
                "id": 5,
                "createDateTime": "2016-10-07T16:46:36Z",
                "lastName": "Tyus",
                "telephoneNumber": "(913) 622-3395",
                "accountType": "nonProvider",
                "gender": "Female",
                "credentials": "AB",
                "lastUpdateDateTime": "2020-02-20T03:03:18Z",
                "firstName": "Example",
                "specialty": "Emergency Medical Technician, Basic"
            },
            "publishable": true,
            "lastUpdateDateTime": "2017-04-17T13:54:09Z",
            "directAddress": "example@tag.medalliesdirect.org",
            "organizationId": 2,
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/2/memberships/5"
        },
        .
        .
        .
    ]
}

Description:

Method : POST

Creates a new account and associates that account with a previously created organization.

Request Data Requirements

Successful Response Representation:

Successful Response Representation: Returns an HTTP code of 201 (CREATED) and a response body containing the data for the newly created resource as a JSON representation matching the field names returned by a get resource metadata operation for the "OrganizationMembership" datatype. See the section on "Resource Datatypes and Metatdata" for more information. The JSON representation will also include a status code, indicating the processing status for the item. Also see "Response Representations" for more information about how this resource method returns multiple data elements. Example return JSON representation when adding one organization membership: { "statusCode": < ... processing status code ... > "item": < ... data for Organization Membership ... > }, }

Processing Status Codes

Supported Query Directives: _html

_fields, _collapse-

Modify Organization Membership

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/modify

Example of Request Body (minimal data, required fields only):

A JSON representation of the required writable fields matching the field names returned by a get resource metadata operation for the "OrganizationMembership" datatype, using one of three account types: "Department", "Provider", or "NonProvider". This resource method supports partial resource updates, supplying only those fields that need to be changed. The id field is always a required value when accessing this resource method. See the section on "Resource Datatypes and Metatdata" for more information.

This resource method also supports modifying more than one account organization membership at a time by submitting a JSON representation such as:
   {
       "items": [
          { < ... data for Organization Membership 1 ... > },
          { < ... data for Organization Membership 2 ... > },
          { < ... data for Organization Membership 3 ... > },
          { < ... data for Organization Membership n ... > },
          ... 
       ]
   }

NOTE: when adding more than one account organization membership at a time, each membership must belong to the same organization.

Description:

Method : POST

Modifies a resource with the information supplied in the request body.

Request Data Requirements

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the data for the updated resource as a JSON representation matching the field names returned by a get resource metadata operation for the "OrganizationMembership" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields

Get Organization Types

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/types

Example of Response Body for getting organization types :

{
    "count": 3,
    "items": [
        {
            "description": "Hospital",
            "code": 1
        },
        {
            "description": "Provider Organization",
            "code": 2
        },
        {
            "description": "Other",
            "code": 3
        }
    ]
}

Description:

Method : GET

Returns all supported organization types used when creating and modifying organization data.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data in key/value pairs; where the "description" is the organization type and the "code" is a related code.

Example: { "count":< ... total data count ... >, "items":[ { "description":< ... description ... >, "code":< ... code ... > }, ... ] }

Supported Query Directives: _html

None

Get US States

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/organizations/usStates

Example of Response Body for getting US States :

{
    "count": 59,
    "items": [
        {
            "name": "Alaska",
            "abbreviation": "AK"
        },
        {
            "name": "Alabama",
            "abbreviation": "AL"
        },
        {
            "name": "Arkansas",
            "abbreviation": "AR"
        },
        {
            "name": "Arizona",
            "abbreviation": "AZ"
        },
        .
        .
        .
    ]
}

Description:

Method : GET

Returns accepted state abbreviations and names used when creating and modifying organization data.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data in key/value pairs; where the "name" is the full name of that US state and the "abbreviation" is the accepted abbreviation.

Example: { "count":< ... total data count ... >, "items":[ { "name":< ... name ... >, "abbreviation":< ... abbreviation ... > }, ... ] }

Supported Query Directives: _html

None

Get Account by Id

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/45

Example of Response Body for getting account by id :

{
    "id": 45,
    "createDateTime": "2017-07-18T20:16:38Z",
    "lastName": "lastName",
    "telephoneNumber": "(999) 999-9999",
    "accountType": "nonProvider",
    "gender": "null",
    "middleInitial": "",
    "lastUpdateDateTime": "2020-02-24T17:39:33Z",
    "firstName": "firstName",
    "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/45",
    "specialty": "N/A",
    "suffix": ""
}

Description:

Method : GET

Returns account information for the supplied id.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the data for the request id as a JSON representation matching the field names returned by a get resource metadata operation for one of three account datatypes: "Department", "Provider", or "NonProvider". See the section on "Resource Datatypes and Metatdata" for more information.

Supported Query Directives: _html

_fields

Deactivate Accounts

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/deactivate

Example of Request Body for deactivating accounts :

The JSON representation to deactivate one account membership with an organization:

   {
        "orgId":< ... organization id ... >,
        "accountId":< ... account id ... >, 
        "reasonCode":< ... deactivation reason code ... >
   }

Or to supply more than one account for deactivation:

   {
        "orgId":< ... organization id ... >,
        "items": [
            {
            "accountId":< ... account id ... >, 
            "reasonCode":< ... deactivation reason code ... >
        },
            ...
        ]
   }

   NOTE: See "Get Account Deactivate Reasons" below for more information on obtaining acceptable deactivation reason codes that can be supplied for this method.   

Description:

Method : POST

Deactivates one or more account/organization association based on submitted parameters.

Field | Description | Type -------------- | -------------- orgId | The id of the organization with which the supplied account ids have a membership. | Integer accountId | The id of the account whose membership with the supplied organization id will be deactivated. | Integer reasonCode | The "Deactivation Reason" code that is to be associated with the deactivation of the supplied account/organization membership. | Integer

Successful Response Representation:

Returns an HTTP code of 200 (OK).

Supported Query Directives: _html

None

Activate Accounts

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/activate?orgId=2&accountId=45

Description:

Method : GET

Activates one or more account/organization association based on submitted parameters

Query Parameters

Parameter | Description | Type -------------- | -------------- orgId | The id of the organization with which the supplied account ids have a membership. | Integer accountId | The id of the account whose membership with the supplied organization id will be deactivated. | Integer reasonCode | The "Deactivation Reason" code that is to be associated with the deactivation of the supplied account/organization membership. | Integer

Successful Response Representation:

Returns an HTTP code of 200 (OK).

Supported Query Directives: _html

None

Get Account Memberships (non-filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/45/memberships?offset=0&limit=10

Example of Response Body for getting Account Memberships (non-filterable)

{
    "count": 1,
    "items": [
        {
            "directAddressLocalPart": "addressExample",
            "createDateTime": "2017-07-18T20:16:38Z",
            "organization": {
                "creationDateTime": "2016-10-07T16:46:23Z",
                "practiceCity": "City Name 1234",
                "status": {
                    "name": "Enabled",
                    "code": 1
                },
                "organizationName": "Organizaiton name",
                "vendor": {
                    "product": "Product Name",
                    "id": 45,
                    "endpointType": {
                        "name": "XD",
                        "code": 3
                    },
                    "rootDomain": "productdirect.net",
                    "name": "Product Name"
                },
                "npi": 1234567890,
                "typeCode": 1,
                "lastUpdateDateTime": "2020-02-24T17:20:01Z",
                "tin": "123456789",
                "id": 2,
                "practiceStreet2": "Suite 001",
                "practiceStreet1": "Westage Business Drive",
                "practiceState": "NY",
                "directAbbreviation": "tag",
                "telephoneNumber": "(999) 999-9999",
                "domain": {
                    "id": 2,
                    "domainName": "tag.medalliesdirect.net"
                },
                "practiceZip": "12524",
                "specialization": "Multi-Specialty",
                "endpointUri": "https://direct.healthcare.com/XDRService"
            },
            "accountId": 45,
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "publishable": false,
            "lastUpdateDateTime": "2017-07-18T20:16:38Z",
            "directAddress": "addressName@tag.medalliesdirect.net",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/45/memberships/2"
        }
    ]
}

Description:

Method : GET

Returns a defined number of organizations with which the specified account has memberships.

Query Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data matching the field names returned by a get resource metadata operation for the "AccountMembership" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements. Supported Query Directives: _html

_fields, _collapse, _count, _items

Get Account Memberships (filterable)

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/45/memberships

Example of Request Body for getting Account Memberships

{
   "offset":< ... offset value ... >,
   "limit":< ... limit value ... >,
   "sortOn":{ ... JSONObject representation of sort criteria ... },
   "filterOn":{ ... JSONObject representation of filter criteria ... }
}

Example of Response Body for getting Account Memberships (filterable)

{
    "count": 1,
    "items": [
        {
            "directAddressLocalPart": "addressExample",
            "createDateTime": "2017-07-18T20:16:38Z",
            "organization": {
                "creationDateTime": "2016-10-07T16:46:23Z",
                "practiceCity": "City Name 1234",
                "status": {
                    "name": "Enabled",
                    "code": 1
                },
                "organizationName": "Organizaiton name",
                "vendor": {
                    "product": "Product Name",
                    "id": 45,
                    "endpointType": {
                        "name": "XD",
                        "code": 3
                    },
                    "rootDomain": "productdirect.net",
                    "name": "Product Name"
                },
                "npi": 1234567890,
                "typeCode": 1,
                "lastUpdateDateTime": "2020-02-24T17:20:01Z",
                "tin": "123456789",
                "id": 2,
                "practiceStreet2": "Suite 001",
                "practiceStreet1": "Westage Business Drive",
                "practiceState": "NY",
                "directAbbreviation": "tag",
                "telephoneNumber": "(999) 999-9999",
                "domain": {
                    "id": 2,
                    "domainName": "tag.medalliesdirect.net"
                },
                "practiceZip": "12524",
                "specialization": "Multi-Specialty",
                "endpointUri": "https://direct.healthcare.com/XDRService"
            },
            "accountId": 45,
            "status": {
                "name": "Enabled",
                "code": 1
            },
            "publishable": false,
            "lastUpdateDateTime": "2017-07-18T20:16:38Z",
            "directAddress": "addressName@tag.medalliesdirect.net",
            "href": "https://api.medalliesdirect.com:9543/OnBoard/services/v1/45/memberships/2"
        }
    ]
}

Description:

Method : POST

Returns a defined number of organizations with which the specified account, and based on other optionally submitted criteria, has memberships.

Request Parameters

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources that meet the "filterOn" criteria, and a JSON representation of resource data matching the field names returned by a get resource metadata operation for the "AccountMembership" datatype. See the section on "Resource Datatypes and Metatdata" for more information. Also see "Response Representations" for more information about how this resource method returns multiple data elements.

Supported Query Directives: _html

_fields, _collapse, _count, _items

Get Account Deactivate Reasons

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/deactivateReasons

Description:

Method : GET

Returns accepted account deactivation reasons used when deactivating account memberships.

Example of Response Body for Account Deactivate Reasons

{
    "count": 5,
    "items": [
        {
            "reason": "Organization Being Renamed",
            "code": 1
        },
        {
            "reason": "Organization Being Deactivated",
            "code": 2
        },
        {
            "reason": "Provider Changing Organizations",
            "code": 3
        },
        {
            "reason": "Provider Leaving Organization",
            "code": 4
        },
        {
            "reason": "Lost Or Stolen Private Key",
            "code": 5
        }
    ]
}

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data in key/value pairs; where the "reason" is the account deactivation reason and the "code" is a related code.

Supported Query Directives: _html

None

Get Account Credentials

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/credentials

Example of Response Body for Account Credentials

{
    "count": 22,
    "items": [
        {
            "name": "MD",
            "code": 1
        },
        {
            "name": "MBBS",
            "code": 2
        },
        {
            "name": "DO",
            "code": 3
        },
        {
            "name": "DMD",
            "code": 4
        },
        {
            "name": "OD",
            "code": 5
        },
        .
        .
        .
    ]
}

Description:

Method : GET

Returns accepted account credentials used when creating or modifying organization memberships.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data in key/value pairs; where the "name" is the account credential and the "code" is a related code.

Supported Query Directives: _html

None

Get Account Specialties

URL:

https://api.medalliesdirect.com:9543/OnBoard/services/v1/accounts/specialties

Example of Response Body for Account Specialties

{
    "count": 838,
    "items": [
        {
            "name": "Acupuncturist",
            "code": "171100000X"
        },
        {
            "name": "Adult Companion",
            "code": "372600000X"
        },
        {
            "name": "Advanced Practice Dental Therapist",
            "code": "125K00000X"
        },
        {
            "name": "Advanced Practice Midwife",
            "code": "367A00000X"
        },
        .
        .
        .
    ]
}

Description:

Method : GET

Returns accepted account specialties (based on NUCC data) used when creating or modifying organization memberships.

Successful Response Representation:

Returns an HTTP code of 200 (OK) and a response body containing the total number of resources, and a JSON representation of data in key/value pairs; where the "name" is the account specialty and the "code" is a related code.

Supported Query Directives: _html

None

Query Directives

For resources that support them (as documented by the resource below), the query string of the URL can contain one or more of the following directives which provide added instructions to the resource about the action being provided or the data to return.

_fields

This directive, when provided with a comma separated list of field names, will cause the resulting returned data to return only data for the specified fields. Note that it is not permissible to specify a field as collapsible and request one of its values in the same query. Sub-datatypes are supported by specifying them with a dot ("."), so for example, "vendor.name" will return only the organization's vendor's name. All datatypes that have an "id" field, will always return the datatype's id, regardless of the values supplied with _fields. This directive only affects items returned.

_collapse

This directive, when provided with a comma separated list of datatype field names will cause the resulting returned data to "collapse" to a shortened version of the specified sub-data. For example, the organization datatype has a sub-datatype of vendor. By default all the vendor information associated with a specific organization will be returned with the organization data. If the query includes this directive with a value of vendor, then the vendor data will be collapsed to a shortened form. All collapsed datatypes will minimally have a URI reference to the data that was collapsed.

Using a ‘*' for the value with _collapse will force all sub-entities to be returned collapsed if they support that feature.

Note: When combining _fields with _collapse, you must specify the collapsible field in the _fields list or that collapsed data will not be returned. Only the data specified in the _fields will be returned.

_count

Generally when retrieving a number of data from a resource, the resource will return a JSON object that contains the total count of data found for the request as well as a set of data (note that this set of data returned may be limited by providing other query directives as supported by the resource, such as _fields, and may be smaller than the total count returned). This directive will cause the resource to only return the total count of resources found.

_items

Generally when retrieving a number of data from a resource, the resource will return a JSON object that contains a set of data or "items" as well as the total count of data found for the request. This directive will cause the resource to only return those items the resource found based on any limiting criteria supplied by the initial request.

Resource Datatypes and Metadata

Each resource supports at least one specific datatype as documented for the specific resource below. For example the Organization Resource supports an "Organization" data type. The Metadata resource provides online documentation about each data type that the API supports. That information can be accessed at: /OnBoard/services/v1/metadata.

The Metadata resource also provides a method to return information about a supplied datatype; such as field names, descriptions of each field, whether the fields are required, optional, read only, as well as default values. This information can be used programmatically in calls to resource methods operating on that data type to validate the data before sending; and includes the fields that are returned by Get operations and consumed by Post operations, unless otherwise documented. This metadata is returned as a JSON object with the following format:

{
         "dataType":...
         "metadata":[
            {
               "fieldName":...,
               "idField":...,
               "description":...,
               "defaultValue":...,
               "valueOptions":[...],
               "fieldType":...,
               "fieldTypeMetadata":[...],
               "filterable":...,
               "addDataAttribute":...,
               "modifyDataAttribute...,
            },
            ...
         ]
      }

Metadata JSON Field Definitions

The metadata resource provides a programmatic way to request information about a resource datatype and use that information programmatically to process either the data sent or received. The following table shows how the "addDataAttribute" and "modifyDataAttribute" number values can be used to indicate how fields should be handled during add and modify operations.

About Id Fields

Any field marked as an id field, i.e. with an "idField" metadata value of true, is not allowed when creating new data; all ids for new data are generated with a successful create request. When modifying data, the id field is always required though it is not modifiable itself. However, any metadata that contains "fieldTypeMetadata" values with id fields, those id fields are generally required during add operations unless otherwise documented by the resource method below.

Filtering Searches

Resources that support filtering provide a "filterOn" parameter that is associated with zero or more filters. Field names that are filterable for a resource datatype can be composed from a request to the Metadata resource supplying that datatype as a parameter.

A filter is composed of three fields:

The filter method tells the filtering mechanism how to use the provided field value to limit the search. So for example a first name field can be matched using the supplied field value ("Sam") and a match method of "START" (id = 0) to search the first name data for all matches that begin with "Sam". When creating filters on datatype fields that are sub-datatypes, such as vendor inside of the Organization datatype, the full path to the field is required; for example "vendor.name", or "vendor.endpointType.code". Compound filters can be created by nesting filters and using a special FilterMethod for AND’ing or OR’ing together; see examples that follow. The following is a list of supported FilterMethods:

Filter Methods

Filter Examples

Filtering information should be provided as a JSON object in the resource’s POST request body. There are four types of JSON filter objects supported, they are:

Simple Filter (Note "fieldValues" can be any valid JSON datatype applicable to the supplied fieldName):
{
"filterOn":{
   "fieldName":"...",
   "fieldValues":["fieldValue1", "fieldValue2", ...], 
   "method":... FILTER METHOD CODE ...
}

Null/Not Null Filter (Note this kind of filter does not take fieldValues.):
"filterOn":{
   "fieldName":"...",
   "method":13   ‘NULL’ FILTER METHOD CODE
}

Range Filter (Note this kind of filter must have two fieldValues and requires the BETWEEN or NOT_BETWEEN FilterMethod):

"filterOn":{
   "fieldName":"...",
   "fieldValues":["fromFieldValue","toFieldValue"],
   "method":... FILTER METHOD CODE ...
}

Group Filter (Note the key word "filters" when combining filters with the FilterMethods AND or OR):

"filterOn":{
   "method":15, ‘AND’ FILTER METHOD CODE
   "filters":[
      {
         "method":... FILTER METHOD CODE ...,
         "fieldName":"...",
         "fieldValues":["fieldValue1", "fieldValue2", ...]
      },
      {
         "method":... FILTER METHOD CODE ...,
         "fieldName":"...",
         "fieldValues":["fieldValue1", "fieldValue2", ...]
       }
     ]
}

Possibilities Filter Error Codes

The following are possible error codes that can result from invalid filter data:

Errors

The REST API supports the following HTTP codes for errored situations:

JSON that is passed in to a REST resource that is invalid will result in an "errorCode" 108 "INVALID_JSON_SYNTAX". If a JSON value does not match a REST API datatype field’s datatype, such as passing a value in JSON as a Number for a field that is a Date, will result in an "errorCode" 109 "INVALID_JSON_DATATYPE". For a list of currently supported error codes and their error code strings see the Metadata Resource: ErrorCodes below.

For all error responses generated by a resource, the REST API returns a JSON object with the following structure:
{
    "errorCode":...an integer value code, 
    "message":...free form text message
}

The only exception to this is when an invalid parameter is sent in the request for a resource, in which case the JSON response will have the following structure:
{
    "errorCode":...an integer value code, 
    "message":...a pre-defined error code string,
    "parameterName":[...a JSONArray of invalid parameter names.]
}