DevelopersSafetySecurityTalk to us
Get started
Get started
Contents

unforged/folio · docs · Start

Quickstart: file your first record

Once we’ve turned folio on for your organisation, you’ll be able to file a record from your own code in a few minutes. This page uses curl, and the web app’s Add documents page will do the same job if you’d rather start there.

Join the beta

Tell us what you have to keep, and which region your records should live in, and we’ll turn folio on for your organisation.

Set up a retention class

A retention class will decide how long a record is kept, and whether it’s Retained or Locked. Your organisation will start with one, Standard, which will keep records for seven years as Retained.

In the web app’s folio settings, add a class for each kind of record you look after. For this walkthrough, make one called client-files. How long each class should run is your professional judgement, and folio will hold to whatever you set.

Make an API key

Create an API key in the web app and give it permission to file records, and to search them if you’d like to try the last step. Treat the whole key as a secret and send it as a bearer token.

File a document

Send the file as the body of the request, with its folder, its name and its class. If the folder doesn’t exist yet, folio will make it.

File a document 
curl -X POST "https://api.unforged.sh/folio/records?folder=clients/harlow&name=engagement-letter.pdf&class=client-files&matter=HAR-0412" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Idempotency-Key: harlow-engagement-letter" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @engagement-letter.pdf

Filing won’t ask for a reason. If you send the same file to the same folder under the same name again, you’ll get the same receipt back rather than a second record.

Keep the receipt

The answer will be the record’s receipt: its id, the SHA-256 fingerprint of the file, its class, its lock and the earliest day it can be deleted.

The receipt 
{
  "record_id": "rec_01J9X3M8V7K2Q4R5S6T7U8V9W0",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "size": 18234,
  "class_id": "client-files",
  "lock": "retained",
  "earliest_delete": "2033-10-08"
}

Store the record id beside your own reference for the client. If anyone ever asks whether the file has changed, the fingerprint is what you’ll compare it against.

Find it again

Search by name, matter or subject, or add scope=content to search the words inside.

Search 
curl "https://api.unforged.sh/folio/search?q=engagement&matter=HAR-0412" \
  -H "Authorization: Bearer $UNFORGED_KEY"

Searching won’t need a reason, but the search and what it showed will go in your ledger like everything else.

The routes

  • POST /folio/records
  • GET /folio/search
Join the beta All folio docs