---
title: "Correlate breach, session, SIM swap and domain signals for one identity"
method: POST
path: "/v1/metered/incident-timeline"
tags: ["Identity exposure"]
---

# Correlate breach, session, SIM swap and domain signals for one identity

`POST /v1/metered/incident-timeline`

## Request

- Base URL: `https://api.relayshield.net`
- URL: `https://api.relayshield.net/v1/metered/incident-timeline`
- Auth: one of:
  - API key in header `X-RS-API-KEY`
  - HTTP bearer

Runs the breach and stolen-session checks for the supplied email (always), plus SIM swap when a phone is supplied and a domain lookalike sweep when a domain is supplied, then matches the resulting signal set against the same coordinated-attack-chain table the WhatsApp monitor uses in the background -- on demand, for any identity, in one call. A chain match (for example breach + SIM swap within the same identity) is a materially higher-confidence finding than either signal alone: attackers commonly combine credential theft with a SIM swap to intercept SMS 2FA.

**Billing.** $0.50 per successful call. Failed calls are never billed. Charged against prepaid credits when the balance covers it, otherwise metered to your card. Threat Intelligence subscribers and AWS Marketplace bundle customers call this at no extra charge.

**Note.** Each sub-check keeps its own failure behaviour -- a SIM swap check the carrier could not answer, or a session-risk query that failed, is reported as checked: false rather than folded into 'not present'. Only smishing_to_sim_swap and breach_otp_intercept can never fire here: both require an SMS or OTP event observed inside a monitored conversation, which this endpoint has no way to check for an arbitrary identity.

## Request body

- object
  - `email` string, email, required: Email address to check. Always run.
  - `phone` string: E.164 phone number. Optional -- adds the SIM swap check.
  - `domain` string: Domain to sweep for lookalikes. Optional -- adds the domain-lookalike check.

## Response `200`

Success. `ok` is true and `data` holds the result.

- object
  - `ok` true, required
  - `data` object, required
    - `identity` object: Which inputs were supplied.
      - `email` string: The normalised address that was checked.
      - `phone_checked` boolean: True when a phone was supplied and the SIM swap check ran.
      - `domain_checked` boolean: True when a domain was supplied and the lookalike sweep ran.
    - `signals_detected` string[]: ATTACK_CHAINS signal types found present, e.g. `breach_alert`.
    - `chain_matched` object: The matched attack chain, or null when no known chain's full signal set is present.
      - `chain` string: Machine-readable chain id, e.g. `breach_sim_swap`.
      - `severity` 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW': CRITICAL or HIGH.
      - `label` string: Human-readable chain name.
      - `what` string: Plain-language explanation of the pattern and why it matters.
    - `checks` object: Per-check detail, keyed by check name. sim_swap and domain are present only when run.
    - `checks_skipped` string[]: Checks not run and why, e.g. `sim_swap (no phone supplied)`.
    - `checked_at` string, date-time: ISO 8601 UTC timestamp of when this check ran.

## Other responses

- `400`: `email` is missing or contains no '@'.
- `401`: Missing or invalid API key.
- `402`: No credits and no active subscription. The response carries `topup_url`.
- `405`: Wrong HTTP method. Every endpoint is POST.

---

[API](https://skmtc.dev/relayshield/apis/relayshield-api.md) · [All operations](https://skmtc.dev/relayshield/apis/relayshield-api/llms.txt) · [OpenAPI document](https://skmtc.dev/relayshield/apis/relayshield-api/revisions/4d4721b936dd?raw)