Inquiry Signals

Platform signals computed for an inquiry (such as fraud scores and behavioral indicators) can be exposed on the external Inquiry API and webhooks. This allows you to consume risk and trust signals directly from inquiry responses without needing to make separate API calls.

How it works

When the feature is enabled, the GET /api/v1/inquiries/:id response includes a signals object in data.attributes. Each key is a signal name and each value is an object holding that signal’s value:

{
  "data": {
    "id": "inq_abc123",
    "type": "inquiry",
    "attributes": {
      "status": "approved",
      "signals": {
        "inquiry/bot-score": {
          "value": 42
        },
        "inquiry/behavior-threat-level": {
          "value": "low"
        }
      }
    }
  }
}

signals is only included once the Inquiry is finalized, which happens after post-processing completes. Earlier responses and webhook payloads for the same Inquiry don’t include it.

When the feature is not enabled, signals is omitted from data.attributes entirely:

{
  "data": {
    "id": "inq_abc123",
    "type": "inquiry",
    "attributes": {
      "status": "approved"
    }
  }
}

Signal object properties

Each key in the signals object is a signal name, such as inquiry/bot-score or inquiry/behavior-threat-level. Signal names follow your key inflection, so the same signal appears as inquiry/bot_score with snake_case. Each value is an object with the following property:

Unit conventions

Programmatic interfaces (the Inquiry API, webhooks, and event payloads) standardize numerical measurements on base SI units without attached unit strings so machine systems and rules engines can compare and evaluate values directly:

• Distance and geospatial measurements: All distance signals (such as geolocation-to-residency-delta or distance between IP and device coordinates) are emitted as raw floating-point numbers in meters ($m$).
• Dashboard display vs. raw payload: In the Persona Dashboard (e.g., on the Inquiry details page), distances exceeding 1,000 meters are automatically formatted in kilometers (e.g., 8,357.8 km) for human readability. In API responses and webhook/event payloads, however, the underlying raw value is always delivered in meters (e.g., 8357841.68).
• Rule and trigger evaluations: When configuring automated workflow triggers, webhook handlers, or downstream business logic based on distance signals, always evaluate thresholds in meters (for example, evaluate 50000 rather than 50 for a 50 km threshold).

Which signals appear

Only signals that pass visibility checks for your organization are included in the response. Specifically:

• The signal must be assigned to the inquiry’s template version.
• The signal’s visibility rules must be satisfied (based on product features and environment restrictions).

The set of visible signals may vary across inquiry templates and template versions. If no signals are visible for a given inquiry, signals is an empty object ({}).

Webhook exposure

Since signals is an inline attribute on the inquiry object, it automatically appears in all inquiry webhook event payloads (e.g. inquiry.completed, inquiry.approved, inquiry.declined). No additional webhook configuration is required. When the feature is not enabled, or before the Inquiry is finalized, signals is omitted from the webhook payload.

For example, an inquiry.approved webhook event payload will include signals in the inquiry attributes:

{
  "data": {
    "type": "event",
    "id": "evt_XGuYWp7WuDzNxie5z16s7sGJ",
    "attributes": {
      "name": "inquiry.approved",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_abc123",
          "attributes": {
            "status": "approved",
            "signals": {
              "inquiry/bot-score": {
                "value": 42
              },
              "inquiry/behavior-threat-level": {
                "value": "low"
              }
            }
          },
          "relationships": {
            "template": {
              "data": {
                "id": "tmpl_XYZ789",
                "type": "template"
              }
            }
          }
        }
      },
      "created-at": "2026-02-16T19:01:00.000Z"
    }
  }
}

See the Webhooks Overview for more information on configuring and consuming webhooks.