Skip to main content
Account number reservations require the account_number_reservation entitlement. Contact Treasury Prime support to enable this feature for your organization.

​
What are account number reservations?

Account number reservations let you obtain and reserve an account number before formally opening an account. The reserved account number is allocated from your organization’s configured account number prefix and held exclusively for your use until you create an account with it. This feature supports use cases where an account number must be known ahead of time, such as:
  • Pre-assigning account numbers during onboarding flows before account approval
  • Displaying account numbers to customers before account creation completes
  • Integrating with external systems that require account numbers upfront
  • Building multi-step onboarding experiences where account details are needed early
Account number reservations are specific to an account product. When you create a reservation, Treasury Prime allocates an account number from the pool associated with that account product’s configured prefix.

​
How account number reservations work

Creating an account number reservation involves calling the POST /account_number_reservation endpoint with an account product ID. Treasury Prime immediately allocates an account number from the configured prefix for that account product and returns a reservation object containing the reserved account number. The reservation remains valid until you use it to create an account by passing the reservation ID in the account_number_reservation_id field when creating an account application. Each reservation can only be used once.

​
Creating a reservation

When you create an account number reservation:
  1. Treasury Prime validates the account product: The system checks that the account product exists and that your organization has the account_number_reservation entitlement enabled.
  2. Treasury Prime allocates an account number: The system reserves an account number from the pool associated with the account product’s configured prefix.
  3. Treasury Prime creates the reservation object: The system creates an account number reservation object with the allocated account number and account product ID.
  4. Treasury Prime returns the reservation: The API response includes the reservation ID and the reserved account number.
Example request to create an account number reservation
curl -X POST \
  -u $API_KEY_ID:$API_SECRET_KEY \
  https://api.treasuryprime.com/account_number_reservation \
  -H 'Content-Type: application/json' \
  -d '{
    "account_product_id": "apt_11ffk99xyzy"
  }'
Example response
{
  "created_at": "2024-01-15T11:55:14Z",
  "updated_at": "2024-01-15T11:55:14Z",
  "id": "anr_123456789",
  "account_number": "1301550041234",
  "account_product_id": "apt_11ffk99xyzy"
}

​
Using an account reservation

To use a reserved account number when creating an account, include the account_number_reservation_id field in your account application request:
Example request to create an account application with a reservation
curl -X POST \
  -u $API_KEY_ID:$API_SECRET_KEY \
  https://api.treasuryprime.com/apply/account_application \
  -H 'Content-Type: application/json' \
  -d '{
    "person_applications": [
      {
        "id": "apsn_01d5w6yaa6vt",
        "roles": ["owner", "signer"]
      }
    ],
    "primary_person_application_id": "apsn_01d5w6yaa6vt",
    "account_product_id": "apt_11ffk99xyzy",
    "account_number_reservation_id": "anr_123456789"
  }'
For more details on creating an account application, see Account Number Reservation API Reference. When the account application is approved and the account is created, Treasury Prime uses the reserved account number from the reservation instead of allocating a new account number.

​
Retrieving reservations

You can retrieve existing reservations using the GET /account_number_reservation endpoint to list all reservations, or GET /account_number_reservation/:id to fetch a specific reservation by ID.

​
Key considerations

​
Account product compatibility

  • Reservations are account product-specific: Each reservation is tied to a specific account product. You must use the reservation with an account application for the same account product.
  • Prefix validation: Treasury Prime validates that the reserved account number matches your organization’s configured prefix when creating the account.

​
Reservation usage

  • No expiration: Reservations do not expire. A reserved account number remains allocated until you use it to create an account.
  • Cannot be deleted or released: Once created, reservations cannot be deleted or released. The account number remains reserved indefinitely.
  • Single use only: Each reservation can only be used once.

​
Validation and errors

  • Entitlement required: The account_number_reservation entitlement must be enabled for your organization. Attempting to create a reservation without this entitlement returns a 403 error: "You are not entitled to use this feature at this time: account_number_reservation".
  • Account product must exist: The account product ID must reference a valid account product. Attempting to create a reservation with an invalid account product ID returns a 404 not found error.
  • Reservation ID must match account product: When creating an account application, the account_number_reservation_id must reference a reservation for the same account product specified in account_product_id. Mismatched account products return a 400 error: "account_number_reservation_id is not valid for the provided account_product_id".
  • Reservation cannot be reused: After a reservation is used to create an account, attempting to reuse the same reservation ID on another account application returns a 400 error: "account_number_reservation_id already used on an application."

​
Bank-specific behavior

Account number reservation behavior may vary by partner bank:
  • Treasury Prime ledger accounts: Reservations allocate account numbers from the configured prefix for the account product.
  • Partner bank core accounts: Reservations may interact with the partner bank’s account numbering system. Contact support for bank-specific details.
For detailed API endpoint documentation, parameter specifications, and response schemas, see the Account Number Reservation API Reference.