Recipients and reachability

Keepable delivers to verified people, not to addresses. A send never sits in limbo hoping somebody turns up. One of three things happens, and which one depends on the identifier you used: it matches somebody now, it is held for somebody who has not registered yet, or it never delivers at all.

And if you hold no identifier at all (a walk-in customer, a beneficiary on a paper list), that is not a dead end either: a claim code deposits the file against the name you declare and hands you a single-use code to pass on however you already reach them.

Matching keys and hold keys

Email is a matching key. It resolves to a Keepable account or it does not. If it does not, the send is blocked: it will not deliver now and it will not deliver later, because nothing about an unmatched email is a promise that the person will turn up.

NIN and CAC number are hold keys. Nigeria has one national identity number per person, so an unmatched NIN is not a failure, it is a cold start. The item is retained: sealed, held, and delivered the day that person verifies. Most of the country is not on Keepable yet, and this is how you reach them anyway.

Set retention_days on the correspondence to say how long you are willing to wait. When it lapses, the item expires unread and nothing is delivered.

Addressing a company

A company is addressed by its CAC registration number, the one the Corporate Affairs Commission issued it:

{ "addressing": { "type": "cac", "cac_number": "RC1234567" } }

Unlike a NIN, this is an identifier you can look up rather than one you have to be given. CAMA 2020 s.729 obliges a company to state its registration number on every business letter, invoice, receipt and order form it issues, so it is usually already printed on the document you are answering; and the Commission runs a free public register that resolves a company name to it.

Include the prefix. It names the register the number came from, and they are separate runs: RC a company, BN a business name, IT incorporated trustees, LP and LLP partnerships. RC1234567 and BN1234567 are different entities, so a bare 1234567 is rejected rather than guessed at.

Write it however you have it (RC 1234567, rc-1234567) and it is normalised. Leading zeros are not part of the identity: RC0001234 and RC1234 are the same company.

All five registers can be addressed. Only RC, IT and LLP can hold a Keepable mailbox of their own, because a business name and a limited partnership have no legal identity separate from the people behind them. Mail to a BN or LP is still held, so nothing addressed to a sole trader is refused; if they later incorporate, it arrives.

Checking before you send

POST https://api.keepable.co/sender/v2/recipient-checks
Authorization: Bearer {{KEEPABLE_TOKEN}}
Content-Type: application/json

{ "identifier_type": "email", "identifier": "musa@zenithtraders.example" }

{ "deliverable": false }

One identifier, one boolean. Both fields are required: identifier_type is nin, email, or cac, and naming it rather than sniffing the string is what stops RC1234567 and a NIN from being told apart by their shape.

Read the answer against the table above: a false on an email means blocked, a false on a NIN means it will be retained, and the two call for completely different handling in your code.

Where it earns its place is interactive: one recipient, typed by a human, where the answer changes what the next screen says.

When you have neither

A declared name and no identifier is still addressable, through a claim code: Keepable deposits the file, mints a single-use code, and you hand the code over on your own channel.

What comes back

A participant never echoes the identifier you addressed them by. What you get is a participant_id, the display_name you supplied, your own ref, and a verification telling you what Keepable actually established about them:

{
  "participant_id": "prt_01J8ZQ4T",
  "display_name": "Musa Bello",
  "ref": "EMP-4471",
  "verification": "nin",
  "state": "delivered"
}

verification is worth reading rather than assuming. A person who answered a form did so from their own Keepable, which they reached by verifying their NIN with a mandatory liveness check. That is a stronger statement about who they are than any field you could have asked them to type.