API reference

raw_transactionobject · optional

The transaction with your system’s field names, instead of transaction. The mapping is set when you go live.

request_idstring · optional

Identifier of the analysis: yours, or one YARDA generates. An identifier already used is refused (409).

transactionobject · optional

The transaction, with the standard field names. It or raw_transaction is required.

transaction.amountnumber · required

Amount, zero or more, in the stated currency.

transaction.receiver_idstring · required

The receiver’s identifier in your system. Pseudonymised on arrival.

transaction.sender_idstring · required

The sender’s identifier in your system. Pseudonymised on arrival.

transaction.transaction_idstring · required

Your reference for the transaction, unique within your institution (100 characters at most).

transaction.agent_idstring · optional

The agent who handled the operation. Pseudonymised on arrival.

transaction.cash_point_idstring · optional

The agent’s till or pick-up point. Pseudonymised on arrival.

transaction.channelstring · optional

Channel of the operation: agent, app, USSD or web, for example.

transaction.corridorstring · optional

The transaction’s corridor, as named in your profile.

transaction.currencystring · optional

ISO 4217 currency code, or a stablecoin ticker such as EURC or USDC.

transaction.device_changed_atstring (date-time) · optional

Date of the sender’s last change of device.

transaction.device_idstring · optional

The sender’s device or app installation. Pseudonymised on arrival.

transaction.fee_amountnumber · optional

Fee charged to the sender, in the operation’s currency; compared with your tariff grid.

transaction.funding_methodstring · optional

How the sender paid: cash, mobile_money, bank_account, card, crypto or other.

transaction.ip_addressstring · optional

IP address of a remote operation (IPv4 or IPv6). Kept under pseudonym.

transaction.kyc_tierstring · optional

The sender’s customer due diligence tier in your system.

transaction.locationstring · optional

Accepted for compatibility, never stored.

transaction.merchant_idstring · optional

The merchant paid. Pseudonymised on arrival.

transaction.metadataobject · optional

Additional information from your system; the analysis does not use it.

transaction.original_transaction_idstring · optional

For a refund or a reversal, the reference of the operation it undoes.

transaction.payout_amountnumber · optional

Amount paid to the receiver, when it differs from the amount sent (another currency, fees deducted).

transaction.payout_currencystring · optional

Currency paid to the receiver.

transaction.payout_methodstring · optional

How the receiver was paid: cash, mobile_money, bank_account, card, crypto or other.

transaction.pin_reset_atstring (date-time) · optional

Date of the sender’s last PIN or password reset.

transaction.receiver_countrystring · optional

The receiver’s country, as an ISO code (for example CI).

transaction.receiver_namestring · optional

The receiver’s name. Required by law on every transfer and screened against your sanctions lists. Compared in memory, never stored.

transaction.receiver_phonestring · optional

The receiver’s phone number. Pseudonymised on arrival.

transaction.sender_addressstring · optional

The sender’s address, one of the ways the law requires to identify them. Only its presence is checked; never stored.

transaction.sender_balancenumber · optional

Balance of the sender’s account or wallet before the operation.

transaction.sender_birth_datestring (date) · optional

The sender’s date of birth; with the place of birth, it identifies them. Only its presence is checked; never stored.

transaction.sender_birth_placestring · optional

The sender’s place of birth. Only its presence is checked; never stored.

transaction.sender_countrystring · optional

The sender’s country, as an ISO code (for example SN).

transaction.sender_declared_monthly_amountnumber · optional

Monthly amount the sender declared at onboarding.

transaction.sender_id_numberstring · optional

Number of the sender’s official identity document. Only its presence is checked; never stored.

transaction.sender_namestring · optional

The sender’s name. Required by law on every transfer (uniform law, article 39; Regulation (EU) 2023/1113) and screened against your sanctions lists. Compared in memory, never stored.

transaction.sender_phonestring · optional

The sender’s phone number. Pseudonymised on arrival.

transaction.sender_sincestring (date) · optional

When the relationship with the sender started.

transaction.sender_typestring · optional

Natural person (person) or legal entity (legal_entity).

transaction.sim_swap_atstring (date-time) · optional

Date of the sender’s last SIM swap, if you know it.

