Session Intelligence

The endpoint supports sessions profiled by the Signifyd web script and Signifyd Mobile SDKs. The fields returned depend on the profiling client and the signals available on the device.

Before you begin

Profile the customer session before requesting Session Intelligence, and pass the same session ID to your backend. You also need a Signifyd API key authorized for Session Intelligence. Keep this key on your backend and do not include it in browser or mobile application code.

For complete request and response schemas, field definitions and response codes, see the Session Intelligence API Reference.

Integration flow

flowchart LR
  C[Customer browser or app] -->|Profile with session ID| S[Signifyd]
  C -->|Send the same session ID| B[Your backend]
  B -->|Request Session Intelligence| S
  S -->|Return session intelligence| B
  B -->|Apply your risk workflow| R[Your application]

  classDef client fill:#FFFFFF,stroke:#00A3E0,stroke-width:2px,color:#003459
  classDef backend fill:#E8EEF6,stroke:#0070BD,stroke-width:2px,color:#003459
  classDef signifyd fill:#003459,stroke:#0070BD,stroke-width:2px,color:#FFFFFF
  classDef application fill:#FFFFFF,stroke:#EAAA00,stroke-width:2px,color:#003459
  class C client
  class B backend
  class S signifyd
  class R application
  linkStyle 0 stroke:#00A3E0,stroke-width:2px
  linkStyle 1 stroke:#0070BD,stroke-width:2px
  linkStyle 2 stroke:#0070BD,stroke-width:2px
  linkStyle 3 stroke:#00A3E0,stroke-width:2px
  linkStyle 4 stroke:#EAAA00,stroke-width:2px

The session ID connects the profile to the lookup:

1. Generate an opaque session ID for the customer journey.
2. Pass it to the Signifyd web script or Mobile SDK when profiling starts.
3. Send the same value to your backend with the related activity.
4. Request Session Intelligence from your backend after the profiling request has completed.
5. Check sessionResponse.profileStatus before using the device object.

Pass the session ID unchanged between these steps. Do not use customer information such as an email address, phone number or account number as the value.

Make the request

Send a POST request to:

https://api.signifyd.com/v3/sessionIntelligence/{sessionId}

Replace {sessionId} with the URL-encoded session ID used during profiling. Authenticate with HTTP Basic authentication, using your authorized Signifyd API key as the username and an empty password.

The request body is optional. When available, include the IP address and user agent observed by your backend:

curl --request POST \
  --url "https://api.signifyd.com/v3/sessionIntelligence/$SESSION_ID" \
  --user "$SIGNIFYD_API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "device": {
      "clientIpAddress": "203.0.113.7",
      "originatingUserAgent": "CUSTOMER_USER_AGENT"
    }
  }'

These values provide additional server-observed context but do not replace device profiling. You can omit the body when they are unavailable. If your backend is behind a proxy or load balancer, use the original customer IP from your trusted forwarding chain.

Handle profile status

Always check sessionResponse.profileStatus before using the response.

PROFILED

PROFILED means Signifyd found a device profile for the session. The device object contains the intelligence available for that profiling client and device.

Treat optional fields as nullable. A missing value means that the signal was unavailable or did not apply to the client. It does not necessarily represent a negative assessment.

NOT_PROFILED

A valid session that is unknown, has not been profiled yet or is no longer available returns HTTP 200 with profileStatus: NOT_PROFILED and device: null:

{
  "sessionResponse": {
    "profileStatus": "NOT_PROFILED"
  },
  "device": null
}

This is a successful API response, not an error. Do not attempt to read fields from device.

If profiling completed recently, retry after a short delay. Otherwise, confirm that the lookup used the same session ID as profiling and that the session is still recent. Session data remains available for approximately 24 hours.

Client-specific signals

Web and native applications expose different capabilities. Browser, navigation and bot-detection signals are primarily produced by web profiling. Device integrity, application and mobile network signals are produced by Mobile SDKs. Wi-Fi and geolocation may be absent when the operating system withholds them or the customer has not granted the relevant permission.

Do not assume that every profile has the same fields. Use the API Reference to determine which fields apply to each profiling client.

Navigation history

For web sessions, device.navigationHistory.pageViews contains profiled page views in newest-first order.

visitedAt is the time Signifyd received the profiling request for the page. It is later than the customer's exact arrival time by however long the page took to load and profile.

timeOnPageSeconds is calculated from the interval between adjacent profiling requests. It is an approximation, not a duration measured by the browser. The newest page has a null value because no later profiled page exists yet. If an intermediate page is not profiled, its time may be attributed to the preceding profiled page. Native application sessions do not provide web page-duration values.

Time-on-page data is most useful when every relevant page is profiled. For single-page applications, follow the SPA Device Profiling guide so route changes generate page views.