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

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

HTTP Request

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

Query Parameters

Key Required Description
projectTemplateId yes Internal project template identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
startDate no

Starting date time in organization timezone. If no time is supplied will assume 00:00:00

ex: 2020-08-22T08:00:00.000Z or 2020-08-22

endDate no

Ending date time in organization timezone. If no time is supplied will assume 00:00:00

ex: 2020-08-22T23:59:59.000Z or 2020-08-22

accessionStatus no
Comma-delimited lists of accession status values to filter the returned list of requisitions
See Requisition JSON below for possible values
reportingStatus no
Comma-delimited lists of reporting status values to filter the returned list of requisitions

See Requisition JSON below for possible values

processingStatus no
Comma-delimited lists of processing status values to filter the returned list of requisitions

See Requisition JSON below for possible values
billingStatus no
Comma-delimited lists of billing status values to filter the returned list of requisitions

See Requisition JSON below for possible values

overallStatus no
Comma-delimited lists of overall status values to filter the returned list of requisitions

See Requisition JSON below for possible values (for the status attribute)
page no

Page number being requested


Defaults to page 1 if not supplied

perPage no

Number of requisitions per page


Maximum of 5000 and defaults to 5000 if not supplied

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:

Response code Response body
200 to indicate success JSON describing the requested provider accounts
401 to indicate an authentication error

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
}
Field name Description
identifier The requisition's identifier

If the project template is configured to autogenerate identifiers, this attributes is ignored when creating a requisition -- the autogenerated identifier isused. Otherwise, you must provide an identifier to create a requisition.

This attribute is ignored when updating a requisition.
requestedTests An array that represents the requested test panels for the requisition

Requisitions must have at least one test panel.
requestedTests[].panelCode The test panel code for a test panel in the requestedTests array
requestedTests[].tests[] An array that represents the selected tests for a test panel in the requestedTests array
requestedTests[].tests[].testCode The test code for a selected test in the requestedTests.tests array
diagnosis An array of ICD-10 diagnosis codes
medications
An array of medications
medications[].name
The name of a medication in the medications array

This is not used when creating or updating requisitions, but will be returned in the response payload and when getting requisitions.
medications[].rxcui
The RXCUI of a medication in the medications array
customAttributes
A list of pairs of custom attribute keys and custom attribute values

"customAttributes": {
  "key1": "value1",
  ...
}
		
status The requisition's overall status

Possible values:
    received
    held
    processing
    complete
    delivered
    deliver_modified
    canceled
    draft

This attribute is determined by the application (and ignored if provided when creating or updating a requisition).

accessionStatus The requisition's accession status

Possible values:
    incomplete
    complete
    signed

This attribute is determined by the application (and ignored if provided when creating or updating a requisition).

processingStatus The requisition's processing status

Possible values:
    held
    unprocessed
    processing
    complete

This attribute is determined by the application (and ignored if provided when creating or updating a requisition).

billingStatus The requisition's billing status

Possible values:
    not-submitted
    ready-to-submit
    submitted
    submit-failed
    reimbursed
    rejected
    error
    denial

This attribute is determined by the application (and ignored if provided when creating or updating a requisition).

reportingStatus The requisition's reporting status

Possible values:
    sent-for-generation
    generation-failed
    generated
    approved
    signed
    downloaded
    rejected

This attribute is determined by the application (and ignored if provided when creating or updating a requisition).

patient.lastName The patient's last name
patient.firstName The patient's first name
patient.streetAddress
The first line of the patient's street address
patient.streetAddressLine2
The second line of the patient's street address
patient.customAttributes A list of pairs of custom attribute keys and custom attribute values

"customAttributes": {
  "key1": "value1",
  ...
}
		
patient.city
The patient's city
patient.state
The patient's state
patient.zipCode
The patient's postal code
patient.dateOfBirth
The patient's date of birth in YYYY-MM-DD format
patient.phoneNumber
The patient's phone number
patient.email
The patient's email
patient.gender
The patient's gender: “M” or “F” or “U”
patient.ethnicity
The patient's ethnicity: "hispanic" or "nothispanic"  or "undisclosed"
patient.race
The patient's race: "white" or "black" or "asian" or "islander" or "native" or "undisclosed"
providerAccount.name
The provider account's name
providerAccount.accountNumber
The provider account's account number
physician.npi
The identifier of the provider

This must be a value NPI in the case of the NPPES registry. For other registries, it can be any string.
billingInformation.billTo
"Bill Insurance", “Patient Pay”, “Facility Pay” or “Other”
The insuranceInformations[]array is only used when billingInformation.billTo is set to "Bill Insurance". billingInformation attributes (billingInformation.memberId below, etc) are only used when billingInformation.billTo is not set to "Bill Insurance"
billingInformation.memberId
Patient/institutional bill-to member ID
billingInformation.name
Patient/institutional bill-to name
billingInformation.email
Patient/institutional bill-to email
billingInformation.phoneNumber
Patient/institutional bill-to phone number
billingInformation.street
Patient/institutional bill-to street address
billingInformation.city
Patient/institutional bill-to city
billingInformation.state
Patient/institutional bill-to state
billingInformation.zip
Patient/institutional bill-to postal code
insuranceInformations
insuranceInformations[].insuranceProviderName
The insurance provider's name

When creating or updating a requisition, this must match one of the defined insurance provider names available to the organization.
insuranceInformations[].subscriberNumber
The insurance subscriber number
insuranceInformations[].idNumber
The insurance id number
insuranceInformations[].groupNumber
The insurance group number
insuranceInformations[].nameOfPersonInsured
The name of the insured
insuranceInformations[].relationshipToInsured
The relationship of the patient to the insured

