Getting started

The DocuShield API lets your systems file non-transferable records, read your organisation's documents, verify documents and receive signed webhooks. Transferable records (electronic bills of lading, bills of exchange and promissory notes) are issued and transferred in the DocuShield app, by a signed-in person with their own wallet. See Transferable records.

Base URL: https://app.docushield.live/api/v1

The example on the app's API Keys page shows a different address. Use the one above.

1. Create a key

Sign in at app.docushield.live as an admin of your organisation, open API Keys and choose New API Key. You need to have accepted the current Terms of Service and Privacy Policy. Start with a Sandbox key: it begins with sk_test_. The key is shown once, so store it as a secret.

A sandbox key is not isolated from production: it can read a production record by its id, manage webhooks and create a production key. Protect it as you would a production key.

2. Make your first call

export DOCUSHIELD_API_KEY="sk_test_..."
curl "https://app.docushield.live/api/v1/ebl" \
  -H "Authorization: Bearer $DOCUSHIELD_API_KEY"

The response has data, a list of your organisation's documents with the newest first, and pagination with page, limit, total and pages. Add ?page=2&limit=50 to move through the list. limit is 25 unless you set it, and at most 100.

3. File a record

curl -X POST "https://app.docushield.live/api/v1/ebl" \
  -H "Authorization: Bearer $DOCUSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blNumber":"DS-TEST-001","shipperName":"Example Exporter Ltd","consigneeName":"Example Importer GmbH","vesselName":"MV Example","voyageNumber":"001E","portOfLoading":"Singapore","portOfDischarge":"Rotterdam","cargoDescription":"40 cartons of machine parts"}'

The eight fields in this example are required. You may also send shipperAddress, consigneeAddress, notifyParty, packages, grossWeight, measurement, freightTerms and billOfLadingType.

The call returns status 201. Although the path says ebl, it files a sea waybill: a non-transferable record with a SHA-256 digest of its fields. It is not a transferable record, and nothing is written to a blockchain. The response says so with "transferable": false and a notice. A documentType that names a transferable type is refused, as Transferable records explains.

4. Move to production

Create a Production key when you are ready. It begins with sk_live_ and uses the same base URL. A sandbox key files and lists sandbox records; a production key files and lists production records. Authentication explains what the two kinds of key share.

What the Preview does not do

• Issue or transfer transferable records. That happens in the app, as described in Transferable records.
• Limit every endpoint. Some endpoints are rate limited. POST /api/v1/verify allows 30 requests a minute per client; above that it returns 429 with code rate_limited. Other limits will be announced in the release notes before they apply.
• Limit a key to certain actions. Every key acts as an admin of your organisation.
• Make a retried POST /ebl safe. See Errors.