Zum Hauptinhalt springen

Integration Guide

For a smooth and easy integration, please refer to the detailed workflow.

The accompanying diagram illustrates the workflow and highlights the essential steps necessary to successfully integrate the SAFE API.

SAFE workflow

Setup​

In order to use the SAFE API, an organization must be created. Within this organization, it is necessary to create an API Key. Please send along the API Key and the organization ID.

Step 1: Authentication​

In order to access the API, you need a valid JWT access_token. Use the retrieveToken endpoint to create the access token. Via the scope_id you can define where a resource is created.

Step 2: Create a configuration​

Use the createConfiguration endpoint to define the country of storage location.

Step 3: Create an annotation​

The annotation is used in order to categorize files. Use the createAnnotation endpoint in order to create an annotation. The annotation_id uniquely defines a file resource by using a UUIDv4.

Step 4: Archive a file​

Use the archiveFile endpoint to archive a file. The request consists of two parts:

  • the archive_file_request (contains information about the file) &
  • the file itself Before archiving a file, it is necessary to have already created an annotation.

Step 5: Search files​

Use the createSearch endpoint in order to search for particular files. This request is being processed asynchronously. The logical_operator is used to connect the argument arrays. The state of the search query can be checked via the retrieveSearchQuery endpoint. Once the request has been processed, the files can be retrieved via the retrieveSearchQueryResults endpoint.

Step 6: Create an export​

In order to create an export, use the createExport endpoint. The export_id must be a UUIDv4 created on your end. This request is being processed asynchronously. An export’s status can be checked via the retrieveExport endpoint. Once it has been processed successfully (state: PROCESSED), the response includes a download link. In order to download a stream containing export data of a processed export, use the downloadExport endpoint.