Create a capital account | The Penny Inc

curl -X POST https://sandbox.api.thepennyinc.com/accounts/capital/ \
     -H "X-Penny-As-Business: business_01a083e2-82ed-7a5c-9d1e-3b6f0c2a4d71" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "parent_account_id": "account_01a083e2-82ed-720b-b737-11cf8b97978e"
}'

{
  "account_id": "account_019372e3-b8dc-7de2-80b6-b8dcde20b6c9",
  "version": 1,
  "version_time": "2024-01-15T10:30:00Z",
  "program_id": "program_019377de-7f88-7f02-894f-7f88f0294fcb",
  "business_id": "business_01937b95-484e-75af-8c68-484e5afc68d3",
  "business_entity_id": "business_entity_01937c9d-3a1e-72b0-8881-3a1e2b088159",
  "status": "active",
  "active": true,
  "currency": "USD",
  "root": true,
  "available_balance": "1000.00",
  "total_balance": "1050.00",
  "alias": "operations-account",
  "description": "Primary operating account for day-to-day spend.",
  "type": "capital",
  "parent_account_id": "account_019372e3-b8dc-7de2-80b6-b8dcde20b6c9",
  "spend_control_id": "spend_control_019379d9-a170-796b-867a-a17096b67a21",
  "auto_top_up": {
    "source_account_id": "account_019372e3-b8dc-7de2-80b6-b8dcde20b6c9",
    "source_account_type": "capital",
    "threshold_amount": "500.00",
    "top_up_amount": "1000.00"
  },
  "low_balance_notification": {
    "threshold_amount": "200.00"
  }
}

Create a new capital account under an existing parent capital account.

Required permissions: account:create.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

parent_account_idstringRequired

Unique identifier of the parent Capital Account. The new account is created within this account's hierarchy and inherits its program and currency.

aliasstring or nullOptional<=64 characters

Optional human-readable label for the account.

descriptionstring or nullOptional<=256 characters

Optional description of the account's intended use.

spend_control_idstringOptional

Optional spend control to attach at creation.

activebooleanOptionalDefaults to true

Whether the account is created in an active state.

auto_top_upobject or nullOptional

Optional automatic top-up configuration applied at creation.

low_balance_alertobject or nullOptional

Optional low-balance alert configuration applied at creation.

Response

The newly created capital account.

account_idstring

Unique identifier for the account.

versioninteger

The current version of the account record.

version_timedatetime

ISO-8601 timestamp of the most recent account update.

program_idstring

The identifier of the program associated with this account.

business_idstring

The identifier of the business associated with this account.

business_entity_idstring

The identifier of the business entity associated with this account.

statusenum

The current operational status of the account.

Allowed values:

activeboolean

Whether the account is currently active and available for use.

currencyenum

ISO-4217 currency code for the account.

Allowed values:

rootboolean

Whether this is the root capital account for the business.

available_balancestringformat: "^-?\d+(\.\d+)?$"

The balance currently available for transactions, as a decimal string.

total_balancestringformat: "^-?\d+(\.\d+)?$"

The total balance including reserved funds, as a decimal string.

aliasstring or nullOptional

An optional label for the account.

descriptionstring or nullOptional

An optional description of the account's purpose.

typeenumOptionalDefaults to capital

Account types exposed to client-facing API responses.

Allowed values:

parent_account_idstring or nullOptional

The identifier of the parent account if this account is part of a hierarchy.

spend_control_idstring or nullOptional

The identifier of the spend control applied to this account.

auto_top_upobject or nullOptional

Automatic top-up configuration, if enabled.

low_balance_notificationobject or nullOptional

Low-balance notification configuration, if enabled.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

Authentication

Headers

Request

Response

Errors