Create a Pull Account

Adds the holder's own account at another US bank, from which ACH pulls fund the account's USD bank account. The holder accepts the ACH debit authorization in the same request.

The routing number's check digit is verified here. Nothing is sent to the bank until the first pull.

New in v3: v2 has no equivalent.

A workspace-scoped key names the account with account_id; an account-scoped key acts for its own account.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

POST

/v3/banking/pull-accounts

Headers

Header	Description
Idempotency-Key	Required, from every caller, API keys included: there is no grace period. One UUID per account to add, sent again unchanged on every retry. A retry answers the first response instead of adding the account twice. See API v3 overview.

Query parameters

Parameter	Type	Description
account_id	string (cst_…)	The account the pull account belongs to. Required for a workspace-scoped key; an account-scoped key adds to its own account and may omit it.

Request Body Sample

{
  "name": "Chase checking",
  "bank_name": "JPMorgan Chase",
  "holder_name": "Samantha Montenegro",
  "holder_type": "individual",
  "routing_number": "021000021",
  "account_number": "000123456789",
  "account_type": "checking",
  "authorization": {
    "accepted": true,
    "version": "2026-10-20.v2"
  }
}

Request Body Schema

Field	Type	Description
name	string	Optional. The holder's own label for it, up to 100 characters.
bank_name	string	Optional. The bank's name, up to 100 characters.
holder_name	string	Required. The name on the account at its bank, up to 100 characters.
holder_type	string	Required. individual or business. A person's account is debited under the NACHA class WEB, a business's under CCD.
routing_number	string	Required. The nine-digit ABA routing number.
account_number	string	Required. 4 to 17 digits.
account_type	string	Required. checking or savings.
authorization.accepted	boolean	Required. true: the holder accepted the ACH debit authorization.
authorization.version	string	Required. The version of the text the holder was shown.

Response Sample

201 Created

{
  "id": "bpa_01k8x4p6sx9t5v7x1z3b5d7f9h",
  "account_id": "cst_01h455vb4pex5vsknk084sn02q",
  "name": "Chase checking",
  "bank_name": "JPMorgan Chase",
  "holder_name": "Samantha Montenegro",
  "holder_type": "individual",
  "routing_number": "021000021",
  "account_number_last4": "6789",
  "account_type": "checking",
  "currency": "USD",
  "status": "active",
  "authorization": {
    "version": "2026-10-20.v2",
    "accepted_at": "2026-10-19T15:00:00Z"
  },
  "created_at": "2026-10-19T15:00:00Z",
  "updated_at": "2026-10-19T15:00:00Z"
}

Response Schema

Field	Type	Description
id	string (bpa_…)	The pull account.
account_id	string (cst_…)	The account it belongs to.
name, bank_name	string	As sent; absent when empty.
holder_name, holder_type, routing_number, account_type	string	As sent.
account_number_last4	string	The last four digits. The full number is never returned.
currency	string	USD.
status	string	active, or disabled after a return or a notification of change (see How ACH Pulls Work).
status_reason	string	Why it was disabled. Absent while active.
return_code	string	The NACHA code that disabled it. Absent while active.
authorization.version, authorization.accepted_at	string	The authorization it was last given.
created_at / updated_at	string (date-time)	RFC 3339, UTC.

Errors

Status	message	When
400	account_id_required	A workspace-scoped key named no account_id.
400	failed to parse request	The body is not valid JSON, holder_type or account_type is not one of the listed values, or account_id is not a cst_… id.
400	invalid_routing_number	Not nine digits, or its check digit does not hold.
400	invalid_account_number	Not 4 to 17 digits.
400	invalid_holder_name	Only spaces.
400	idempotency_key_required	No Idempotency-Key header.
400	idempotency_key_invalid	The Idempotency-Key is longer than 255 characters or not printable ASCII.
401	unauthorized	Missing or invalid signature.
403	forbidden	An account-scoped key named another account in account_id.
403	account_frozen	The account is frozen or blocked.
404	feature_not_enabled	ACH pulls are not enabled for the account.
404	customer_not_found	No such account.
409	ach_authorization_outdated	authorization.version is not the current text. Fetch it again, show it, and send the new version.
409	idempotency_in_progress	The same Idempotency-Key is still running. Retry after Retry-After seconds with the same key.
413	body_too_large	The body is over 1 MiB.
422	ach_authorization_required	authorization.accepted is not true.
422	Validation failed	A required field is missing, or a text field is too long; details names it.
422	idempotency_key_conflict	The same Idempotency-Key was used for a different request.
503	idempotency_unavailable	The key store is unavailable. Nothing ran: retry later with the same key.

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

• Instagram: BlockWyre Instagram
• Twitter: BlockWyre Twitter
• Facebook: BlockWyre Facebook
• LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!