ArLIMS

Accessing the Order API

Authentication & authorization to the ArLIMS Order API follows a standard OAuth 2.0 OpenID Connect workflow.

Obtain your client credentials

If you have not yet been provided credentials by ArLIMS, please contact our support at support@arlims.com. Assuming that your association with an ArLIMS lab is verified, you will be provided a one-time-use link for setting up your client secret key.

Please note that this is the only time you will be shown your client credentials (your Client Id and Client Secret). Save these credentials in a secure location — you will need them to request an access token.

Request an Access Token

Authorization to an ArLIMS API endpoint is granted via an access token. To request an access token, your client application will issue a POST request to the following endpoint:

https://prodauth.arlims.com/connect/token

The following is a very basic example of using cURL to request an access token:

curl --request POST \
    --url 'https://prodauth.arlims.com/connect/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id=YOUR_CLIENT_ID \
    --data client_secret=YOUR_CLIENT_SECRET

A successful response will be very similar to the following example:

{
    "access_token": "********************",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "pgx"
}

Please note the expires_in value. Access tokens have a limited lifetime (currently, 3600 seconds, or one hour). Once an access token has expired, your application will need to request a new token.

Store the value of access_token. You will include this code in a BEARER authorization header for every request.

Create an Order

To create a new order, your client application will issue a POST request to the following endpoint,

https://prodapi.arlims.com/api/orders

Your request must contain a JSON-encoded instance of the Requisition model, shown here:

{
    "reorder": null,
    "labelOrigin": null,
    "sampleLabel": null,
    "sampleType": null,
    "sampleCollectionDate": null,
    "sampleCollectionInitials": null,
    "collectorCode": null,
    "billToOption": null,
    "facilityCode": null,
    "organizationCode": null,
    "organizationNPI": null,
    "providerNPI": null,
    "providerName": null,
    "providerPhone": null,
    "providerOther": null,
    "firstName": null,
    "lastName": null,
    "middleInitial": null,
    "dateOfBirth": null,
    "sex": null,
    "ethnicity": null,
    "raceOther": null,
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "cityQuadrant": null,
    "countyOrParish": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "emailAddress": null,
    "phone": null,
    "alternatePhone": null,
    "height": null,
    "weight": null,
    "medicalRecordNumber": null,
    "prisonerIdentification": null,
    "ssNorITIN": null,
    "identificationNumber": null,
    "identificationState": null,
    "acknowledgementReceived": null,
    "dateAcknowledgementReceived": null,
    "acknowledgementText": null,
    "races": [],
    "diagnosisCodes": [],
    "medicationsPrescribed": [],
    "medicationsToEvaluate": [],
    "testPanels": [],
    "policies": [],
    "questions": [],
    "attachments": []
}

The following is an example of a valid request object.

{
    "reorder": "false",
    "labelOrigin": "ARL",
    "sampleLabel": "173340598",
    "sampleType": "NSL",
    "sampleCollectionDate": "08/18/2021",
    "sampleCollectionInitials": null,
    "collectorCode": null,
    "billToOption": "FP",
    "facilityCode": "Test",
    "organizationCode": "CITYH01",
    "organizationNPI": "1285605444",
    "providerNPI": "1487966412",
    "firstName": "Carl",
    "lastName": "Sagan",
    "middleInitial": null,
    "dateOfBirth": "06/01/1970",
    "sex": "M",
    "ethnicity": "N",
    "raceOther": null,
    "addressLine1": "123 Example Drive",
    "addressLine2": null,
    "city": "Examplesville",
    "cityQuadrant": "NE",
    "countyOrParish": null,
    "state": "WA",
    "postalCode": "12345",
    "country": "USA",
    "emailAddress": "carl.sagan@example.com",
    "phone": "123-123-1234",
    "alternatePhone": null,
    "height": "73",
    "weight": "215",
    "medicalRecordNumber": "CS123123123",
    "prisonerIdentification": null,
    "ssNorITIN": null,
    "identificationNumber": null,
    "identificationState": null,
    "acknowledgementReceived": null,
    "dateAcknowledgementReceived": null,
    "acknowledgementText": null,
    "races": ["2106-3"],
    "diagnosisCodes": [],
    "medicationsPrescribed": ["Tylenol"],
    "medicationsToEvaluate": ["aspirin"],
    "testPanels": ["TESTONE"],
    "policies": [],
    "attachments": []
}

