Legal statusOrder of 15 September 2026: in force; no application for leave to appeal was filedOrder of 15 Sep 2026
Banks and trust companies

A system link between your estates system and ours.

For the IT people of a bank's fiduciary unit or a trust company. Your system can refer an estate, read your estates with the same fields as the spreadsheet download, and receive a signed notice when an estate's status changes.

Getting a key

  1. Signed data-processing terms firstWe issue a key only once your institution's signed data-processing terms are on our record. Ask Wayne de Jager at wayne@firearmdesk.co.za.
  2. A key acts as a named personEach key belongs to one person at your institution who uses our portal as an attorney or firm administrator. Everything done with the key is recorded as done by that person through that key, and the acknowledgement of each referral goes to that person. If the person leaves or their access is suspended, the key stops working.
  3. Shown onceWe show the key once, when it is issued, and keep only a fingerprint of it. Store it as a secret on your server. If it may have been exposed, tell us: we revoke it at once and issue another. Revoking a key also removes a notice address that key set, and status notices stop as soon as none of your keys works.

Address and authentication

Every call goes to https://app.firearmdesk.co.za/api/v1/institution over HTTPS, from your server. Send the key in the Authorization header:

Authorization: Bearer fdk_…

Refer an estate

POST /referrals refers one estate. The fields are the columns of the spreadsheet template on the portal, with the same rules; the estate then follows exactly the path of an estate referred on the portal. Send a new Idempotency-Key header (8 to 100 letters, digits, hyphens or underscores) with each estate. If you send the same request again with the same key, for example after a timeout, you get the first answer again, with the header Idempotency-Replayed: true, and never a second estate. The same key with a different estate is refused.

FieldWhat it holds
deceased_full_name (required)The full name of the deceased, 2 to 200 characters.
firm_file_referenceYour own file reference, up to 100 characters. It comes back on every answer and notice as yourReference.
master_referenceThe Master’s reference, up to 60 characters.
date_of_deathYYYY-MM-DD, not in the future.
provinceA province code (EC, FS, GP, KZN, LP, MP, NC, NW, WC) or the province’s name.
executor_nameUp to 200 characters.
executor_emailA valid email address.
executor_phoneA South African or international number, 7 to 15 digits.
estimated_firearm_countA whole number from 0 to 500, as a number or as text.
firearm_locationWhere the firearms are kept, in words, up to 500 characters. Never a street address you would not put in an email.
urgencyNORMAL, URGENT, SAFETY_CONCERN. NORMAL when left out.
licensed_heir_keepsWhether a licensed heir who will inherit keeps the firearms: ALL, SOME, NONE, UNKNOWN. UNKNOWN when left out.
confirmation (required)The confirmation the tick on the portal gives: authorityToRefer, privacyNoticeAccepted and termsAccepted all true, and termsVersion, the version in force, as shown on our terms page (the privacy notice carries the same version). Any other version is refused with 422, and the answer names the version in force.

Any other field is refused, and so is the whole request. Identity numbers, firearm serial numbers and licence numbers are never sent through this link.

POST https://app.firearmdesk.co.za/api/v1/institution/referrals
Authorization: Bearer fdk_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0
Idempotency-Key: est-2026-0412-1
Content-Type: application/json

{
  "deceased_full_name": "Johannes Voorbeeld",
  "firm_file_reference": "EST/2026/0412",
  "master_reference": "12345/2026",
  "date_of_death": "2026-09-14",
  "province": "GP",
  "executor_name": "Anna Voorbeeld",
  "executor_email": "anna@example.co.za",
  "estimated_firearm_count": 3,
  "urgency": "NORMAL",
  "licensed_heir_keeps": "UNKNOWN",
  "confirmation": {
    "authorityToRefer": true,
    "privacyNoticeAccepted": true,
    "termsAccepted": true,
    "termsVersion": "the version shown on our terms page"
  }
}
HTTP/1.1 201 Created

{
  "reference": "FD-2026-000123",
  "yourReference": "EST/2026/0412",
  "status": "Awaiting authority documents",
  "link": "https://app.firearmdesk.co.za/portal/attorney/matters/ckexample0000000000000000"
}

Read your estates

GET /matters lists your institution's estates, oldest change first, with the fields of the spreadsheet download. Optional query values: limit (1 to 100, 50 when left out), yourReference (your file reference, exactly), updatedSince (an ISO 8601 time with its offset) and cursor (the nextCursor of the page before; it is null on the last page). To keep a copy up to date, ask with updatedSince set to the last lastUpdated you hold.