transaction.statusstring · optional

Status of the operation: completed, pending, failed, cancelled or reversed. The usual words of your exports are recognised (success, refunded, annulé...).

transaction.timestampstring (date-time) · optional

Date and time of the transaction, in ISO 8601 format.

transaction.transaction_typestring · optional

Type of operation: cash_in, cash_out, p2p, merchant_payment, bill_payment or remittance, for example.

transaction.wallet_idstring · optional

The sender’s wallet, when distinct from the sender. Pseudonymised on arrival.

anomaly_scorenumber · required

Score of the unusual behaviour model, from 0 to 1.

client_idstring · required

Your institution’s identifier at YARDA.

client_phasestring · required

The learning phase of your space.

decisionstring · required

The decision. block appears only if you have allowed blocking.Values: allow, review, alert, block

explanationsarray of object · required

Each model’s contribution to the final score.

explanations[].scorenumber · required

Its score, from 0 to 1.

explanations[].sourcestring · required

The model concerned.

explanations[].weightnumber · required

Its weight.

explanations[].weighted_scorenumber · required

Its score multiplied by its weight.

explanations[].detailsarray of string · optional

Details specific to the model.

final_scorenumber · required

Final score, from 0 to 1: the transaction’s rank within your own traffic.

inference_time_msnumber · required

The time the analysis took on the server, in milliseconds.

ml_scorenumber · required

Score of the supervised model, from 0 to 1, when such a model is in service.

request_idstring · required

Identifier of the analysis: yours, or one YARDA generates. An identifier already used is refused (409).

thresholdsobject · required

The review, alert and block thresholds applied to this analysis.

timestampstring (date-time) · required

Date and time of the response.

transaction_idstring · required

Your reference for the transaction.

weightsobject · required

Weight of each model in the final score.

decision_causeobject · optional

The decisive cause of the decision.

decision_cause.decisionstring · required

The decision this cause explains.

decision_cause.kindstring · required

Kind of cause: score_band, score_rules, detection_cap, typology, list_entry, declarative, on_error or blocking_disabled.

decision_cause.reason_enstring · required

The cause, written in English.

decision_cause.reason_frstring · required

The cause, written in French.

decision_cause.detailsobject · optional

The values quoted in the cause: score, threshold, version.

decision_cause.originalobject · optional

For blocking_disabled, the cause that asked for the block.

decision_cause.rulestring · optional

The rule that decided, when it is a rule.

decision_policyobject · optional

Present when your policy changed the decision: a block returned as an alert, for example.

decision_policy.codestring · required

Kind of adjustment, today blocking_disabled.

decision_policy.decisionstring · required

The decision after the adjustment.

decision_policy.original_decisionstring · required

The decision before the adjustment.

decision_policy.reason_enstring · required

The adjustment, explained in English.

decision_policy.reason_frstring · required

The adjustment, explained in French.

degradedboolean · optional

True when a model could not answer: the decision then follows the floor set by your policy.Default: false

legalobject · optional

The legal floor, apart from the decision: the sender and the receiver screened against your sanctions lists when you send their names (sender_name, receiver_name).

legal.holdboolean · required

True when a party resembles an entry of a sanctions list, or when screening failed: do not execute the transfer until a person has ruled in the console. The hold changes neither the score nor the decision. You are told when it ends by webhook (legal.hold.updated) and can follow each hold with GET /v1/legal-holds.

legal.screeningstring · required

screened: the named parties were screened; names_absent: no name was sent, nothing could be screened; unavailable: none of your lists is loaded; failed: screening failed and the transfer is held.Values: screened, names_absent, unavailable, failed

legal.cashobject · optional

The parties’ cash of the day, for a customer answering to the UEMOA: for each party that handed in or received cash, the local day, the total in FCFA (this operation included) and the number of operations, with the thresholds of 9,000,000 FCFA (identification, uniform law art. 17 i) and 15,000,000 FCFA (report to the CENTIF, art. 72). Null for an operation without cash.

legal.dutiesarray of string · optional

What your institution must do, never a hold: cash_identification, identify the customer whose cash of the day goes beyond 9,000,000 FCFA; cash_report, report the cash to the CENTIF from 15,000,000 FCFA.