The following is a very basic example of using cURL to create an order, using the above example:

curl --request POST \
    --url 'https://prodapi.arlims.com/api/orders' \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "reorder": "false", "labelOrigin": "ARL", "sampleLabel": "173340598", "sampleType": "NSL", "sampleCollectionDate": "08/18/2021", "sampleCollectionInitials": null, "collectorCode": null, "billToOption": "FP", "facilityCode": "Test", "organizationNPI": "1285605444", "providerNPI": "1487966412", "firstName": "Carl", "lastName": "Sagan", "middleInitial": null, "dateOfBirth": "06/01/1970", "sex": "M", "ethnicity": "N", "raceOther": null, "addressLine1": "123 Example Drive", "addressLine2": null, "city": "Examplesville", "cityQuadrant": "NE", "countyOrParish": null, "state": "WA", "postalCode": "12345", "country": "USA", "emailAddress": "carl.sagan@example.com", "phone": "123-123-1234", "alternatePhone": null, "height": "73", "weight": "215", "medicalRecordNumber": "CS123123123", "prisonerIdentification": null, "ssNorITIN": null, "identificationNumber": null, "identificationState": null, "races": ["2106-3"], "diagnosisCodes": [], "medicationsPrescribed": ["Tylenol"], "medicationsToEvaluate": ["aspirin"], "testPanels": ["TESTONE"], "policies": [], "attachments": [] }' \

For the above example, substitute your access token for ACCESS_TOKEN.

A successful response will be very similar to the following:

{
    "transactionCode": "f022679a-0ec9-41b4-b8bc-6900e704763c",
    "status": "Received"
}

A failed response will contain a list of error messages in the errors property:

{
    "errors": [{
        "code": "ERR",
        "message": "Sample label is invalid"
    }]
}

Update an Order

NOT SUPPORTED

Updating an order is not currently supported by the ArLIMS API. Please contact your lab administrator if an order must be updated.

Request Order Details

To request the current state of an order, your client application will issue a GET request to the following endpoint,

https://prodapi.arlims.com/api/orders/{id}

where {id} is a transaction code for a previously-placed order. Your client can only request the details of orders which you have created.

The following is a very basic example of using cURL to request the details of an order:

curl --request GET \
    --url https://prodapi.arlims.com/api/orders/00000000-0000-0000-0000-000000000000 \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json'

For the above example, substitute your access token for ACCESS_TOKEN.

A successful response will be very similar to the following:

{
    "status": "Completed",
    "transactionCode": "00000000-0000-0000-0000-000000000000",
    "order": {
        "reorder": null,
        "labelOrigin": "ARL",
        "sampleLabel": "123456789",
        "sampleType": "BCLSWB",
        "sampleCollectionDate": "2014-03-12T00:00:00.0000000",
        "sampleCollectionInitials": "ARL",
        "collectorCode": null,
        "facilityCode": null,
        "billToOption": "IB",
        "organizationCode": "HOSPI01",
        "organizationNPI": "1231231234",
        "providerNPI": "8765309",
        "firstName": "Example",
        "lastName": "Patient",
        "middleInitial": "M",
        "dateOfBirth": "1999-11-26",
        "sex": "M",
        "ethnicity": "U",
        "raceOther": null,
        "addressLine1": null,
        "addressLine2": null,
        "city": null,
        "cityQuadrant": null,
        "countyOrParish": null,
        "state": null,
        "postalCode": null,
        "country": "United States",
        "emailAddress": null,
        "phone": null,
        "alternatePhone": null,
        "height": null,
        "weight": null,
        "medicalRecordNumber": null,
        "prisonerIdentification": null,
        "ssNorITIN": null,
        "identificationNumber": null,
        "identificationState": null,
        "races": ["2054-5","2106-3"],
        "diagnosisCodes": [],
        "medicationsPrescribed": [],
        "medicationsToEvaluate": ["Norco"],
        "testPanels": ["FULLPGX"],
        "policies": [{
            "payer": {
                "code": "EXP",
                "name": "Example Payer",
                "addressLine1": "123 Example Lane",
                "addressLine2": null,
                "city": "Examplesville",
                "state": "GU",
                "postalCode": "00002",
                "country": "U.S.A.",
                "phone": null
            },
            "accountNumber": "D8EED6BF-024E-4E3C-AB35-47C51F6BEB14",
            "groupNumber": null,
            "relationship": "SPNDEP",
            "firstName": null,
            "lastName": null,
            "middleInitial": null,
            "dateOfBirth": null,
            "attachments": null
            }],
        "attachments": null
    },
    "result": "OMITTED",
    "errors": null
}

