Skip to main content

​
Overview

A Whitelist Recipient is an intercompany counterparty — a bank account or a crypto wallet — that your organization pre-registers and has reviewed by Conduit before any funds move. Only recipients in registered status unlock purpose: intercompany payouts for the associated customer. Whitelist recipients are scoped to a customer. Each entry records the recipient’s coordinates, the legal holder name, the relationship to the customer, and the evidence documents that support the registration. The rail field says how the recipient is identified: us by ABA routing number plus account number, swift by BIC plus an IBAN (or plus an account number for banks in countries without IBAN), sepa by IBAN alone, and crypto by chain plus address.
The crypto rail is for another entity in your customer’s corporate group. It requires relationship: group_entity and rejects relationship: self. To whitelist your customer’s own wallet, register it as a self_custody registered address instead.

​
Relationships

  • Customer — each recipient is scoped to a single customer (customerId). You may register multiple recipients per customer.
  • Documents — one or more previously uploaded doc_* documents are attached as evidenceDocumentIds at registration time. These evidence the intercompany relationship (ownership chart, inter-company agreement, bank statement).
  • Payouts — a payout with purpose: intercompany requires a registered entry matching the destination. A bank payout matches on the destination bank details. A crypto payout matches a crypto entry on chain plus address, and must also send destination.recipient.attestation.custody: "third_party" with the third-party identity fields, because a group entity is a different beneficial owner. The RECIPIENT_NOT_WHITELISTED error fires if no matching entry exists.

​
Lifecycle

Review outcomes are delivered via whitelist_recipient.* webhooks. Do not poll for status changes — listen for the webhook.

​
Key fields

​
API surface

  • POST /v2/customers/:customerId/whitelist-recipients — register a new recipient (requires Idempotency-Key)
  • GET /v2/customers/:customerId/whitelist-recipients — list recipients, optionally filtered by ?status=
  • GET /v2/customers/:customerId/whitelist-recipients/:id — get a single recipient
  • DELETE /v2/customers/:customerId/whitelist-recipients/:id — revoke a recipient (terminal)
In sandbox, two simulate endpoints bypass the review queue:
  • POST /v2/sandbox/whitelist-recipients/:id/simulate-approve — move pending_review → registered
  • POST /v2/sandbox/whitelist-recipients/:id/simulate-reject — move pending_review → rejected