legal.list_setstring · optional

The versions of the lists the parties were screened against.

legal.partiesarray of object · optional

For each named party: its role, its pseudonym, its status (clear, potential, confirmed, dismissed), the references of the entries raised and the best score.

legal.reasonsarray of string · optional

The reasons for the hold: sanctions_potential_sender, sanctions_potential_receiver, sanctions_confirmed_sender, sanctions_confirmed_receiver, screening_failed, transfer_information_incomplete.

legal.transfer_informationobject · optional

Whether the transfer carries the information the law requires on its parties: status (complete, incomplete, not_applicable, or attested when your institution carries out the analysis of its alerts and keeps this information itself), what is missing (payer_name, payee_name, payer_identification) and the regimes applied (uemoa, eu). When incomplete, the transfer is held: do not execute it before obtaining the information.

model_version_idinteger · optional

The version of the supervised model that scored the transaction, if any.

reasonsarray of object · optional

The behaviour variables that explain the score.

reasons[].directionstring · required

high if the value is unusually high, low if it is low.

reasons[].featurestring · required

The variable concerned.

reasons[].typicalnumber · required

The usual value.

reasons[].valuenumber · required

The value for this transaction.

reasons[].weightnumber · required

The reason’s weight: rarity for the behaviour model, contribution towards fraud for the supervised model.

reasons[].sourcestring · optional

The model giving the reason: anomaly or supervised.

triggered_rulesarray of object · optional

The rules and typologies that acted on the transaction.

triggered_rules[].rule_namestring · required

The rule’s name.

triggered_rules[].rule_typestring · required

typology (built-in typology or block list) or declarative (your rule).

triggered_rules[].scorenumber · required

The score increase asked for, 1 when it asks for none.

triggered_rules[].descriptionstring · optional

Why the rule acted, in English.

triggered_rules[].severitystring · optional

The minimum decision imposed (review, alert, block), or flag.Default: low

triggered_rules[].versioninteger · optional

The version of your rule.

warningsarray of object · optional

What the transaction holds that its model did not learn: a field filled in nearly every training transaction and absent here, or a value never seen. The transaction may look unusual for that reason alone: check what your integration sends. These warnings never change the decision; an empty list when there are none.

warnings[].codestring · required

field_absent (missing field) or unknown_value (value unknown to the model).

warnings[].fieldstring · required

The transaction field concerned.

warnings[].message_enstring · required

The warning, written in English.

warnings[].message_frstring · required

The warning, written in French.

warnings[].training_sharenumber · required

Share of the training transactions in which the field is filled, from 0 to 1.

warnings[].valuestring · optional

For unknown_value, the value received.

request_idstring · required

The analysis identifier, returned by the scoring call.

The content of this response is not yet described field by field in the OpenAPI description.

request_idstring · required

The analysis identifier, returned by the scoring call.

labelstring · required

The fraud type from your taxonomy, or legitimate.

investigator_idstring · optional

The person who labelled it, in your system.

notesstring · optional

A free note.

The content of this response is not yet described field by field in the OpenAPI description.

labelsarray of object · required

The labels, from 1 to 1,000.

labels[].event_atstring (date-time) · required

Date of the fact: neither before the transaction nor in the future.

labels[].is_fraudboolean · required

True for fraud, false for a legitimate operation.

labels[].sourcestring · required

Where the information comes from: complaint, reversal or investigation.Values: complaint, reversal, investigation

labels[].transaction_idstring · required

Your reference for a transaction YARDA has already received.

labels[].fraud_typestring · optional

The fraud type, which must belong to your taxonomy.

labels[].notestring · optional

A free note, 2,000 characters at most.

createdinteger · required

Labels recorded for the first time.

rejectedarray of object · required

Labels refused, each with its reason.

rejected[].reasonstring · required

Why it was refused.

rejected[].transaction_idstring · required

The reference of the transaction concerned.

updatedinteger · required

Labels that replace an earlier one.

The content of this response is not yet described field by field in the OpenAPI description.

disputesarray of object · required

1 to 1,000 disputes.

disputes[].external_idstring · required

Your reference of the dispute, the same at every update.

disputes[].kindstring · required

