Developer docs
Add a transfer
Add a transfer to the account by its UETR, with the amount, currency and date it was sent. The account's plan decides how it is monitored, as for an add on the website. Adding a UETR the account already holds returns that transfer and uses no more of the plan; an archived one is returned archived. Returns the transfer and the outcome.
POST
https://uetr.ai/api/v1/transfers- MCP tool:
add_transfer - Access: a key or connection with read and change access
Request body
| Field | Type | Required | Description |
|---|---|---|---|
uetr | string (matching ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$) | Yes | The transfer's UETR. |
amount | object | Yes | The amount sent and its currency. The currency is a three-letter code in any letter case, one of USD, EUR, GBP, JPY, CHF, CAD, AUD, AED, BDT, BRL, CNY, HKD, IDR, ILS, INR, JOD, MAD, MXN, MYR, NZD, PHP, PKR, PLN, QAR, SAR, SGD, SZL, THB, TRY, TWD, TZS, XAF, XOF, ZAR. The value can have at most 2 decimal places, or none for JPY, XAF and XOF. |
amount.value | number (greater than 0) | Yes | The amount in the supplied currency's major units, not minor units. For example, 129600 USD means USD 129,600.00. |
amount.currency | string (matching ^[A-Za-z]{3}$) | Yes | |
payment_date | string (matching ^\d{4}-\d{2}-\d{2}$) | Yes | The date the payment was sent. It can be no earlier than 2000-01-01 and no later than the next calendar day in UTC. |
Response
| Field | Type | Required | Description |
|---|---|---|---|
transfer | object | Yes | The transfer. |
transfer.id | string (uuid) | Yes | The transfer's id in this account. |
transfer.uetr | string | Yes | The Unique End-to-end Transaction Reference. |
transfer.label | string or null | Yes | The account's own label for the transfer. |
transfer.view | full, free | Yes | full: every report as the paid timeline shows it. free: the free tracker view. |
transfer.status | searching, not_found, check_failed, in_transit, on_hold, credited, rejected, returned, cancelled | Yes | The transfer's current status. |
transfer.position_sentence | string or null | No | get_transfer only, in the full view: the payment position from its status and verified route. A reporting bank alone never establishes a position. list_transfers and webhook events leave it out. |
transfer.status_code | string or null | Yes | The latest ISO 20022 status code, in the full view only: the one the transfer's timeline shows as its status, the same in get_transfer, list_transfers and webhook events. In get_transfer it is the code of the last event that carries one, unless a final outcome is kept after its report is no longer listed. |
transfer.status_explanation | string or null | Yes | What the status code means, in plain English. |
transfer.checks_finished | boolean | Yes | True when no automatic check is scheduled: a final outcome, an archived transfer, or a closed monitoring window. list_transfers judges the transfer's own entry, as the dashboard shows it; get_transfer judges every lookup of the UETR, as the timeline does. |
transfer.amount | object | Yes | The amount entered for the search, as last corrected by the account owner. bank_reported_amount is what a bank reported. |
transfer.amount.value | number | Yes | The amount in the supplied currency's major units, not minor units. For example, 129600 USD means USD 129,600.00. |
transfer.amount.currency | string | Yes | ISO 4217 currency code. |
transfer.payment_date | string | Yes | The payment date entered for the search, as last corrected by the account owner. |
transfer.bank_reported_amount | object or null | Yes | The latest amount a bank reported, with its value date. When no bank stated a currency, the currency is the one entered for the search. A free transfer's figure is the one its free tracker shows, from the reports revealed so far. |
transfer.bank_reported_amount.value | number | Yes | The amount in the supplied currency's major units, not minor units. For example, 129600 USD means USD 129,600.00. |
transfer.bank_reported_amount.currency | string | Yes | ISO 4217 currency code. |
transfer.bank_reported_amount.payment_date | string or null | Yes | |
transfer.last_checked_at | string or null (date-time) | Yes | When the transfer was last checked, within this account's own monitoring of it: never before added_at, and never after its checks ended. |
transfer.monitoring_until | string or null (date-time) | Yes | When this transfer's monitoring window ends or ended (at archiving, if earlier): the paid window, or for a free transfer its free checking window. Checks can finish before it, and a paid transfer still inside its free checking window keeps free checks after it; checks_finished says whether any is scheduled. |
transfer.check_frequency_minutes | integer or null | Yes | How often this transfer's own checks run, in the full view; null when it has none scheduled. |
transfer.archived | boolean | Yes | True when the transfer is archived. |
transfer.added_at | string (date-time) | Yes | When the transfer was added. |
events | array of object or null | Yes | Every bank report, in the full view only, in the stage order of the transfer's timeline, earliest stage first: the last is the latest stage, which may have been received before an earlier stage's report (see observed_at). |
events[].reported_at | string or null (date-time) | Yes | When the bank reported this status, if the report carries that time. |
events[].observed_at | string (date-time) | Yes | When this report was first received. When received_before_added is true, that time is withheld and observed_at only keeps the report's place among the reports: the time this account added the transfer (one millisecond later for each such report received before it), or, when a bank time from before that add follows the report, just before that bank time. |
events[].received_before_added | boolean | Yes | True when this report was first received before this account added the transfer. Its receipt time is not given; reported_at, the bank's own time, is unchanged. |
events[].status | searching, not_found, check_failed, in_transit, on_hold, credited, rejected, returned, cancelled or null | Yes | |
events[].status_code | string or null | Yes | The ISO 20022 status code the bank reported. |
events[].status_explanation | string or null | Yes | |
events[].reporting_bank | object | Yes | The bank that reported. It is not necessarily on the payment's route. |
events[].reporting_bank.name | string | Yes | |
events[].reporting_bank.country | string or null | Yes | |
events[].reporting_bank.bic | string or null | Yes | |
events[].bank_processing_status | string or null | Yes | The bank's own processing status, in its words. |
events[].extended_tracking_status | string or null | Yes | The bank's extended tracking status, in its words. |
events[].amount | object or null | Yes | The amount this report carried, when it carried one. |
events[].amount.value | number | Yes | The amount in the supplied currency's major units, not minor units. For example, 129600 USD means USD 129,600.00. |
events[].amount.currency | string | Yes | ISO 4217 currency code. |
events[].currency | string or null | Yes | The currency the report stated, when it stated one. A report can state a currency with no amount and no fees. |
events[].fees | array of object | Yes | Every fee this report stated, as the bank listed them. |
events[].fees[].value | number | Yes | When currency is supplied, the fee is in that currency's major units, not minor units. A null currency remains unspecified. |
events[].fees[].currency | string or null | Yes | |
events[].fees[].role | total, component, bank | Yes | A stated total, one part of a total, or one bank's charge. |
events[].fees[].label | string or null | Yes | The bank's own name for the fee, if it gave one. |
events[].fees[].charged_by | string or null | Yes | The bank the report says charged it, if any. |
events[].fees[].event_number | integer or null | Yes | The event inside this report's own list of events that the fee belongs to, as the bank record numbers it; null when the fee belongs to the report as a whole. |
events[].payment_date | string or null | Yes | The value date this report carried, when it carried one. |
events[].bank_reference | string or null | Yes | The bank's reference for the payment. |
events[].chips_ssn | string or null | Yes | The CHIPS sequence number the bank reported. |
events[].details | array of object, by kind: cancellation_request, amount, reference, time, duration, exchange_rate, chain_bank, charge_bearer, fee_note, reject_return_reason, message, event_status | Yes | Every further detail the bank record shows for this report, in the record's order, with the bank's times by stage and then durations last. Kinds: amounts by role, references, banks the report names in the payment's chain, exchange rates, the charge bearer, fee notes, reject or return reasons, messages, event statuses and literal cancellation-request codes. A cancellation request is separate from the transaction outcome. Fees are in fees. A detail that restates the bank reference, the bank's status time or a stored amount is left out. New kinds and values can appear within an API version; skip any you do not recognise. |
waiting_at | string or null | Yes | In the full view, the bank the payment is waiting at, when the reports name one; otherwise null. |
free | object or null | Yes | The free tracker's view, in the free view only. |
free.has_activity | boolean | Yes | True once any bank has reported the transfer. |
free.last_report_at | string or null (date-time) | Yes | The newest time a bank itself gave for a report in the free view: the latest reports[].reported_at whose time_source is bank_reported. Null when no listed report gives a bank time; a report without one shows when it was first received. |
free.last_update_at | string or null (date-time) | Yes | When the newest report in the free view was first received, which can be long after the bank's own report time. The newest bank report time is last_report_at. |
free.reporting_bank_countries | array of string | Yes | Home countries of the banks that reported. These are not the payment's route. |
free.reporting_banks | integer | Yes | How many banks have reported. |
free.next_update_at | string or null (date-time) | Yes | When the free view next refreshes. |
free.pending_update_at | string or null (date-time) | Yes | When a newer report becomes visible in the free view. |
free.checks_end_at | string or null (date-time) | Yes | When free automatic checks end. |
free.checks_ended | boolean | Yes | |
free.reports | array of object | Yes | The reports the free view shows, in its order: the report behind the current status first, then newest first by reported_at, with reports that have no time last. At most 50. |
free.reports[].bank_number | integer or null | Yes | The reporting bank, numbered within this transfer; its name is in the full view. |
free.reports[].reported_at | string or null (date-time) | Yes | The report's time. A first_received time from before this account added the transfer reads as the time the account added it (see received_before_added). |
free.reports[].time_source | bank_reported, first_received or null | Yes | Whether the time is the one the bank gave, or when the report was first received. |
free.reports[].received_before_added | boolean | Yes | True when a first_received report was first received before this account added the transfer. |
free.reports[].amount | object or null | Yes | The amount this report carried, when it carried one; the currency is null when the report gave none. |
free.reports[].amount.value | number | Yes | When currency is supplied, the amount is in that currency's major units, not minor units. A null currency remains unspecified. |
free.reports[].amount.currency | string or null | Yes | |
free.reports[].payment_date | string or null | Yes | The value date this report carried, when it carried one. |
free.reports[].details_in_full_view | object | Yes | Which details this report holds that the full view shows. Only their presence is in the free view. |
free.reports[].details_in_full_view.bank_name | boolean | Yes | |
free.reports[].details_in_full_view.bic | boolean | Yes | |
free.reports[].details_in_full_view.status | boolean | Yes | |
free.reports[].details_in_full_view.message | boolean | Yes | |
free.reports[].details_in_full_view.reference | boolean | Yes | |
free.reports[].details_in_full_view.fees | boolean | Yes | |
free.total_reports | integer | Yes | How many reports the free view counts. |
free.report_counts | object | Yes | Counts of details the full view shows, as the free tracker lists them. |
free.report_counts.with_bank_time | integer | Yes | |
free.report_counts.with_fees | integer | Yes | |
free.report_counts.with_messages | integer | Yes | |
free.report_counts.bank_references | integer | Yes | Distinct bank references. |
free.amount_bank_number | integer or null | Yes | The number of the bank (its reports[].bank_number) that reported the transfer's bank_reported_amount. A bank's number, never a count: reporting_banks is the count. |
free.value_date_bank_number | integer or null | Yes | The number of the bank (its reports[].bank_number) that reported the bank-reported value date. A bank's number, never a count. |
free.reported_by | object | Yes | The same bank numbers as amount_bank_number and value_date_bank_number, kept for existing clients. Each is a bank's number, never a count. |
free.reported_by.amount | integer or null | Yes | |
free.reported_by.value_date | integer or null | Yes | |
free.pending_report_at | string or null (date-time) | Yes | The recorded time of the newer report not yet in the free view, when it has one. |
free.attention | action_needed, waiting or null | Yes | A bank's current report flags an issue: action needed, or waiting at a bank. The code and bank are in the full view. |
free.delay | object or null | Yes | Whole days since any bank last reported, when that is longer than usual. |
free.delay.days | integer | Yes | |
free.delay.tier | slow, very_slow | Yes | |
free.payment_route | object or null | Yes | The sending and beneficiary banks the reports confirm. |
free.payment_route.sender | object or null | Yes | |
free.payment_route.sender.name | string or null | Yes | The bank's name, when the directory knows it. |
free.payment_route.sender.bic | string | Yes | |
free.payment_route.beneficiary | object or null | Yes | |
free.payment_route.beneficiary.name | string or null | Yes | The bank's name, when the directory knows it. |
free.payment_route.beneficiary.bic | string | Yes | |
free.payment_route.other_banks | boolean | Yes | True when other banks took part; they are named in the full view. |
corrections_remaining | integer or null | Yes | How many more corrections the account owner can make to the entered amount, currency and payment date now that a bank has reported. Null when no bank has reported, when the API key or connected app is not the account owner's, when the transfer is archived, or when the count could not be read. |
outcome | created, existing, archived | Yes | created: a new transfer. existing: the account already held it. archived: the account holds it archived; restore it to resume monitoring. |
Example
curl -X POST "https://uetr.ai/api/v1/transfers" \
-H "Authorization: Bearer $UETR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"uetr":"eb6305c9-1f7f-49de-aed0-16487c27b42d","amount":{"value":1500.5,"currency":"USD"},"payment_date":"2026-10-01"}'The answer:
{
"transfer": {
"id": "8d2f6b1e-4c3a-4f7d-9e8b-5a1c2d3e4f60",
"uetr": "eb6305c9-1f7f-49de-aed0-16487c27b42d",
"label": null,
"view": "full",
"status": "searching",
"position_sentence": null,
"status_code": null,
"status_explanation": null,
"checks_finished": false,
"amount": {
"value": 1500.5,
"currency": "USD"
},
"payment_date": "2026-10-01",
"bank_reported_amount": null,
"last_checked_at": "2026-10-14T09:00:00.000Z",
"monitoring_until": "2026-11-14T09:00:00.000Z",
"check_frequency_minutes": 60,
"archived": false,
"added_at": "2026-10-14T09:00:00.000Z"
},
"events": [],
"waiting_at": null,
"free": null,
"corrections_remaining": null,
"outcome": "created"
}Refusals
Besides the access refusals every call can meet, this call can answer:
read_only_credential(403): Read-only key or connection.machine_writes_disabled(503): Changes are switched off.request_too_large(413): Request too large.unsupported_media_type(415): Body not sent as JSON.active_transfer_limit(409): Active transfer limit reached.monthly_limit_reached(409): Monthly transfer limit reached.rescue_limit(409): Rescue covers one transfer.lookup_limit(429): Lookup limit reached.plan_unverified(503): Plan could not be verified.plan_expired(409): Monitoring access has ended.transfer_archived(409): Transfer is archived.account_email_missing(409): No email address on the account.check_not_started(503): Check not started.not_permitted(403): Not permitted.demo_transfer(409): The demo transfer cannot be changed.