Requisition APIs (Scoped)

Ovation offers two kinds of APIs to create, read and update requisitions. This article describes the APIs that are scoped to a requisition template identifier specified in a URL parameter. Requisition APIs that are not scoped to a specific template are described in the article titled "Requisition APIs (Un-scoped)."

Below are the available scoped APIs for working with requisitions in Ovation.

• Get Requisitions
• Requisition JSON
• Get a Requisition
• Create a Requisition
• Update a Requisition
• Get Requisition Schema

Get Requisitions

Use this endpoint to get limited details for a selected set of requisitions.

HTTP Request

GET /api/v3/project_templates/{projectTemplateId}/requisitions      

Query Parameters

Response

The response includes an array containing the requisitions that satisfy the filter parameters provided, subject to pagination.

Example response payload:

{
  "requisitions": [
    {
      "id": 12345
      "identifier": "string",
      "requisition_template_id": 12345,
      "status": "processing",
      "accession_status": "incomplete",
      "processing_status": "unprocessed",
      "reporting_status": "not-started",
      "billing_status": "not-submitted",
      "created_at": "date string",
      "updated_at": "date string",
      "workflows": [
           {
           "id": 12345,
           "name": "string",
           "status": "completed",
           "workflow_definition_id": 12345,
           "created_at": "date string",
           "completed_at": "date string",
           "samples": [
                {
                "identifier": "string",
                "workflow_sample_result_ids": [
                     12345
                     ]
                 },
                 ...
                 ]
           },
           ...
      ]
    },
    ...
  ],
  "meta": {
    "currentPage": 1,
    "perPage": 5000,
    "totalEntries": 2
  }
}

Response

This endpoint can return the following responses:

Requisition JSON

Requisitions are represented in JSON as follows. This applies to the payload you provide for creating and updating requisitions, to the response payload for each of those operations, and to the response payload to when you get a requisition. There are a few differences among those cases, which are noted.

{
  "requisition": {
    "identifier": "Some Identifier",
    "requestedTests": [
      {
        "panelCode": "somePanelCode",
        "tests": [
          {
            "testCode": "someTestCode"
          },
          ...
        ]
      },
      ...
    ],
    "diagnosis": [
      "some ICD-10 code",
      ...
    ],
    "medications": [
      {
        "name": "some medication name",
        "rxcui": "some RXCUI"
      },
      ...
    ],
    "customAttributes": {
      "someAttributeKey": "some attribute value",
      ...
    },
    "patient": {
      "identifier": "string",
      "lastName": "string",
      ...
      "customAttributes": {
        "someAttributeKey": "some value",
        ...
      }
    },
    "providerAccount": {
      "name": "some provider account name",
      "accountNumber": "some provider account account"
    },
    "physician": {
      "npi": "some physician identifier"
    },
    "billingInformation": {
      "billTo": "string",
      ...
      "insuranceInformations": [
        {
          "insuranceProviderName": "Aetna health of California",
          ...
          "preAuthorization": {
            "authorizationNumber": "343432343",
          }
        },
        {
           ... repeat for secondary insurance
        }
      ]
    },
    "samples": [
      {
        "identifier": "sample identifier",
        ...
        "customAttributes": {
          "attributeKey": "some value",
          ...
        }
      },
      ...
    ],
    "workflows": [
      ...
    ],
    "hasSecondaryUseNotification": boolean,
    "secondaryUseEntitlements": "pipe-delimited list of entitlements",
    "hasMedicalConsent": boolean
  },
  "markAsSigned": boolean
}

Get a Requisition

HTTP Request

GET /api/v3/project_templates/{projectTemplateId}/requisitions/{requisitionIdentifier}      

Query Params

Response

This endpoint can return the following responses:

Create a Requisition

Use this endpoint to create a new requisition.

HTTP Request

POST /api/v3/project_templates/{projectTemplateId}/requisitions      

Query Parameters

Payload

Provide the requisition JSON as described above

Response

The Create Requisition API call can return the following possible responses:

Update a Requisition

Use this endpoint to update an existing requisition.

HTTP Request

PUT  /api/v3/projectTemplates/{projectTemplateID}/requisitions/{requisitionIdentifier}      

Query Params

Payload

Use the same payload as defined above for creating requisitions.

Response

This endpoint can return the following responses:

Using our REST API to retrieve Requisition Schema

HTTP Request

GET /api/v3/project_templates/{projectTemplateId}/requisition_schema      

Description

This API will return a JSON schema describing the JSON payload to be used when creating a requisition. The fields marked as required are required to complete a requisition (they are not requirements for a successful API call). These fields are determined from how the project template is configured in the LIMS.

Additionally any configured custom attributes will be present with their key.

The following fields, if configured, will include a list of valid options:

• panelCode
• group
• billTo
• label
• insuranceType
• containerType
• gender
• race
• ethnicity