Skip to main content
POST
Create Book Transfer

Authorizations

x-api-key
string
header
required

Your Meow API key, sent in the x-api-key header for authentication.

Headers

Idempotency-Key
string | null

A unique key you generate (1-50 printable ASCII characters, no spaces) so retrying this request never creates a duplicate. Reusing a key is rejected.

Required string length: 1 - 50
Pattern: ^[!-~]+$
x-entity-id
string<uuid>

Optional entity_id to scope requests to a specific entity.

Path Parameters

account_id
string
required

The ID of the account.

Body

application/json
amount
required

Amount to move, in USD.

Required range: 0.01 <= x <= 1000000000
to_account_id
string<uuid>
required

Destination account, owned by the same entity. Use list_bank_accounts to find one.

description
string | null

Description shown on the transfer.

Required string length: 1 - 50
metadata
Metadata · object | null

Your own key/value data to attach to this object. Meow stores it unchanged and returns it on every read of the object and on every webhook event about it, so you can match it back to your own records. Up to 20 pairs; keys up to 40 characters, values up to 200, and 5 KB serialized as JSON in total — note that a non-ASCII character counts as 6 bytes and an emoji as 12. Values must be strings. Meow never interprets it — do not put anything here that needs to stay private.

idempotency_key
string | null
deprecated

Deprecated: send the key in the Idempotency-Key header instead. When both are sent they must match.

Required string length: 1 - 50

Response

Successful Response

amount
string
required

Amount moved, in USD. Echoes the request.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
description
string | null
required

Description shown on the transfer. Echoes the request.

created_time
integer
required

When the transfer was created, as a Unix timestamp in seconds.

transfer_type
enum<string>
required

Rail used. Always book for this endpoint.

Available options:
book,
usdc,
usdt,
pyusd,
cash,
usdg,
ach,
wire,
international
to_account_id
string<uuid>
required

Destination account. Echoes the request.

to_account_name
string
required

Display name of the destination account.

to_account_account_number_masked
string
required

Last 4 digits of the destination account number.

approval_id
string<uuid>
required

Handle for this transfer, returned whether or not an approval policy gated it. Pass it to GET /approvals/{approval_id} to follow the transfer to completion.

id
string | null

Identifier of the book transfer at the bank. null until the transfer leaves the queue, so it is always absent while status is processing or pending_approval. Use approval_id as the stable handle instead.

to_entity_id
string<uuid> | null

Entity that owns the destination account. Set only when that entity differs from the one sending the transfer; null for a transfer between two of your own accounts.

to_entity_name
string | null

Legal name of the entity that owns the destination account. Set under the same condition as to_entity_id.

status
enum<string> | null

Where the transfer is in its lifecycle. pending_approval means an approval policy is holding it; processing means it was queued for submission to the bank.

Available options:
pending,
pending_approval,
canceled,
processing,
error,
sent,
returned,
void
message
string | null

Human-readable next step. Set only when status is pending_approval; otherwise null.

metadata
Metadata · object | null

The metadata attached when this object was created, unchanged. null when none was attached. Rarely, a .created webhook can be published before the create request finishes committing, and that one event reports null; every later event and every read of the object carries the metadata.