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
- 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.
- 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.
- 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_…
- Never in a URLA key in a query string or a path is never accepted. Keys start with
fdk_, so your own scanners can find one that leaks. - Server to server onlyAnswers carry no CORS headers, so a web browser cannot call the link. Your portal session does not work here, and the key does not open the portal.
- JSONRequests and answers are JSON in UTF-8. Times are ISO 8601 in UTC; dates such as
openedare South African dates.
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.
| Field | What it holds |
|---|---|
deceased_full_name (required) | The full name of the deceased, 2 to 200 characters. |
firm_file_reference | Your own file reference, up to 100 characters. It comes back on every answer and notice as yourReference. |
master_reference | The Master’s reference, up to 60 characters. |
date_of_death | YYYY-MM-DD, not in the future. |
province | A province code (EC, FS, GP, KZN, LP, MP, NC, NW, WC) or the province’s name. |
executor_name | Up to 200 characters. |
executor_email | A valid email address. |
executor_phone | A South African or international number, 7 to 15 digits. |
estimated_firearm_count | A whole number from 0 to 500, as a number or as text. |
firearm_location | Where the firearms are kept, in words, up to 500 characters. Never a street address you would not put in an email. |
urgency | NORMAL, URGENT, SAFETY_CONCERN. NORMAL when left out. |
licensed_heir_keeps | Whether 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:
- Referral received
- Awaiting authority documents
- Authority verified
- Firearm inventory in progress
- Arranging licensed custody
- Collection or receipt scheduled
- In licensed custody
- Valuation in progress
- Awaiting executor instruction
- Processing executor instruction
- Awaiting external authority
- Settlement and closure
- Closed
- Paused pending legal confirmation
- Paused pending compliance review
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.
- The addresshttps on the standard port (443), a public host name (not an IP address), no user name or password in it. We check where the name points at every delivery and send nothing to an address that is not on the public internet.
- Your answerAnswer with any 2xx status within 5 seconds. We do not follow redirects and we do not read or keep what you send back.
- RetriesIf a delivery fails we try again, waiting longer each time, up to five attempts in all; then we stop and our team is told. Notices can arrive out of order: use
changedAt. UseFirearmdesk-Notice-Idto ignore one you already have. - What a notice holdsOur reference, your reference, the status in the portal's words and when it changed. Nothing else. Read the estate with
GET /matters/{reference}for the rest.
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.
| Status | Meaning |
|---|---|
| 400 | The 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. |
| 401 | The key is missing, not valid or no longer active. The answer is the same whatever the reason. |
| 404 | No estate of your institution has that reference. An estate of another institution answers the same way. |
| 409 | New 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. |
| 422 | The 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. |
| 429 | Too many calls. Wait for the number of seconds in the Retry-After header. |
| 500 | Something failed on our side. Send the same request again with the same Idempotency-Key; you will not make a second estate. |
| 503 | Status notices are not available yet. The rest of the link works. |
- Each key120 calls a minute, and of those 60 referrals in any 15 minutes.
- Each addressAfter 20 refused keys in 15 minutes, further refused keys from that address answer 429 until the 15 minutes pass. A valid key keeps working.
- SizeA referral body of at most 32 KB; at most 100 estates on a page.
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.