complaint, dispute or chargeback.Values: complaint, dispute, chargeback

disputes[].opened_atstring (date-time) · required

When the customer filed it (ISO 8601).

disputes[].reasonstring · required

Why: fraud, unauthorised, scam, account_takeover (fraud claims), or not_received, processing_error, duplicate, other.Values: fraud, unauthorised, scam, account_takeover, not_received, processing_error, duplicate, other

disputes[].transaction_idstring · required

Your reference of the contested transaction.

disputes[].amountnumber · optional

The amount contested.

disputes[].currencystring · optional

The currency of the amount contested.

disputes[].fraud_typestring · optional

The fraud type of your taxonomy, for a fraud claim.

disputes[].notestring · optional

A note of your own, without names or contact details.

disputes[].resolved_atstring (date-time) · optional

When you concluded it; required when upheld or rejected.

disputes[].statusstring · optional

open (default), upheld, rejected or withdrawn.Values: open, upheld, rejected, withdrawnDefault: open

createdinteger · required

Labels recorded for the first time.

labels_retractedinteger · required

Labels taken back (a withdrawal, or a reason no longer fraud).

labels_writteninteger · required

Labels written or corrected for the models.

refusedarray of object · required

The entries refused, each with its reason.

refused[].external_idstring · required

The reference of the refused dispute.

refused[].reasonstring · required

Why it was refused.

updatedinteger · required

Labels that replace an earlier one.

statusstring · optional

clear (no match), potential (to examine), confirmed or dismissed (a person’s decision).Values: open, upheld, rejected, withdrawn

kindstring · optional

Only this kind: complaint, dispute or chargeback.Values: complaint, dispute, chargeback

transaction_idstring · optional

Your reference for the transaction.

limitinteger · optional

How many at most (100 by default).

offsetinteger · optional

How many to skip, to read the next page.

The content of this response is not yet described field by field in the OpenAPI description.

agentsarray of object · required

1 to 5,000 register entries.

agents[].identifierstring · required

The agent_id of your transactions (the cash_point_id for a cash point).

agents[].kindstring · required

agent, sub_agent, branch or cash_point.Values: agent, sub_agent, branch, cash_point

agents[].closed_atstring (date) · optional

When it stopped; the agent stays in the register.

agents[].countrystring · optional

The country it operates in (two letters).

agents[].opened_atstring (date) · optional

When it began operating.

agents[].parentstring · optional

The master agent, for a sub-agent only.

agents[].regionstring · optional

Your own code for its area.

createdinteger · required

Labels recorded for the first time.

refusedarray of object · required

The entries refused, each with its reason.

refused[].keystring · required

The identifier or reference of the refused entry.

refused[].reasonstring · required

Why it was refused.

updatedinteger · required

Labels that replace an earlier one.

kindstring · optional

Only this kind: agent, sub_agent, branch or cash_point.Values: agent, sub_agent, branch, cash_point

limitinteger · optional

How many at most (100 by default).

offsetinteger · optional

How many to skip, to read the next page.

The content of this response is not yet described field by field in the OpenAPI description.

linesarray of object · required

1 to 1,000 tariff lines.

lines[].amount_minnumber · required

Start of the amount band, included.

lines[].currencystring · required

The currency of the operations it prices.

lines[].fee_fixednumber · required

The fixed part of the fee.

lines[].fee_ratenumber · required

The proportional part, as a fraction of the amount (0.01 is 1 %).

lines[].line_idstring · required

Your reference of the line.

lines[].valid_fromstring (date) · required

First day it applies.

lines[].amount_maxnumber · optional

End of the amount band, excluded; absent for no limit.

lines[].corridorstring · optional

Only for this corridor, when set.

lines[].fee_maxnumber · optional

The highest fee, when there is one.

lines[].fee_minnumber · optional

The lowest fee, when there is one.

lines[].funding_methodstring · optional

Only for this funding method, when set.Values: cash, mobile_money, bank_account, card, crypto, other

lines[].payout_methodstring · optional

Only for this payout method, when set.Values: cash, mobile_money, bank_account, card, crypto, other

lines[].transaction_typestring · optional

Only for this operation type, when set.

lines[].valid_tostring (date) · optional

