Requisition APIs (Un-scoped)

Ovation offers two kinds of APIs to create, read and update requisitions. Those that are scoped to a specific requisition template with a URL parameter are described in the Requisition APIs (Scoped) article. This article describes the APIs that are not scoped to a requisition template. In many ways, these APIs work the same, so please refer to the "Requisition APIs (Scoped)" article for details that are shared. This article only describes the differences.

Get Requisitions

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

HTTP Request

GET /api/v3/requisitions

Query Params

Key	Required	Description
organizationId	Yes	The internal identifier for the organization. Copy this from the URL. (It's 123 in this example: https://lab.ovation.io/orgs/123/requisitions.) Note that this can also be provided as a URL parameter.
projectTemplateID	No	While this parameter is ignored by the scoped API; for the un-scoped API it optionally specifies the template by its identifier, which makes the un-scoped API work the same as the scoped one.

Get a Single Requisition

Use this API to get information about an existing requisition. This API is functionally equivalent to the template-scoped API because both explicitly specify the requisition itself.

HTTP Request

GET /api/v3/requisitions/{identifier}

Query Params

Key	Required	Description
identifier	Yes	The requisition's identifier
organizationId	Yes	The internal identifier for the organization. Copy this from the URL. (It's 123 in this example: https://lab.ovation.io/orgs/123/requisitions.) Note that this can also be provided as a URL parameter.

Create a Requisition

Use this API to create a requisition without explicitly specifying the template.

HTTP Request

POST /api/v3/requisitions

You can optionally specify the template in which to create the requisition (using the projectTemplateID field defined below), which makes this API functionally equivalent to the template-scoped one. But you can also omit the template and let the API infer the template to use. It infers the template, when it can, from the following considerations:

the specified provider account and the templates that provider account links to through the Order Forms feature;
the specified test panels and which templates are configured to allow those test panels; and
whether the requisition is specified to be a test requisition (using the testOrderFlag field) and which templates are identifiable as test templates (as described below).

Template Inference

First, these checks happen:

If there are no templates, an error is returned and the requisition is not created.
If there is exactly one template, that one will be used.
If the specified provider account has exactly one Order Form, the template linked to that Order Form will be used.

Then, all templates that allow all of the specified test panels are considered:

Validation templates are then excluded from consideration if testOrderFlag is true ; non-validation templates are excluded if it is false . (See the definition below for the testOrderFlag field for details.)
If there is exactly one template under consideration, that one will be used.
Otherwise, if there is one template under consideration that uses only exactly the specified test panels, that one will be used.
Otherwise, since there are multiple templates that could be used, the API will return an error and the requisition will not be created. In this case, you can use the projectTemplateID field in the request payload to explicitly identify the template to use.

Create Requisition Payload

The body of the request should contain the following JSON. The ellipses indicate that the fields specified for the scoped API are also available for this API.

{ 
	"organizationId": "676", 
	"testOrderFlag": false, 
	"requisition":  {
		...
		projectTemplateID: 12345
		...
	}
}

Field Name	Required	Description
organizationId	Yes	The internal identifier for the organization. Copy this from the URL. (It's 123 in this example: https://lab.ovation.io/orgs/123/requisitions.) Note that this can also be provided as a URL parameter.
testOrderFlag	No	Whether or not the requisition is a test. Set this field to `true` or `false`. The default is `false`. When this option is selected, only templates whose name contains "test" or "validation" (in any case) are considered in the inference logic. (And when it is not selected, those templates are not considered in that logic.)
projectTemplateID	No	The identifier of the template in which to create the requisition.

Create Requisition Response

This API can return the following response in addition to those returned by the template-scoped API.

Response Code	Response Body
404 Indicating that requisition was not created	Either {"error":"Multiple matching templates found, unable to determine match. Found [list of possible templates]."} or {"error":"Could not find matching template.}

Update a Requisition

Use this API to update an existing requisition.

HTTP Request

PUT /api/v3/requisitions/{identifier}

This API is functionally equivalent to the scoped API since the requisition is explicitly identified.