Search Fraud risk assessment

POST

/v1/object-types/hospitality.fraud_risk_assessment/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.fraud_risk_assessment/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","cursor":"example","filters":[{"property":"id","type":"eq","value":"example"}],"limit":1,"order":"asc","property_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","scope":{"level":"tenant"},"sort_by":"created_at"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.fraud_risk_assessment/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "id", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

Search for instances. Filters eq, contains, gte and lte AND-compose; or / not are additive follow-ups. Pages with an opaque cursor; the +1 fetch returns has_more without a second round-trip. Ordered by sort_by (default created_at) in order (default ascending), id breaking ties; rows with no value for a property key sort last.

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

Request Body^required

application/json

object

branch

Optional open-branch id. Search composes that branch’s copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.

string format: uuid

cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string

filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array

One of:

object

property

required

Allowed value: id

type

required

Allowed value: eq

value

required

string

limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer

>= 1 <= 500

order

Direction of sort_by: asc (oldest / smallest first) or desc. A cursor is bound to the sort_by and order it was minted under; another pair is refused (422).

string

default: asc

Allowed values: asc desc

property_id

The house a desk stands in: keeps this property’s rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house’s — the meaning property_id has on the event tail.

string format: uuid

scope

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

sort_by

What the page is ordered by: the row’s created_at or updated_at, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).

string

default: created_at

Allowed values: created_at updated_at id subject_kind subject_id fire_point vendor_id vendor_model_version score score_calibrated band recommended_action confidence confidence_score rationale_text issued_at expires_at decision_status decided_at decided_by applied_action_kind applied_action_correlation_id escalation_reason rejection_reason coverage_terms_uri feature_payload_hash

Responses

200

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

application/json

object

data

required

Array<object>

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

has_more

required

boolean

next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string

Example

{
  "data": [
    {
      "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"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Fraud risk assessment

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required