Submit an Order & Metadata Components

Prerequisites 

Project Key

Each order must be associated with a project key which is recognized by the development team. Project keys for both the staging and production environments will be provided by our team. Reach out to [e-mail] if you do not know your project key.

Actor-Email

You must include an Actor-Email header which lists as its value the email address of the “actor” making the request when making API requests to any endpoint which requires it. 

The API checks this email address against our database and ensures that the user has an active account with sufficient permissions to perform the action. For more information on User Accounts see this help article here. 

To see an actor’s user account information, you can run the following cURL command:

Staging: curl -H "Authorization: Bearer {token}" -H “Actor-Email: {[e-mail]}” https://gpo-staging.broadinstitute.org/auth

Production: curl -H "Authorization: Bearer {token}" -H “Actor-Email: {[e-mail]}” https://gpo.broadinstitute.org/auth

Submit an Order

For the production environment, the primary endpoint you will use to submit orders is:

• https://gpo.broadinstitute.org/redoc#tag/Orders-and-Samples/operation/postOrder

 Each order specifies:

• An indication of which test or tests are to be run on each sample.
  • You can obtain a list of all valid test codes and supported options here.
  • Validations are performed based on the test selected and will provide feedback if any submissions are invalid. See Understanding Errors for more detail.
• The barcodes of the test tubes containing the samples.
• Sample and demographic information about the patients whose samples were submitted. 

You can also provide IDs which reference the orders and samples in your system. If you provide “external” IDs as the Sample_ID, we will store them and return them to you when querying for the status of your orders.

Metadata Components

Many of the entities in the API support metadata, which is where most of the demographic information is defined. The API documentation does not specify which metadata is available, as this list is dynamic and can change over time and for different use cases.

Each metadata field has the following attributes:

• name: The key you will use when providing metadata in the API, such as first_name.
• description: A description of the metadata field.
• allow_multiple: Specifies whether or not this field supports multiple values. In the API, each metadata field will always be represented as an array of values, for convenience, but for single-valued fields the array will only contain a single element.
• type: The type of field. When used in the API, metadata will always be expressed in a string representation, but will be converted to the appropriate type when it is stored in the order database. The type will be one of:
  • string, a text field, limited to 255 characters
  • email, a text field validated as an email address
  • float
  • integer
  • boolean, expressed as true or false. You can also use 1 or 0
  • datetime, expressed in a valid ISO 8601 format:
    • yyyy-mm-dd (will be placed at midnight UTC)
    • yyyy-mm-ddTHH:MM:SS (will be assumed to be UTC)

• yyyy-mm-ddTHH:MM:SSZ (UTC)
• yyyy-mm-ddTHH:MM:SS±zz:zz (will retain the timezone)

A complete list of all valid metadata fields for each entity type can be found below: 

• Orders
• Samples
• Patients