Possible values: "Self", "Spouse", "Life partner","Child","Ward","Handicapped Dependent","Sponsored Dependent","Dependent of a minor Dependent" or "Other"
insuranceInformations[].dobOfInsured
Insured's date of birth
insuranceInformations[].insuranceType
"Primary" or “Secondary”
insuranceInformations[].preAuthorization.authorizationNumber
Preauthorization authorization number
insuranceInformations[].preAuthorization.numTests
Number of preauthorized tests
insuranceInformations[].preAuthorization.effectiveStartDate
Start of preauthorization period formatted as YYYY-MM-DD
insuranceInformations[].preAuthorization.effectiveEndDate
End of preauthorization period formatted as YYYY-MM-DD
insuranceInformations[].preAuthorization.contactName
Contact name for preauthorization
insuranceInformations[].preAuthorization.contactPhoneNumber
Contact phone number for preauthorization
samples
An array of samples for the requisition
samples[].identifier
The sample identifier for one of the samples in the samples array

When creating a requisition or adding a sample to a requisition (when updating a requisition), you must provide a unique sample identifier even if the project template is configured to autogenerate sample identifiers in the application.
samples[].group
The sample group for one of the samples in the samples array

Samples must always be in a group
samples[].label
The sample type for one of the samples in the samples array

You must provide this value when creating or updating a requisition.
This value is not provided on get or in response to creating or updating.
samples[].containerType
The container type for one of the samples in the samples array
samples[].containerBarcodeLabel
The container barcode label for one of the samples in the samples array
samples[].receivedDateTime
The timestamp when one of the samples in the samples array was received in ISO 8601 format
samples[].collectionDateTime
The timestamp when one of the samples in the samples array was collected in ISO 8601 format
samples[].customAttributes
A list of pairs of custom attribute keys and custom attribute values

"customAttributes": {
  "key1": "value1",
  ...
}
		
workflows[] An array of workflows that included any sample in the requisition. The structure of each is as described in the Get Workflow API, but only the samples in the requisition are included.
signedConsent deprecated Use hasSecondaryUseNotification instead.

Setting signedConsent to true is the same as setting hasSecondaryUseNotification to 1; setting signedConsent to false is the same as setting hasSecondaryUseNotification to 0.
hasMedicalConsent Indicates if medical consent has been given for the sample(s) on the requisition.

0: medical consent has been given
1: medical consent has not been given
3: whether or not medical consent has been given is unknown
hasSecondaryUseNotification Indicates if patient has been notified of secondary use.

0: patient not notified
1: patient notified
2: patient notified but has opted out of one or more entitlements (in which case, you must also provide secondaryUseEntitlements as described below)
3: whether or not the patient was notified is unknown
secondaryUseEntitlements In the case where hasSecondaryUseNotification is set to 2, this field represents the list of entitlements opted into, each separated by the “|” character, among these possible values:

can-use-specimen
can-use-clinical-data
can-recontact-patient

For example: can-use-specimen|can-use-clinical-data|can-recontact-patient
markAsSigned If set as true and all required fields for the requisition have been sent, then the accession status will be set to “signed”.
reports An array of reports in the requisition
reports[].status
This is the "Overall Status" seen in the application. Possible values:
  • sent-for-generation
  • generation-failed
  • generated
  • approved
  • signed
  • downloaded
  • rejected

The reports array, if provided, is ignored when creating or updating requisitions.

reports[].result Result of report if available (positive, negative, etc.)
reports[].documentName PDF Document Name
reports[].displayName Display name for report
reports[].downloadLink The path to PDF Report in S3
reports[].sampleIdentifier Sample Identifier

Drop from documentation? It's redundant
reports[].createdDate The date the report was created
reports[].sampleTatHours Hours it took for the sample to be processed
reports[].signedBy An array that lists all of the users that signed the report
reports[].workflowId ID for workflow report was generated from
reports[].workflowName Name of workflow report was generated from

Get a Requisition

HTTP Request

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

Query Params

Key Required Description
projectTemplateID yes Internal project template identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
requisitionIdentifier yes The identifier of the requisition to be updated

Response

This endpoint can return the following responses:

Response code Response body
200 to indicate success JSON describing the requested requisition; refer to the description of the inbound payload above
401 to indicate an authentication error

Create a Requisition

Use this endpoint to create a new requisition.

HTTP Request

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

Query Parameters

Key Required Description
projectTemplateId yes Internal project template identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)

Payload

Provide the requisition JSON as described above

Response

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

Response Code Response Body
201 to indicating that the requisition was successfully created The requisition will return the original requisition data entered
{"requisition":{"id":26355,"identifier":"COVID-107", ....
401 to indicate an authentication error  
404 to indicate that the project template id was not found
422 to indicate a validation error JSON description of the error


Update a Requisition

Use this endpoint to update an existing requisition.

HTTP Request

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

Query Params

Key Required Description
projectTemplateID yes Internal project template identifier. Copy from URLs. (It's the 789 in this example: https://lab.ovation.io/orgs/123/projects/456/requisition-settings/789/template-information.)
requisitionIdentifier yes The identifier of the requisition to be updated

Payload

Use the same payload as defined above for creating requisitions.

Response

This endpoint can return the following responses:

Response code Response body
200 to indicate that the requisition was successfully created JSON describing the updated requisition
401 to indicate an authentication error   
404 to indicate that the requisition or project template was not found
406 to indicate unacceptable values "Update may not change sample date received"
"You don't have the right permissions to change a requisition identifier, sample identifier or container ID"
"Missing organization time zone"
422 to indicate an error with the request contents A JSON description of the validation error

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