Skip to main content

​
Overview

A Whitelist Recipient is an intercompany bank account 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 a bank account (US domestic or SWIFT/IBAN), the legal holder name, the relationship to the customer, and the evidence documents that support the registration.

​
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 recipient matching the destination bank details. The RECIPIENT_NOT_WHITELISTED error fires if no such entry exists.

​
Lifecycle

StatusMeaning
PENDING_REVIEWThe registration has been submitted and is awaiting compliance review.
REGISTEREDThe recipient has been approved. purpose: INTERCOMPANY payouts may now target this account.
REJECTEDThe registration was declined. The rejectionReason field carries the detail. Resubmit with corrected information to start a new review.
SUSPENDEDThe entry has been temporarily suspended by Conduit. New payouts to this recipient are blocked until the suspension is lifted.
REVOKEDThe registration was cancelled, either by your organization (DELETE /v2/customers/:id/whitelist-recipients/:recipientId) or by Conduit. Terminal state.
Review outcomes are delivered via whitelist_recipient.* webhooks. Do not poll for status changes — listen for the webhook.

​
Key fields

FieldTypeDescription
idwlr_*Unique identifier for the recipient.
railUS | SWIFTPayment rail. US identifies by ABA routing number + account number. SWIFT identifies by IBAN.
holderNamestringLegal name of the bank account holder.
relationshipSELF | GROUP_ENTITYWhether this is the customer’s own account (SELF) or another entity in the same corporate group (GROUP_ENTITY).
bankIdentifierstring | nullABA routing number for US rail; null for SWIFT (bank identified via IBAN).
accountIdentifierstringAccount number (US) or IBAN (SWIFT).
evidenceDocumentIdsdoc_*[]Documents uploaded to support the registration.
statussee aboveCurrent review status.
rejectionReasonstring | nullPresent when status is REJECTED.

​
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