Day it stops applying, excluded; absent while in force.

createdinteger · required

Labels recorded for the first time.

refusedarray of object · required

The entries refused, each with its reason.

refused[].keystring · required

The identifier or reference of the refused entry.

refused[].reasonstring · required

Why it was refused.

updatedinteger · required

Labels that replace an earlier one.

active_onstring (date) · optional

Only the lines in force that day.

limitinteger · optional

How many at most (100 by default).

offsetinteger · optional

How many to skip, to read the next page.

The content of this response is not yet described field by field in the OpenAPI description.

customer_idstring · required

The customer’s identifier in your system. Only its pseudonym is kept; always send the same one for the same customer.

namestring · required

The full name. Compared in memory, never stored.

birth_yearinteger · optional

The year of birth, between 1900 and 2100. Optional, it sharply reduces false matches between namesakes.

idinteger · required

Identifier of the result.

listobject · required

The version of the United Nations list, kept for integrations written before national lists.

list.entriesinteger · required

Number of entries.

list.fetched_atstring (date-time) · required

Date YARDA obtained it.

list.generated_atstring (date-time) · required

Publication date of this version.

list.sha256string · required

SHA-256 fingerprint of the version.

list.sourcestring · required

The list.

listsarray of object · required

Every list in force the name was compared with.

lists[].entriesinteger · required

Number of entries.

lists[].fetched_atstring (date-time) · required

Date YARDA obtained it.

lists[].generated_atstring (date-time) · required

Publication date of this version.

lists[].sha256string · required

SHA-256 fingerprint of the version.

lists[].sourcestring · required

The list.

matchesarray of object · required

The list entries close to the name sent.

matches[].birth_yearsarray of integer · required

The published years of birth.

matches[].kindstring · required

Individual or entity.

matches[].listed_onstring · required

The listing date.

matches[].matched_namestring · required

The entry’s name or alias closest to the name sent.

matches[].namestring · required

The entry’s name.

matches[].programmestring · required

The entry’s sanctions programme.

matches[].referencestring · required

The entry’s reference in its list.

matches[].scorenumber · required

How alike the names are, from 0 to 1.

matches[].provenanceobject · optional

The version of the list the entry was found in: publisher, address of the publication, retrieval date and SHA-256 fingerprint.

matches[].sourcestring · optional

The source list.Default: un_sc_consolidated

screened_atstring (date-time) · required

Date and time of screening.

statusstring · required

clear (no match), potential (to examine), confirmed or dismissed (a person’s decision).

subjectstring · required

The customer’s pseudonym.

decided_atstring (date-time) · optional

Date of that decision.

decided_bystring · optional

The person who confirmed or dismissed the match.

notestring · optional

The reason for that decision.

customersarray of object · required

The customers to screen, from 1 to 1,000.

customers[].customer_idstring · required

The customer’s identifier in your system. Only its pseudonym is kept; always send the same one for the same customer.

customers[].namestring · required

The full name. Compared in memory, never stored.

customers[].birth_yearinteger · optional

The year of birth, between 1900 and 2100. Optional, it sharply reduces false matches between namesakes.

clearinteger · required

Number of customers with no match.

listobject · required

The version of the United Nations list, kept for integrations written before national lists.

list.entriesinteger · required

Number of entries.

list.fetched_atstring (date-time) · required

Date YARDA obtained it.

list.generated_atstring (date-time) · required

Publication date of this version.

list.sha256string · required

SHA-256 fingerprint of the version.

list.sourcestring · required

The list.

listsarray of object · required

Every list in force the name was compared with.

lists[].entriesinteger · required

Number of entries.

lists[].fetched_atstring (date-time) · required

Date YARDA obtained it.

lists[].generated_atstring (date-time) · required

Publication date of this version.

lists[].sha256string · required

SHA-256 fingerprint of the version.

lists[].sourcestring · required

The list.

screenedinteger · required

Number of customers screened.

to_reviewarray of object · required

The customers with a match to examine or confirmed, as screening results.

to_review[].idinteger · required

Identifier of the result.

to_review[].matchesarray of object · required

The list entries close to the name sent.

to_review[].screened_atstring (date-time) · required

