Objects and Dictionary

Auth objects

Login request

{
  "companyId": "uuid",
  "email": "fraud-admin@example.com",
  "password": "string"
}

Login response

{
  "accessToken": "jwt",
  "refreshToken": "jwt",
  "subscriptionStatus": "active",
  "planCode": "growth",
  "planFeatures": [
    "event_explorer",
    "reviews"
  ]
}

Refresh response

{
  "accessToken": "jwt",
  "refreshToken": "jwt"
}

Assessment request object

Core required fields:

• transactionId: your business identifier for the transaction or decision.
• userId: the stable user identifier in your system.
• amountMinor: amount in minor currency units, such as cents or paise.
• currency: 3-letter uppercase currency code, such as USD or INR.

Optional enrichment fields:

• email, ipAddress, deviceFingerprint, phoneNumber
• paymentMethodHash, shippingAddressHash
• metadata, billingAddress, shippingAddress
• cardDetails, deviceMeta, ipGeo

Field list:

1. transactionId Type is string. Required.
2. userId Type is string. Required.
3. email Type is string. Optional.
4. ipAddress Type is string. Optional.
5. deviceFingerprint Type is string. Optional.
6. phoneNumber Type is string. Optional.
7. paymentMethodHash Type is string. Optional.
8. shippingAddressHash Type is string. Optional.
9. amountMinor Type is integer. Required.
10. currency Type is 3-letter currency code. Required.
11. scoringProfile Type is string. Optional.
12. metadata, billingAddress, shippingAddress, cardDetails, deviceMeta, ipGeo Object fields. Optional.

Assessment response object

1. assessmentId UUID of the stored assessment.
2. riskScore Final numeric score from 0 to 100.
3. action Final action the client should apply.
4. recommendedAction Direct recommendation from the engine.
5. policyMode hybrid, advisory, or shadow.
6. riskLevel Severity band.
7. reasonCodes Explanation code list.
8. featureContributions Diagnostic signal object.
9. engineVersion Engine release label.
10. latencyMs End-to-end evaluation latency.

Event ingest object

Every ingest request should include:

• company identity with companyId
• source tracking with eventSource and externalEventId
• replay-safe identity with idempotencyKey
• the user and event type with userId and eventType
• the event time in timestamp
• event-specific business context inside metadata

Field list:

1. companyId UUID. Required.
2. eventSource String. Required.
3. externalEventId String. Required.
4. idempotencyKey String. Required.
5. userId String. Required.
6. eventType Enum. Required.
7. timestamp ISO 8601 datetime. Required.
8. metadata Object. Required.
9. paymentDetails, billingAddress, shippingAddress, cardDetails, deviceMeta, ipGeo Optional objects.

Payment details object

The paymentDetails object is easiest to think about in groups:

Core payment identity:

• methodType: payment family such as card, UPI, wallet, bank transfer, or COD.
• provider: gateway or PSP name.
• fingerprint: stable payment method fingerprint.
• gatewayPaymentId: payment ID from your PSP or acquirer.
• amountMinor: amount in minor currency units.
• currency: 3-letter uppercase currency code.

Card-specific fields:

• cardLast4
• cardBin
• cardNetwork
• issuer
• country

Alternative payment method fields:

• walletId
• upiVpa

Outcome and processing fields:

• authStatus
• captureStatus
• failureCode
• failureCategory
• attemptCount
• threeDsResult

Contextual sub-objects

billingAddress and shippingAddress

{
  "country": "US",
  "postalCode": "10001",
  "city": "New York"
}

cardDetails

{
  "bin": "411111",
  "last4": "1111",
  "network": "visa",
  "issuingCountry": "US",
  "cardType": "credit"
}

deviceMeta

{
  "os": "iOS",
  "browser": "Mobile Safari",
  "language": "en-US",
  "timezone": "America/New_York"
}

ipGeo

{
  "country": "US",
  "region": "NY",
  "city": "New York",
  "lat": 40.7128,
  "lon": -74.006
}

Subscription object

Key subscription fields:

• status: current billing state such as pending, active, or expired.
• startsAt and endsAt: billing period boundaries.
• cancelAtPeriodEnd: whether the current cycle will end without renewal.
• plan: the nested commercial plan, including features and limits.

1. id UUID.
2. companyId UUID.
3. planId UUID.
4. status String.
5. lemonSqueezySubscriptionId String or null.
6. lemonSqueezyCustomerId String or null.
7. startsAt Datetime.
8. endsAt Datetime or null.
9. cancelAtPeriodEnd Boolean.
10. metadata Object or null.
11. plan Nested plan object.

Usage record object

{
  "id": "uuid",
  "subscriptionId": "uuid",
  "companyId": "uuid",
  "metric": "fraud_events_ingested",
  "year": 2026,
  "month": 4,
  "used": 1240
}

Review object

A review includes:

• review ID
• status
• analyst metadata
• linked assessment summary
• created and updated timestamps

Review statuses:

• open
• in_review
• escalated
• resolved
• closed
• confirmed_fraud
• false_positive

Graph explorer object

{
  "nodes": [
    {
      "id": "riskuser::user_123",
      "label": "RiskUser",
      "group": "riskuser",
      "properties": {}
    }
  ],
  "links": [
    {
      "source": "riskuser::user_123",
      "target": "globalindicator::abcdef",
      "type": "USES_INDICATOR"
    }
  ],
  "meta": {
    "seedUserId": "user_123",
    "nodeCount": 2,
    "linkCount": 1
  }
}