Custody Distributions API Documentation

Overview

The Custody Distributions API allows you to create and manage fund distributions from brokerage accounts to external bank accounts. This endpoint supports both domestic (ACH) and international (wire) transfers.

Base URL

https://api.norcapsecurities.com/v3/custody/distributions

POST /v3/custody/distributions

Create one or more new distribution requests from brokerage accounts to external bank accounts.

Request Body

{
  "newDistributions": [
    {
      "brokerageAccountId": "string",
      "amountCents": "integer",
      "accountId": "string",  // Optional: Use this OR bankId/bankAccountId
      "bankId": "string",     // Optional: Banking routing number or BIC/SWIFT code
      "bankAccountId": "string", // Optional: Bank account number or IBAN
      "transactionType": "string", // Optional: "ach" or "wire"
      "transactionMemo": "string"  // Optional: Memo for the transaction
    }
  ]
}

Parameters

Field	Type	Required	Description
`newDistributions`	array	Yes	Array of distribution requests
`brokerageAccountId`	string	Yes	The brokerage account ID (e.g., "NC95156")
`amountCents`	integer	Yes	Amount to distribute in cents (e.g., 1234 = $12.34)
`accountId`	string	Conditional	External account ID linked to bank account. Required if `bankId` and `bankAccountId` not provided
`bankId`	string	Conditional	For US banks: routing number; For international banks: BIC/SWIFT code. Required if `accountId` not provided
`bankAccountId`	string	Conditional	Bank account number or IBAN. Required if `accountId` not provided
`transactionType`	string	No	Type of transaction: "ach" or "wire". If not specified, the system will determine the appropriate type
`transactionMemo`	string	No	Optional memo or description for the transaction

Note: You must provide either accountId OR both bankId and bankAccountId. Providing both will result in an error.

Response

Success Response (200 OK)

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "distributions": [
    {
      "id": "uuid",
      "submissionId": "uuid",
      "brokerageAccountId": "string",
      "amountCents": "integer",
      "status": "string",
      "accountId": "string",
      "bankId": "string",
      "bankAccountId": "string",
      "transactionType": "string",
      "transactionMemo": "string",
      "createdAt": "datetime",
      "updatedAt": "datetime"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the distribution (UUID format)
`submissionId`	string	Identifier for the submission batch (UUID format)
`brokerageAccountId`	string	Brokerage account ID
`amountCents`	integer	Amount in cents
`status`	string	Current status of the distribution (e.g., "pending")
`accountId`	string	External account ID (null if using bank info directly)
`bankId`	string	Bank routing number or BIC/SWIFT code (null if using accountId)
`bankAccountId`	string	Bank account number or IBAN (null if using accountId)
`transactionType`	string	Type of transaction: "ach" or "wire" (may be null initially)
`transactionMemo`	string	Memo or description for the transaction (may be null)
`createdAt`	string	Creation timestamp (YYYY-MM-DD HH:MM:SS)
`updatedAt`	string	Last update timestamp (YYYY-MM-DD HH:MM:SS)

Status Codes

The distribution status can be one of the following:

pending (default)
processing
on_hold
approved
rejected
scheduled
in_review
completed
terminated
failed
reopened

Error Responses

Status Code	Error Code	Description
400	1400	Missing required fields or invalid parameters
422	1422	Invalid banking information (e.g., invalid IBAN)

Common Error Messages

Bad request: account ID or banking info required
Bad request: only one of account ID or banking info may be specified
Bad request: '{id}' is not a valid account ID
Bad request: '{accountId}' is not linked to an external account
Bad request: brokerage account '{brokerageAccountId}' does not exist
Invalid request semantics: not a valid iban

Examples

Example 1: Create a distribution using an external account ID

// Request
POST /v3/custody/distributions
{
  "newDistributions": [
    {
      "brokerageAccountId": "NC95156",
      "amountCents": 1234,
      "accountId": "A1234567890"
    }
  ]
}

// Response
{
  "statusCode": "101",
  "statusDesc": "Ok",
  "distributions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "submissionId": "550e8400-e29b-41d4-a716-446655440001",
      "brokerageAccountId": "NC95156",
      "amountCents": 1234,
      "status": "pending",
      "accountId": "A1234567890",
      "bankId": null,
      "bankAccountId": null,
      "transactionType": null,
      "transactionMemo": null,
      "createdAt": "2023-05-01 14:30:00",
      "updatedAt": "2023-05-01 14:30:00"
    }
  ]
}

Example 2: Create a distribution using direct bank information

// Request
POST /v3/custody/distributions
{
  "newDistributions": [
    {
      "brokerageAccountId": "NC95156",
      "amountCents": 1234,
      "bankId": "012345678",
      "bankAccountId": "123456789"
    }
  ]
}

// Response
{
  "statusCode": "101",
  "statusDesc": "Ok",
  "distributions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "submissionId": "550e8400-e29b-41d4-a716-446655440001",
      "brokerageAccountId": "NC95156",
      "amountCents": 1234,
      "status": "pending",
      "accountId": null,
      "bankId": "012345678",
      "bankAccountId": "123456789",
      "transactionType": null,
      "transactionMemo": null,
      "createdAt": "2023-05-01 14:30:00",
      "updatedAt": "2023-05-01 14:30:00"
    }
  ]
}

Example 3: Create a distribution with a specified transaction type and memo

// Request
POST /v3/custody/distributions
{
  "newDistributions": [
    {
      "brokerageAccountId": "NC95156",
      "amountCents": 2222,
      "accountId": "A1234567890",
      "transactionType": "wire",
      "transactionMemo": "from NC95156"
    }
  ]
}

// Response
{
  "statusCode": "101",
  "statusDesc": "Ok",
  "distributions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "submissionId": "550e8400-e29b-41d4-a716-446655440001",
      "brokerageAccountId": "NC95156",
      "amountCents": 2222,
      "status": "pending",
      "accountId": "A1234567890",
      "bankId": null,
      "bankAccountId": null,
      "transactionType": "wire",
      "transactionMemo": "from NC95156",
      "createdAt": "2023-05-01 14:30:00",
      "updatedAt": "2023-05-01 14:30:00"
    }
  ]
}

Example 4: Create multiple distributions in a single request

// Request
POST /v3/custody/distributions
{
  "newDistributions": [
    {
      "brokerageAccountId": "NC95156",
      "amountCents": 1111,
      "bankId": "012345678",
      "bankAccountId": "123456789"
    },
    {
      "brokerageAccountId": "NC95156",
      "amountCents": 2222,
      "accountId": "A1234567890",
      "transactionType": "wire",
      "transactionMemo": "from NC95156"
    },
    {
      "brokerageAccountId": "NC95156",
      "amountCents": 3333,
      "bankId": "CHASDEFX123",
      "bankAccountId": "ACCT123456789XYZ"
    }
  ]
}