POST /v1/risk

Score one booking attempt. Call this from your server right before you commit the reservation.


Method	`POST`
URL	`https://api.staysignals.com/v1/risk`
Auth	`X-StaySignals-Key: sk_<project>_...`
Content-Type	`application/json`

Request body

Send as much of this payload as you can. Only the fields marked required are strictly needed, but the more context StaySignals has, the more signals it can evaluate and the sharper the decision.

`session` (required)

The SDK session observed in the browser.

Field	Type	Required	Description
`session.id`	string	yes	The session UUID generated by `staysignals.js`. Read from `window.staysignals.sessionId` on the client, or from the `staysignals_sid` cookie (e.g. `ses_9f2a1c7b2e8d4a1f`).
`session.ip`	string	—	The end user's IP address at the time of checkout (e.g. `203.0.113.42`).

`booker` (required)

The person placing the booking.

Field	Type	Required	Description
`booker.reference_id`	string	—	Your own internal identifier for this booker, if you have one (e.g. `usr_8a21`).
`booker.first_name`	string	yes	Given name (e.g. `Grace`).
`booker.last_name`	string	yes	Family name (e.g. `Hopper`).
`booker.email`	string	yes	Email address (e.g. `grace@example.com`).
`booker.phone`	string	yes	Phone number in E.164 format (e.g. `+15125550125`).

`guests`

The guests staying at the hotel. Always an array, even for a single guest.

Field	Type	Required	Description
`guests[].first_name`	string	—	Given name (e.g. `Alan`).
`guests[].last_name`	string	—	Family name (e.g. `Kay`).

`billing`

The billing address used at checkout.

Field	Type	Required	Description
`billing.address_line`	string	—	Street address (e.g. `221 Congress Ave`).
`billing.country`	string	—	ISO 3166-1 alpha-2 country code (e.g. `US`).

`hotel` (required)

The property being booked.

Field	Type	Required	Description
`hotel.reference_id`	string	—	Your own internal identifier for the property (e.g. `hot_4fd1`).
`hotel.giata_id`	string	—	The GIATA property ID. Strongly recommended — it lets StaySignals judge several signals more accurately (e.g. `123456`).
`hotel.name`	string	yes	Property name (e.g. `The Gravel House`).
`hotel.address`	string	yes	Street address of the property (e.g. `501 E 6th St, Austin, TX`).
`hotel.country`	string	yes	ISO 3166-1 alpha-2 country code (e.g. `US`).

`booking` (required)

The reservation details.

Field	Type	Required	Description
`booking.check_in`	string	yes	Check-in date, `YYYY-MM-DD` (e.g. `2026-06-15`).
`booking.check_out`	string	yes	Check-out date, `YYYY-MM-DD` (e.g. `2026-06-17`).

Response

Field	Type	Description
`decision_id`	string	Unique identifier for this decision, prefixed with `dec_`. Store it on the order record to look up the decision later in the Dashboard.
`risk_score`	integer	Integer from 0 to 99. Higher means more suspicious.
`risk_level`	string	One of `low`, `medium`, `high`. Derived from `risk_score` via a fixed mapping — not affected by your risk setting.
`suggested_action`	string	One of `allow`, `challenge`, `deny`. How to route the checkout. See Handling the response.
`risk_setting`	string	Which risk setting was active at the time of the decision.
`decided_at`	string	ISO 8601 timestamp of when StaySignals scored the booking.

Example

Request

curl https://api.staysignals.com/v1/risk \
  -H "X-StaySignals-Key: sk_<project>_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "id": "ses_9f2a1c7b2e8d4a1f",
      "ip": "203.0.113.42"
    },
    "booker": {
      "reference_id": "usr_8a21",
      "first_name": "Grace",
      "last_name": "Hopper",
      "email": "grace@example.com",
      "phone": "+15125550125"
    },
    "guests": [
      { "first_name": "Alan", "last_name": "Kay" }
    ],
    "billing": {
      "address_line": "221 Congress Ave",
      "country": "US"
    },
    "hotel": {
      "reference_id": "hot_4fd1",
      "giata_id": "123456",
      "name": "The Gravel House",
      "address": "501 E 6th St, Austin, TX",
      "country": "US"
    },
    "booking": {
      "check_in": "2026-06-15",
      "check_out": "2026-06-17"
    }
  }'

Response

{
  "decision_id": "dec_8f2a1c7b2e8d",
  "risk_score": 18,
  "risk_level": "low",
  "suggested_action": "allow",
  "risk_setting": "balance",
  "decided_at": "2026-04-18T08:27:33Z"
}

On this page