Recipients and reachability
Supply recipients when a published plan expects them, then use the run result and participant states instead of probing identifiers first.
Delivered plans accept a recipients array when they run. Each entry carries
an addressing object, a display name, and your own stable ref.
{
"recipients": [
{
"addressing": { "type": "nin", "nin": "12345678901" },
"display_name": "Musa Bello",
"ref": "EMP-4471"
}
]
}Addressing modes
type | Identifier | When nobody matches now |
|---|---|---|
nin | nin | Retained for delivery after that person verifies. |
cac | cac_number | Retained when the legal entity can hold a mailbox. |
email | email | Rejected; an email is a matching key, not a future hold key. |
claim | declared_name | Creates a single-use claim code your organisation delivers. |
Identifiers are write-only and are never echoed back. The participant carries
its participant_id, the display_name you supplied, your ref, and what
Keepable verified.
Validate through the run
There is no public recipient-check endpoint. Submit the recipients with the plan run:
- malformed or unresolvable entries appear in the run's
rejectedcollection with their input index andref; - accepted entries become participants; and
- asynchronous delivery outcomes appear on those participants and in webhook events.
This avoids turning the API into an identity-enumeration service and removes a separate preflight round trip.
Addressing a company
Use the full CAC registration number, including its series prefix, such as
RC1234567, BN1234567, IT1234567, LP1234567, or LLP1234567. A bare
number is rejected because the registers are separate.
When you have only a name
Use claim addressing. Keepable deposits the file against the declared name and
returns a single-use code through GET /correspondence/{correspondence_id}/claims.
See Claim codes.