Skip to content

Documents API

The IBM Food Trust™ Documents API allows authorized users to upload, view and share your organization's supply chain documents, such as facility certificates and audit reports.

Prerequisites

To use the IBM Food Trust Documents API, you must meet the following prerequisites:

  1. Your organization has subscribed to the Documents module.

  2. Your data integration experts are familiar with using REST APIs to send data programmatically. Automation of data upload is an ultimate goal to facilitate data sharing.

  3. For IBM Food Trust organizations to share supply chain data, each organization must have defined the appropriate level of data access control. For details on restricting and sharing your data, see Data entitlement mode and Data access control.

Getting started

Take the following steps to get started with the IBM Food Trust Documents API:

  1. Obtain an authentication token, as described in Authenticate human users and Authenticate system users.

  2. Submit a Documents API request by including the authentication token in the authorization header, as shown in the example request. For manual testing, human users can use Swagger to call the API endpoints.

  3. For help understanding the API response model, refer to the documentation below.

Swagger

To use the Documents API manually, use the Swagger interface for the following environments:

You must first provide a valid IBM Food Trust authorization token (human user token) on Swagger, using the Authorize button on the top right of the page.

Endpoints

All Documents API endpoints are documented in Swagger. With the required authorization, users can create, share, search, download and view documents.

For example, to create a new document an authorized user will call the following endpoints:

  • GET /templates/{documentType} - Retrieves a document type template for rendering and validating a document.
  • POST /documents - Creates and uploads a new document, with access permissions.

Request body

Use the following attributes to create and upload a new document (POST /documents endpoint):

  • properties - Information about the document (uploaded in JSON).
  • content - A content file in PDF, PNG, JPEG, or GIF format.
  • entitlement - Document access permissions. See Data entitlement mode and Data access control for details.

Parameters

The following parameters are used when calling applicable endpoints:

  • id - The system-generated document ID.
  • version - The document version. Versions of the same document will have an equivalent id.

Example Query

See Swagger for example requests and responses for each endpoint.