A failed response will contain a list of error messages in the errors property:

{
    "errors": [{
        "code": "ERR",
        "message": "Transaction code is invalid"
    }]
}

Request Status of an Order

To request the current status of an order, your client application will issue a GET request to the following endpoint,

https://prodapi.arlims.com/api/orders/status/{id}

where {id} is a transaction code for a previously-placed order. Your client can only request the status of orders which you have created.

The following is a very basic example of using cURL to request the status of an order:

curl --request GET \
    --url https://prodapi.arlims.com/api/orders/status/00000000-0000-0000-0000-000000000000 \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json'

For the above example, substitute your access token for ACCESS_TOKEN.

A successful response will be very similar to the following example,

{
    "transactionCode": "00000000-0000-0000-0000-000000000000",
    "status": "Unknown"
}

where status will be one of the values shown below.

• Unknown
• Pending Approval
• Declined
• Received
• In Progress
• Recalled
• Consult Requested
• Completed

Requesting Status of All Orders

NOT SUPPORTED

Requesting the status of all orders is not currently supported by the ArLIMS API. Please contact your lab administrator if you need to fetch the status of more than one order at a time.

Remove an Order

NOT SUPPORTED

Removing an order is not currently supported by the ArLIMS API. Please contact your lab administrator if an order must be removed.

API Models

The following document defines the data structures for sending requests to the Order API.

Requisition

The Requisition model is defined as follows and constitutes the core model for all order create and update requests.

{
    "reorder": null,
    "labelOrigin": null,
    "sampleLabel": null,
    "sampleType": null,
    "sampleCollectionDate": null,
    "sampleCollectionInitials": null,
    "collectorCode": null,
    "billToOption": null,
    "facilityCode": null,
    "organizationCode": null,
    "organizationNPI": null,
    "providerNPI": null,
    "providerName": null,
    "providerPhone": null,
    "providerOther": null,
    "firstName": null,
    "lastName": null,
    "middleInitial": null,
    "dateOfBirth": null,
    "sex": null,
    "ethnicity": null,
    "raceOther": null,
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "cityQuadrant": null,
    "countyOrParish": null,
    "state": null,
    "postalCode": null,
    "country": null,
    "emailAddress": null,
    "phone": null,
    "alternatePhone": null,
    "height": null,
    "weight": null,
    "medicalRecordNumber": null,
    "prisonerIdentification": null,
    "ssNorITIN": null,
    "identificationNumber": null,
    "identificationState": null,
    "acknowledgementReceived": null,
    "acknowledgementReceivedDate": null,
    "acknowledgementText": null,
    "races": [],
    "diagnosisCodes": [],
    "medicationsPrescribed": [],
    "medicationsToEvaluate": [],
    "testPanels": [],
    "policies": [],
    "questions": [],
    "attachments": []
}

If a request includes patient insurance information (the policies property of the Requisition model), each policy will use the Policy and Payer models shown below.

Policy

A Policy encapsulates the minimum data necessary to transmit insurance billing information, as shown here:

{
    "payer": null,
    "accountNumber": null,
    "groupNumber": null,
    "relationship": null,
    "firstName": null,
    "lastName": null,
    "middleInitial": null,
    "dateOfBirth": null,
    "attachments": []
}

Payer

The Payer is the insurance provider for this policy. Your lab has a number of payers already defined, and can be retrieved using the Lookups API. See Requesting Lookup Codes for help requesting payers.

{
    "code": null,
    "name": null
}

To use an existing payer, provide a value for the code property. To use a custom payer, omit code and provide a value for name. For example:

Existing payer

{
    "code": "BCBSMI" 
}

Custom payer

{
    "name": "Blue Cross/Blue Shield of Michigan" 
}

Ask on Order Entry (AOE) Questions

