Skip to main content
POST
Delivers one sealed envelope to the bank. The body is the envelope described under Envelope format: the header, the encapsulated key, the ciphertext and your signature. Trusset checks what it can read, stores the envelope and tells the bank a record is waiting. It cannot decrypt it. A 201 means Trusset holds the envelope. It does not mean the bank accepted the record. Follow it with Get Delivery Status.

Checks, in order

The first check that fails refuses the delivery, and nothing is stored:
  1. Your source is ACTIVE (SOURCE_PAUSED).
  2. Sealed KYC records are enabled for the bank’s instance (SEALED_KYC_NOT_ENABLED). This can fail on a production instance only.
  3. The body is well formed: the header is compact JSON with exactly the 13 keys, every value has its form, the timing rules hold, and enc, ciphertext and signature have their sizes (VALIDATION_ERROR, PAYLOAD_TOO_LARGE).
  4. header.sourceId is the sourceId in the path (VALIDATION_ERROR).
  5. The signature verifies against the signing key the bank registered for your source (INVALID_SIGNATURE).
  6. header.profileKey is the profile key the bank set for your source (PROFILE_MISMATCH).
  7. The bank has a recipient key, and header.recipientKeyId names it (RECIPIENT_KEY_NOT_SET, RECIPIENT_KEY_MISMATCH).
  8. The envelope is new, or an exact repeat (ENVELOPE_ID_REUSED, RECORD_ALREADY_DELIVERED).
  9. The inbox has room (INBOX_FULL).

Sending twice

Posting the exact same envelope again answers 200 with replayed: true and the record it created the first time. Nothing is stored twice, so a retry after a timeout or a lost response is safe.

A full inbox

A delivery is refused with 429 INBOX_FULL while 1,000 records of your source wait unopened, or while the records waiting unopened at the bank’s instance would exceed 512 MiB together. Room returns when the bank opens or rejects records, or when waiting records lapse. Tell the bank, and retry later.

Path Parameters

string
required
Your source ID, from the invite.

Body Parameters

string
required
The header bytes as base64url without padding. At most 2,048 bytes before encoding.
string
required
The 32-byte HPKE encapsulated key, standard base64 with padding.
string
required
The ciphertext with its 16-byte tag, standard base64 with padding. From 82 to 6,291,456 bytes before encoding.
string
required
Your 64-byte Ed25519 signature over the header and the sealed bytes, standard base64 with padding.

Response Fields

object

Error Codes