Read Fraud risk assessment

GET

/v1/object-types/hospitality.fraud_risk_assessment/objects/{id}

const url = 'https://api.aerandil.com/v1/object-types/hospitality.fraud_risk_assessment/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
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.aerandil.com/v1/object-types/hospitality.fraud_risk_assessment/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Read an existing instance.

A typed fraud-risk assessment issued by an agent (or, less commonly, a human risk analyst logging a manual assessment into the audit trail) against a reservation, payment, charge, person, or loyalty redemption. Mostly-immutable post-issue: the score / band / recommended_action / confidence / factors / reason_codes / rationale / risk_context_snapshot are frozen at write time so the audit trail is what the model saw at decision time, not against today’s profile. The decision_, applied_, escalation_, and rejection_ fields mutate exactly once on the transition out of suggested — gated by the decision_status_transitions cross-link validator. Doubly load-bearing for chargeback-dispute defence: card networks accept frozen-feature evidence in dispute response.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.fraud_risk_assessment:read

Parameters

Path Parameters

required

string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

branch

string format: uuid

Read through an open branch’s copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with as_of (422). The branch must exist under the caller’s tenant.

Responses

200

Object found.

application/json

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.fraud_risk_assessment

properties

required

object

applied_action_correlation_id

correlation_id of the chained action's ApplyActionResponse (set when apply chained into a typed action)

string

applied_action_kind

Action class actually taken on `applied` transition

string

Allowed values: approve_proceed decline_block step_up_3ds_initiated step_up_kyc_initiated decline_with_refund decline_with_hold approve_with_manual_review

band

Risk band ordinal

string

Allowed values: low medium high block not_assessed

confidence

required

Operator-facing confidence ordinal

string

Allowed values: low medium high

confidence_score

Calibrated probability [0, 1] — set when the model emits one

string format: decimal

coverage_guaranteed

True when the vendor's chargeback-guarantee terms cover this decision (per-decision, not per-vendor)

boolean

coverage_terms_uri

Optional pointer to the vendor's coverage terms applicable to this decision

string

decided_at

When the assessment transitioned out of suggested

string format: date-time

decided_by

`principal.stable_id()` of the deciding principal

string

decision_status

required

Lifecycle state

string

Allowed values: suggested applied rejected escalated expired superseded

escalation_reason

Reason recorded on escalation

string

Allowed values: low_confidence policy_block high_value chargeback_history_match watchlist_hit kyc_failure three_ds_failure manual_review_required vendor_uncertainty regulatory_review operator_override

escalation_target_staff_ref

Optional explicit staff assignment on escalation

string format: uuid

expires_at

required

After this, decision_status moves to expired

string format: date-time

factors_considered

required

Signal categories the assessment conditioned on

Array<string>

Allowed values: payment_signal identity_signal behavioural_signal device_signal velocity_signal geo_signal lead_time loyalty_account_age prior_chargeback_history prior_recovery_history third_party_payer_flag vcn_detected injection_history network_outcome kyc_outcome three_ds_outcome watchlist_match graph_signal fraud_network_signal other

feature_payload_hash

SHA-256 of the canonical JSON of the input features (tamper- evidence anchor for chargeback-dispute defence)

string

fire_point

required

Lifecycle moment the assessment fired at

string

Allowed values: at_booking at_payment at_check_in at_folio_close on_chargeback_attempt

folio_charge_ref

Optional charge anchor (set for charge-scoped assessments at `at_payment` / `at_folio_close` fire-points)

string format: uuid

required

Assessment id

string

issued_at

required

When the agent emitted the assessment

string format: date-time

person_ref

Optional denormalised person anchor (set when the booking has an identified guest or when the assessment is person-scoped)

string format: uuid

policy_outcomes

required

Compliance flags observed during scoring

Array<string>

Allowed values: psd2_sca_required psd2_sca_out_of_scope_moto psd2_sca_exempted_low_value psd2_sca_exempted_trusted_beneficiaries psd2_sca_exempted_tra psd2_sca_exempted_recurring psd2_sca_exempted_corporate_payment three_ds_y three_ds_a three_ds_u three_ds_n three_ds_r three_ds_not_attempted gdpr_art22_explanation_required pci_token_only pci_last4_only facta_red_flag_match fincen_8300_threshold_met eu_ai_act_high_risk_processing ccpa_admt_notice_required none

rationale_text

Human-readable explanation surfaced to operators

string

reason_codes

Explanation array — each entry carries a code, severity, and signed contribution to the final score (JSON; host populates per documented shape)

recommended_action

Recommended action class

string

Allowed values: approve review step_up_3ds step_up_kyc decline escalate

rejection_reason

Free-text reason on reject (gold-standard decision-log pattern)

string

reservation_ref

Optional denormalised reservation anchor (set for reservation-scoped assessments)

string format: uuid

risk_context_snapshot

Frozen context snapshot at issue time (§3.1.1; JSON; host populates per recommended shape)

score

Raw numeric score on the [0, 100] scale

string format: decimal

score_calibrated

Optional calibrated probability [0, 1] when the model emits one

string format: decimal

subject_id

required

Id of the typed object the assessment scored (resolved against `subject_kind`)

string

subject_kind

required

What kind of object the assessment scored

string

Allowed values: reservation payment charge person loyalty_redemption folio

superseded_by_assessment_ref

Newer assessment that replaces this one (set on supersedence)

string format: uuid

triggered_rules

Custom-rule provenance when the score path went through rules (JSON array of {rule_id, rule_version?, action?})

vendor_id

required

Vendor identity (denormalised from Principal::Agent.vendor)

string

vendor_model_version

Vendor model version when exposed (e.g. stripe_radar_v3)

string

provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object

pins

object

key

additional properties

object

pinned_at

string format: date-time

pinned_by

object

reason

required

string

properties

object

key

additional properties

object

external_id

string

recorded_at

required

string format: date-time

source

required

string

source_updated_at

string format: date-time

stream

string

scope

required

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

tenant_id

required

string format: uuid

updated_at

required

string format: date-time

version

required

integer

>= 1

Example

{
  "object_type": "hospitality.fraud_risk_assessment",
  "properties": {
    "applied_action_kind": "approve_proceed",
    "band": "low",
    "confidence": "low",
    "decision_status": "suggested",
    "escalation_reason": "low_confidence",
    "factors_considered": [
      "payment_signal"
    ],
    "fire_point": "at_booking",
    "policy_outcomes": [
      "psd2_sca_required"
    ],
    "recommended_action": "approve",
    "subject_kind": "reservation"
  },
  "scope": {
    "level": "tenant"
  }
}

Headers

ETag

string

/^"\d+"$/

Quoted strong validator (RFC 7232 §2.3) carrying the object’s monotonic version. Informational on the read path — object mutation goes through typed actions on /v1/actions/{action}/apply, not raw CRUD.

404

No object with that id (or soft-deleted).