One or more tests may require additional information to be provided. These are defined as "Ask on Order Entry" (AOE) questions, and can be retrieved using the Lookups API. See Requesting Lookup Codes for help requesting the current AOE questions.

When requesting the current set of questions, you will receive a response in this format:

{
    "code": "0000-1",
    "name": "Question Text Here",
    "values": []
}

If the question requires one or more selections from a list of options, those options are included in the values property:

{
    "code": "Option Value Here",
    "name": "Option Text Here"
}

Your response must match one of the option values or will be rejected.

The response model for a question response is defined as such:

{
    "code": null,
    "value": null
}

The code property must be one of the Code values for a question returned by the questions lookup. The value property denotes the response value to be included in the request.

For questions which require one or more selections from a list of options, include a new response for each selected option:

{
    "questions": [{
        "code": "00000-0",
        "value": "1"
    }, {
        "code": "00000-0",
        "value": "2"
    },

    /* ...more options... */

    , {
        "code": "00000-0",
        "value": "n"
    }]
}

Attachments

You may attach one or more files to an order or to a policy, using the attachments property on the relevant object. An attachment must use this model:

{
    "title": null,
    "fileName": null,
    "fileData": null,
    "contentType": null,
}

The fileName, fileData, and contentType fields are required. The fileData field must be a Base64-encoded string. If provided, title will be used when displaying the attachment within the ArLIMS application - if omitted, the fileName value will be used instead.

Table Lookups

ArLIMS provides an API to allow a client to request the message codes used in a valid Requisition object. Each of the tables below can be requested issuing a GET request to the API endpoint

https://prodapi.arlims.com/api/tables/{names}

where {names} is a comma-separated list of tables to request.

Supported lookup names

The following is a very basic example of using cURL to request lookup values:

curl --request GET \
    --url https://prodapi.arlims.com/api/tables/facilities \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json'

A successful response will have a message body similar to the following:

{
    "requestedNames": [ "facilities" ],

    "tables": [{
        "key": "facilities",
        "values": [{
            "code": "FAC1",
            "name": "Facility 1"
        },
        {
            "code": "FAC2",
            "name": "Facility 2"
        }]
    }],

    "errors": null,
    "warnings": null
}

Any value found in {names} which does not correspond to a valid lookup key will be noted in the "warnings" property of the response.

Add Consult Document to an Order

ArLIMS provides an API to allow a client to add a new consult document to an order by issuing a POST request to the API endpoint

https://prodapi.arlims.com/api/documents

Your request must contain a JSON-encoded instance of the PutDocumentRequest model, shown here:

{
    "transactionCode": null,
    "fileLabel": null,
    "fileName": null,
    "contentType": null,
    "fileData": null
}

The fileData property must be a Base64-encoded string of the file's binary data.

The following is a very basic example of using cURL to create a new document:

curl --request POST \
    --url https://prodapi.arlims.com/api/documents \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "transactionCode": "00000000-0000-0000-0000-000000000000", "fileLabel": "Provider Consult File", "fileName": "provider-consult-file.pdf", "contentType": "application/pdf", "fileData": OMITTED }' \

For the above example, substitute your access token for ACCESS_TOKEN.

A successful response will have a message body similar to the following:

{
    "transactionCode": "00000000-0000-0000-0000-000000000000",
    "responseCode": "RECEIVED",
    "errors": null,
    "warnings": null
}

Requesting New Consult Documents for an Order

ArLIMS provides an API to allow a client to request a list of new consult documents for an order by issuing a GET request to the API endpoint

https://prodapi.arlims.com/api/documents/{id}

where {id} is a transaction code for a previously-placed order. Your client can only request documents for orders which you have created.

The following is a very basic example of using cURL to request new documents:

curl --request GET \
    --url https://prodapi.arlims.com/api/documents/00000000-0000-0000-0000-000000000000 \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json'

For the above example, substitute your access token for ACCESS_TOKEN.

A successful response will have a message body similar to the following:

{
    "transactionCode": "00000000-0000-0000-0000-000000000000",
    "files": [{
        name: "additional-patient-file.pdf",
        label: "Additional Patient File",
        contentType: "application/pdf",
        encodedData: "... base64-encoded string..."
    }],
    "errors": null,
    "warnings": null
}

For the above example, the encodedData property of each file will be a Base64-encoded string of the file's binary data.