Skip to content

List transactions

GET
/api/v1/organizations/{organization_id}/transactions
curl --request GET \
--url https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/transactions \
--header 'Authorization: Bearer <token>'

List an organization’s transactions — card spend, payments in and out, swaps, fees, purchases, and points — newest first, with keyset pagination (pass cursor = the last transaction’s id). Filter by type, category, currency, date range, card, or free-text search.

organization_id
required
string format: uuid

The organization’s ID

card_id
string format: uuid

Only include transactions for this card

payment_batch_id
string format: uuid

Only include the payments of this payment batch, whatever their approval state

source_types
Array<string>

Canonical transaction types to include

categories
Array<string>
Allowed values: add_money billing_invoice card_spend fiat_swap send_money points_spend points_accrual purchase

Customer-facing transaction categories to include. Fees categorize with their parent activity: “add_money” also returns fees charged on those deposits.

currencies
Array<string>
Allowed values: USD CAD EUR GBP HKD SGD USDC USDT TSOL ELEPOINTS

Currencies to include, matched against the organization’s own balances. A payout that debits USD and lands THB is USD here. A swap matches both the currency it sold and the one it bought.

date_start
string format: date
date_end
string format: date
timezone
string
user_ids
Array<string>
hold
boolean
needs_sender_travel_rule
boolean
approval_status
Array<string>
exclude_with_expense
boolean
q
string
limit
integer

Page size, clamped to 1..100 (default 50)

cursor
string format: uuid

Transaction id of the last item from the previous page

Transactions

Media typeapplication/json
TransactionList
object
data
required
Array<object>
One of: discriminator: type
CardTransaction
object
amounts
required
object
base_amount
required
string
base_currency
required

ISO 4217 alpha-3 currency code

string
/^[A-Z]{3}$/
local_amount
required
string
local_currency
required

ISO 4217 alpha-3 currency code

string
/^[A-Z]{3}$/
approval_request
required
One of:
object
id
required
string format: uuid
status
required
string
Allowed values: approved cancelled pending rejected
approval_request_id
required
string | null format: uuid
card
required
object
id
required
string format: uuid
last_four
required
string
name
required
string
status
required
string
direction
required
string
Allowed values: in out
effect
required
One of:
TransactionEffect
object
base_amount
required
string
currency
required

ISO 4217 alpha-3 currency code, or ELEPOINTS for points-denominated effects

string
direction
required
string
Allowed values: in out
fees
required
Array<object>
object
amount
required
string
bands
required

The points-cap band split behind a merged booster line: each band’s own rate and the slice of the amount it billed. Null on every other line.

Array<object> | null
object
amount
required
string
band
required
string
Allowed values: within_allowance overage
rate
required
string
effective_rate
required

The line’s own magnitude against the effect’s base — what it actually cost per unit, which caps and clips can put below the face rate in rate.

string | null
name
required
string | null
rate
required
string | null
type
required
string
Allowed values: platform additive network
total
required
string
total_fee_amount
required
string
effective_at
required
string | null format: date-time
expense_id
required
string | null format: uuid
id
required
string format: uuid
merchant
required
object
city
required
string | null
country
required
string
name
required
string
merchant_category
required
string | null
payment_batch
required
One of:
object
id
required
string format: uuid
name
required

The batch’s name, if it was given one

string | null
payment_batch_id
required

The payment batch this transaction is one row of; pass to getPaymentBatch. Null when the transaction is not a batch payment.

string | null format: uuid
points
required
string | null
points_allowance
required

The slice of points the monthly allowance covered — the receipt’s “included with your plan” figure, and the slice the fee’s within-allowance rate was priced on. Tracks points_cap_outcome: not_capped means the whole award is here. Where no monthly cap is configured the whole award reads as allowance. “0” when the award holds nothing covered; null only when there is no award at all.

string | null
points_before_cap
required

The points the transaction would have earned before the monthly allowance cut it. Populated only on an award no booster applied to that met an exhausted or nearly exhausted allowance; null everywhere else — boosted earning is never reduced.

string | null
points_cap_outcome
required
One of:
string
Allowed values: not_capped partially_capped fully_capped
points_overage
required

The slice of points past the monthly allowance — the receipt’s “with booster” figure, split against the allowance headroom at the award’s most recent amendment. The charged fee keeps the split struck at authorisation (an amendment scales the charge in proportion, it does not re-split it), so after an amendment that moves the award this pair can differ from the fee charged beside it. Tracks points_cap_outcome: non-zero exactly when a boosted award straddled or passed the ceiling — billed, never refused; an award no booster applied to stops at the ceiling instead and reads “0” here. points_allowance + points_overage = points whenever an award exists; a voided award reads 0 / 0. Null only when there is no award at all.

string | null
points_reversed
required

Whether the source transaction was undone. Every full reversal voids the whole award — fees and points follow the money in the same proportion — so a reversed award’s points figure reads “0” and its points_allowance / points_overage split reads 0 / 0. points_cap_outcome keeps the award’s cap history. Null when there is no award at all.

boolean | null
recorded_at
required
string format: date-time
source
required
object
id
required
string format: uuid
resource
required
string
status
required
string
timeline
required
Array<object>
object
base_amount
required
string | null
local_amount
required
string | null
local_currency
required

ISO 4217 alpha-3 currency code

string | null
/^[A-Z]{3}$/
occurred_at
required
string format: date-time
status
required
string
type
required
string
Allowed values: card_transaction
user
required
One of:
object
avatar
required
string | null
first_name
required
string | null
last_name
required
string | null
voided
required
boolean
has_more
required
boolean
next_cursor
required
string | null format: uuid

Example

{
"data": [
{
"approval_request": {
"status": "approved"
},
"direction": "in",
"effect": {
"direction": "in",
"fees": [
{
"bands": [
{
"band": "within_allowance"
}
],
"type": "platform"
}
]
},
"points_cap_outcome": "not_capped",
"type": "card_transaction"
}
]
}

Invalid request parameters or body

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Missing, invalid, or expired bearer token

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}

Too many requests

Media typeapplication/json
RateLimitedError
object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string
error
required
object
type
required
string
Allowed value: rate_limited

Example

{
"error": {
"type": "rate_limited"
}
}
Retry-After
required
string

How long to wait before retrying, expressed as delay seconds or an HTTP date

Unexpected server error

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
"error": {
"details": "example",
"message": "example",
"request_id": "example",
"step_up": {
"delivery": "example",
"expires_at": "2026-04-15T12:00:00Z",
"id": "example",
"match_code": "example",
"methods": [
"example"
],
"step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"webauthn": {
"allow_credentials": [
{
"id": "example",
"transports": [
"example"
],
"type": "example"
}
],
"challenge": "example",
"challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
"rp_id": "example",
"timeout": 1,
"user_verification": "example"
}
},
"type": "example"
}
}