Start a bulk FHIR import job

This API call lets you perform a NCPI FHIR Document Reference bulk import.

Before you start using this API call, please read the following important notes:

You can only use this endpoint if you obtain OAuth 2.0 access token.
The maximum number of items to import per single API call is 100.
The rate limit for this API call is 1000 bulk requests in 5 minutes.

https://cavatica-api.sbgenomics.com/v2/bulk/fhir

Request

Example request

POST v2/bulk/fhir  HTTP/1.1
Host: cavatica-api.sbgenomics.com
Authorization: Bearer <token>
Content-Type: application/json
X-SBG-Advance-Access: Advance

curl --data '@import.json' -X POST -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "Content-Type: application/json" 'https://cavatica-api.sbgenomics.com/v2/bulk/drs/imports/create HTTP/1.1'

Header Fields

Key	Description of value
`Authorization` required	Standard OAuth 2.0 access token obtained through OAuth 2.0 handshake.
`Content-type` required	Use `application/json`
`X-SBG-Advance-Access` required	A special header for advanced access permissions

Request body

Key	Data type	Description of value
`items`	Object	Contains details about each of the import items. See the rows below for details.
`fhir_document_reference`	String	FHIR URI of the FHIR DocumentReference that you want to import, for example `https://hapi.fhir.org/baseR4/DocumentReference/44765605`
`parent`	String	The ID of the target folder to which the item should be imported, for example `568cf5dce4b0307bc0462060` Should not be used together with project. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs. If project is used, the items will be imported to the root of the project's files.
`project`	String	The project in which to import the file. Should be specified in the username/project-slug format, for example `rfranklin/my-project`.
`name`	String	The name of the file when imported to the destination. If the name is already in use in the project, the rule defined in `conflict_resolution` will apply.
`metadata`	Object	Consists of key-value pairs of metadata fields that should be assigned to the imported files. Learn more
`conflict_resolution`	String	Action to take if a file with the same name already exists in the project. Available values: `OVERWRITE` `AUTORENAME` `SKIP` Default: `SKIP`
`tags`	Array of strings	Tags that will help label and differentiate the imported files in the project. Learn more

Example request body

{
	"conflict_resolution": "SKIP",
	"items": [
    {
      "fhir_document_reference": "https://hapi.fhir.org/baseR4/DocumentReference/44765605",
      "project": "rfranklin/fhir-import/",
      "name": "test-file.ext",
      "metadata": {
        "study_id": "1",
        "cohort": 4
			}
	}
  ],
	"tags": [
		"INCLUDE"
	]
}

Response

See a list of CAVATICA-specific response codes that may be contained in the body of the response.

Response body

The response object contains the link for downloading the file.

Key	Data type	Description
`id`	String	ID of the import job.
`state`	String	Current state of the import job. Available values: `SUBMITTED` `RUNNING` `FINISHED`

Key

Data type

Description

id

String

ID of the import job.

state

String

Current state of the import job. Available values:

SUBMITTED
RUNNING
FINISHED

Example response body

{
    "id": "12ed92ac-5265-4cf2-8885-46ae1b36c2c2",
    "state": "SUBMITTED"
}