GET /matters/FD-2026-000123 returns one estate with the same fields.

GET https://app.firearmdesk.co.za/api/v1/institution/matters?limit=2&updatedSince=2026-11-01T00:00:00%2B02:00

HTTP/1.1 200 OK

{
  "matters": [
    {
      "reference": "FD-2026-000123",
      "yourReference": "EST/2026/0412",
      "deceased": "Johannes Voorbeeld",
      "status": "In licensed custody",
      "opened": "2026-11-02",
      "lastUpdated": "2026-11-12T09:41:07.120Z",
      "closed": null,
      "firearms": 3,
      "nextStep": "Nothing needed from you. With Platform operations",
      "feesInvoicedCents": 224250,
      "feesInvoicedRand": "2242.50",
      "feesPaidCents": 0,
      "feesPaidRand": "0.00"
    }
  ],
  "nextCursor": "WyIyMDI2LTExLTEyVDA5OjQxOjA3LjEyMFoiLCJja2V4YW1wbGUiXQ"
}

The status is always in the words the portal uses:

Money is given in cents, as a whole number, and in rand. Firearmdesk is not registered for VAT, so no VAT is added to our fees.

Status notices

Give one HTTPS address with PUT /webhook. When the status of one of your estates changes, we send a notice to it. The answer to PUT holds the signing secret: it is shown only then. Setting the address again replaces it and issues a new secret. GET /webhook shows the address; DELETE /webhook removes it, and notices not yet sent are then not sent.

PUT https://app.firearmdesk.co.za/api/v1/institution/webhook
Authorization: Bearer fdk_…
Content-Type: application/json

{ "url": "https://notices.example-trust.co.za/firearmdesk" }

HTTP/1.1 200 OK

{
  "url": "https://notices.example-trust.co.za/firearmdesk",
  "setAt": "2026-11-16T07:30:00.000Z",
  "secret": "fdwhsec_…",
  "message": "Keep the secret: it signs every notice and is shown only now. …"
}
POST /firearmdesk HTTP/1.1
Host: notices.example-trust.co.za
Content-Type: application/json
User-Agent: Firearmdesk-Notices/1
Firearmdesk-Timestamp: 1763278200
Firearmdesk-Signature: v1=5f0c…(64 hexadecimal characters)
Firearmdesk-Notice-Id: ckexample0000000000000000

{"reference":"FD-2026-000123","yourReference":"EST/2026/0412","status":"In licensed custody","changedAt":"2026-11-16T07:29:58.412Z"}

The signature is HMAC-SHA256, with your secret as the key, over the timestamp header, a full stop and the raw body exactly as received, written as v1= and 64 hexadecimal characters. Check it before you act on a notice:

// Node.js: check a notice before you act on it
import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(rawBody, timestamp, signature, secret) {
  // refuse a notice older than five minutes, so a captured one cannot be replayed later
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'v1=' + createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signature)
  return a.length === b.length && timingSafeEqual(a, b)
}

Errors and limits

An error answers with a status and a JSON body: error, a short code, and message, a sentence you can show a person.

StatusMeaning
400The request cannot be read: a missing Idempotency-Key, a field we do not know (it is named), a query we do not take. A field this link never carries, such as an identity, serial or licence number, is not named in the message: its name is in the fields array of the answer.
401The key is missing, not valid or no longer active. The answer is the same whatever the reason.
404No estate of your institution has that reference. An estate of another institution answers the same way.
409New referrals are paused (the message says why), or another change was saved at the same moment: nothing was saved, so send the same request again.
422The estate needs correcting (errors lists each problem, in plain words), the confirmation is missing, or the Idempotency-Key was already used for a different estate.
429Too many calls. Wait for the number of seconds in the Retry-After header.
500Something failed on our side. Send the same request again with the same Idempotency-Key; you will not make a second estate.
503Status notices are not available yet. The rest of the link works.

What the link never carries

No identity numbers, no firearm serial numbers or other marks, no licence numbers, no custody partner's name or address and no storage position, in either direction. They stay in the portal, where access is controlled and recorded. Every accepted call is recorded in our audit trail by the key's first characters, with counts and references only, never the content you send.

Questions, a new key or a key to revoke: Wayne de Jager, wayne@firearmdesk.co.za. More about the service for institutions is on the banks and trust companies page.