Date and time of screening.

to_review[].statusstring · required

clear (no match), potential (to examine), confirmed or dismissed (a person’s decision).

to_review[].subjectstring · required

The customer’s pseudonym.

to_review[].decided_atstring (date-time) · optional

Date of that decision.

to_review[].decided_bystring · optional

The person who confirmed or dismissed the match.

to_review[].notestring · optional

The reason for that decision.

checked_atstring (date-time) · required

Last time the United Nations list’s publisher was asked.

confirmedinteger · required

Confirmed matches.

customersinteger · required

Number of customers screened.

listobject · required

The version of the United Nations list, kept for integrations written before national lists.

list.entriesinteger · required

Number of entries.

list.fetched_atstring (date-time) · required

Date YARDA obtained it.

list.generated_atstring (date-time) · required

Publication date of this version.

list.sha256string · required

SHA-256 fingerprint of the version.

list.sourcestring · required

The list.

listsarray of object · required

Every list in force the name was compared with.

lists[].entriesinteger · required

Number of entries.

lists[].fetched_atstring (date-time) · required

Date YARDA obtained it.

lists[].generated_atstring (date-time) · required

Publication date of this version.

lists[].sha256string · required

SHA-256 fingerprint of the version.

lists[].sourcestring · required

The list.

on_current_listinteger · required

Customers screened against the versions in force.

overdueboolean · required

True if that deadline has passed.

pending_listsinteger · required

National list versions read and awaiting a check.

potentialinteger · required

Matches to examine.

rescreen_due_atstring (date-time) · required

Deadline for screening again, when a list has changed since the last one.

statusstring · optional

open: a person must rule, or information is missing; confirmed: a party is a confirmed match, freezing and reporting are yours to do; released: nothing holds the transfer any more; superseded: the transaction was scored again.Values: open, confirmed, released, superseded

afterinteger · optional

The cursor: the next value of the previous page.

limitinteger · optional

Holds per page, from 1 to 500 (100 by default).

itemsarray of object · required

The holds of the page.

items[].holdboolean · required

True while the transfer must stay on hold: execute it only once it is false.

items[].placed_atstring (date-time) · required

When the scoring placed the hold (UTC).

items[].reasonsarray of string · required

The reasons still standing, as in the scoring’s legal.reasons.

items[].request_idstring · required

The scoring that placed the hold.

items[].resolved_atstring (date-time) · required

When the hold ended, released or superseded; null while it lasts.

items[].resolved_bystring · required

Who ruled, when a ruling in screening released the hold.

items[].statusstring · required

open: a person must rule, or information is missing; confirmed: a party is a confirmed match, freezing and reporting are yours to do; released: nothing holds the transfer any more; superseded: the transaction was scored again.Values: open, confirmed, released, superseded

items[].superseded_bystring · required

The request id of the scoring that superseded this one.

items[].transaction_idstring · required

Your reference for the transaction.

items[].updated_atstring (date-time) · required

Last change of the hold (UTC).

nextinteger · optional

Pass as after for the next page; null on the last.

transaction_idstring · required

Your reference for the transaction.

holdboolean · required

True while the transfer must stay on hold: execute it only once it is false.

placed_atstring (date-time) · required

When the scoring placed the hold (UTC).

reasonsarray of string · required

The reasons still standing, as in the scoring’s legal.reasons.

request_idstring · required

The scoring that placed the hold.

resolved_atstring (date-time) · required

When the hold ended, released or superseded; null while it lasts.

resolved_bystring · required

Who ruled, when a ruling in screening released the hold.

statusstring · required

open: a person must rule, or information is missing; confirmed: a party is a confirmed match, freezing and reporting are yours to do; released: nothing holds the transfer any more; superseded: the transaction was scored again.Values: open, confirmed, released, superseded

superseded_bystring · required

The request id of the scoring that superseded this one.

transaction_idstring · required

Your reference for the transaction.

updated_atstring (date-time) · required

Last change of the hold (UTC).

statusstring · required

The service’s state.

timestampstring (date-time) · required

The server’s time.

servicestring · optional

The service’s name.Default: mto-fraud-detector

versionstring · optional

The service’s version.Default: 0.1.0