List approval requests
const url = 'https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/approvals?status=pending';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/approvals?status=pending' \ --header 'Authorization: Bearer <token>'List approval requests for your organization.
Filter by status (pending, approved, rejected, cancelled), several at once via statuses, or get all. Default shows only pending requests.
Returns the canonical cursor list envelope {data, has_more, next_cursor}
alongside pending_count and can_take_action. Pass cursor (the last
approval’s id) to fetch the next page.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The organization’s ID
Query Parameters
Section titled “Query Parameters”Filter by status. Default: pending
Filter by several statuses at once. Takes precedence over status when non-empty.
Page size, clamped to 1..100 (default 50)
Approval id of the last item from the previous page
Responses
Section titled “Responses”Approval requests
object
List of approval requests
object
Email of who approved/rejected (if processed). Prefer approver.email
When approved/rejected
Why the request was refused, as given to rejectRequest. Only ever set on a rejected approval, and null even then when the rejecter gave no reason.
Prefer requester.email
Prefer requester.name
object
object
Coin quantity landing at the destination
Coin quantity deducted from the organization, fees included
object
Denomination of amount/amount_with_fees — the coin’s symbol
object
The on-chain address funds are sent to
object
Set when the contact has been soft-deleted since the payment was created
Raw crypto-rail state (e.g. awaiting_approval). Not the canonical cross-rail Payment.status — read the payment via getPayment for that.
Contact category the payment was tagged with
On-chain transaction id; null until broadcast
object
object
Amount deducted from the organization
Denomination of amount; null on pre-backfill rows
object
object
object
Why the last registration attempt failed, in customer-facing copy. Null once active.
Whether the destination is registered with the payout partner. Only active destinations can be quoted or paid.
object
object
object
Whether the wallet belongs to the sender. An own-account wallet completes the travel rule with no counterparty.
object
object
object
object
The payee’s country (ISO alpha-2).
The payee’s Ele ID as it resolved when the contact was saved, without the @.
Whether the payee is a registered business rather than an individual.
Always true: an Ele ID resolves only to a verified organization.
The payee’s verified business or owner name behind that Ele ID.
object
Set when the contact has been soft-deleted since the payment was created
The accepted payout quote this payment is priced against
object
The Elephants component of the total fee
Elephants fee as a rate
True when this quote can no longer be executed and Approve would fail — offer a re-quote instead. Server-derived from the same check executePayment applies.
Effective expiry — the quote’s own, else its partner quote’s; null when open-ended
The fixed (network/partner) component of the total fee
Rail the payout is routed over
Raw fiat-rail state (e.g. awaiting_approval). Not the canonical cross-rail Payment.status — read the payment via getPayment for that.
object
object
Amount moved, in currency
Currency of amount
What the payee will see on their transaction
How the payee was addressed (e.g. ele_id)
The Elephants organization the money goes to: the verified name behind the Ele ID it was sent to (verified: true), else the organization’s name
object
object
object
object
Approval state of the request governing this contact
object
object
object
Why the last registration attempt failed, in customer-facing copy. Null once active.
Whether the destination is registered with the payout partner. Only active destinations can be quoted or paid.
object
object
object
Whether the wallet belongs to the sender. An own-account wallet completes the travel rule with no counterparty.
object
object
object
object
The payee’s country (ISO alpha-2).
The payee’s Ele ID as it resolved when the contact was saved, without the @.
Whether the payee is a registered business rather than an individual.
Always true: an Ele ID resolves only to a verified organization.
The payee’s verified business or owner name behind that Ele ID.
object
The domain event’s id
The event stream it was written to, e.g. “payment_contact_events”
The id of the aggregate the event belongs to
The event type, e.g. “payment_contact.created”
Contact name
Optional nickname
Contact category
object
object
object
Set when this contact has been soft-deleted
When the invoice was paid; null before then
Days from today (UTC) to due_date; negative when overdue
object
object
Whether the invite grants a card
Monthly card limit the invitation sets, in whole US dollars
Who is being invited
object
Role the invitee joins with
object
object
Which side row amounts are entered on
How much the source balance is short of total_deducting, for a viewer who may see balances; null when it covers the batch, the viewer may not see it, or the batch is past approval (its total is on hold)
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Rows whose quote has lapsed; requote the batch when non-zero
Every ready row’s fee lines summed by code in the source currency, with rate and bands null; empty until reviewed, or when a row’s fee is in another currency
object
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The points-cap band split behind a merged booster component: each band’s own rate and the slice of the amount it billed. Null on every other component.
object
The one provider rate the batch was priced at (payout currency per unit of source currency, before fees), when every ready row quotes the same pair and rate; null before review, when the source equals the payout currency, or when rows differ. Fees vary per row by band, so the all-in rate does not.
Rows whose payment is on hold; the batch stays executing while non-zero
The batch’s name
Live rows with a needs_fix issue; pricing and submit wait on zero
The currency every recipient receives
Payout reason code shared by every row
Ele reward points the ready rows earn together; null until reviewed
The batch this one was rerun from
What the batch still holds on the source balance: the total from approval, less each row’s share as it is sent or given back; null before approval and once the batch completes
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The batch whose failed rows this one retries
object
The amount entered for this row, on amount_side; null on a fresh draft row
What differs from the uploaded line: each upload column the row was edited on since the import (the sheet’s text as from, the row’s value as to). Empty for a row as uploaded, a row that did not come from a file, and a removed row.
object
The upload column whose value the row no longer matches
The sheet’s text
The row’s value now; null when cleared
The contact’s name, or the inline recipient’s account holder name
object
object
object
Why the last registration attempt failed, in customer-facing copy. Null once active.
Whether the destination is registered with the payout partner. Only active destinations can be quoted or paid.
object
object
object
Whether the wallet belongs to the sender. An own-account wallet completes the travel rule with no counterparty.
object
object
object
object
The payee’s country (ISO alpha-2).
The payee’s Ele ID as it resolved when the contact was saved, without the @.
Whether the payee is a registered business rather than an individual.
Always true: an Ele ID resolves only to a verified organization.
The payee’s verified business or owner name behind that Ele ID.
Deprecated: read destination instead. Recipient currency and masked account, e.g. “VND ••4471”
Set at review. ready rows carry a quote; every other value names why the row cannot be sent. Null before the first review.
Why the row cannot be or was not paid; null when nothing is wrong. At review, the detail behind the blocker (the issue, or the reason the inline recipient could not be saved). From execution on, a stable code for the client to put words to: recipient_not_registered or execution_blocked, quote_drift, insufficient_funds, cancelled_before_execution, failed_before_execution, already_terminal or execution_refused; and once the batch has sent the payment, payment_failed, payment_reversed or payment_cancelled.
What stops this row from being paid, checked on every read of a draft against the destination field mapping; empty once the row is fine, and always empty after the draft is submitted
object
Stable reason: missing_amount, missing_field, invalid_field, bank_not_found, contact_missing, contact_not_approved, destination_not_ready, no_fiat_destination, currency_mismatch, corridor_unsupported, recipient_required, duplicate_recipient
The recipient input field to fix (e.g. account_number), or amount; null when the issue is about the row as a whole
needs_fix blocks pricing and submit; a warning never does
Plain words for the customer
How the row got here: uploaded from a file, address_book, manual (typed in)
Null while the row pays an inline recipient that is not a contact yet
The payment this row became at submit; pass to getPayment
The row’s payment as it stands, null before submit: awaiting_approval, on_hold (held: the batch waits and resumes it once it can be sent), submitted, processing, succeeded, failed, cancelled, reversed (refunded to the balance).
The row’s accepted quote, priced at review
object
What the batch pays for this row, fees included
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
True once this quote can no longer be executed; approving the batch would fail. Requote the batch to refresh every expired row.
The row’s fee lines, as a single payment’s quote lists them: the partner (network) fee, the Elephants fee and any additive fee
object
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The points-cap band split behind a merged booster component: each band’s own rate and the slice of the amount it billed. Null on every other component.
object
The provider’s rate, payout currency per unit of source currency, before fees (a single quote’s gross_rate)
What the recipient receives
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Every fee line summed; null when the partner fee is in another currency
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The recipient a row pays while it is not a contact yet: the bank fields as given, before submit turns them into a contact and destination
object
What the recipient sees on their statement; the batch’s text when null
Set when the row was taken out of the draft; such rows are never paid
Written once at execution; null until then. sent means the payment was handed to execution: its own status says whether it is submitted, on hold or done. failed carries the refusal in error; cancelled if withdrawn before its turn.
The row as the uploaded file had it: one value per template column, as text
object
The source balance as it stands, for a viewer who may see balances; null otherwise
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
The balance the batch is paid from; null until one is chosen
object
Signed URL to GET the file as an attachment, no bearer needed; valid until download_url_expires_at, after which reading the batch again mints a fresh one
Bank statement text shared by every row
draft while rows are edited and priced; awaiting_approval once submitted; executing after approval while rows are sent; completed when every row has a result; cancelled if cancelled or rejected before execution.
Sum of every ready row’s cost; null until reviewed
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Every ready row’s fees summed; null until reviewed, or when a row’s fee is in another currency
object
Decimal string at the currency’s precision, e.g. “10.50”
Three-letter currency code, e.g. “USD”
Live rows with a warning
Human-readable description of what’s being approved
The id of the entity named by target_type
Which kind of entity this approval governs
Number of pending approvals
Example
{ "data": [ { "action_type": "withdrawal", "status": "pending", "subject": { "type": "crypto_outgoing" }, "target_type": "crypto_outgoing" } ]}Invalid request parameters or body
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
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
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
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
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
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.
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
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
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.
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
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
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.
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
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
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
object
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
object
Example
{ "error": { "type": "rate_limited" }}Headers
Section titled “Headers”How long to wait before retrying, expressed as delay seconds or an HTTP date
Unexpected server 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
object
Structured error details (e.g. validation errors), when present
Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.
Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.
object
Method used to deliver this challenge
Challenge expiry
Sudo session ID returned to completeStepUp
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.
Available verification methods
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.
object
object
Machine-readable error code from a stable vocabulary (open enum — handle unknown values)
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" }}