URurbanfox
Cases

Update a case

Changed on

Update the status of a fraud case.

put/v2/{tenant_slug}/cases/{case_id}

Request

Path parameters

tenant_slugstring required

Tenant DNS slug (lowercase letters, digits, and hyphens; 3-100 characters).

Example:demo-retail
case_idstring required

Unique case identifier returned by GET /cases.

Example:case-abc123

Headers

idempotency-keystring required

Required. Names this update so a retry of it is answered with the recorded outcome instead of being applied again. Generate one value per user action or logical operation, a UUID v7 is recommended, and send the same value on every retry of that action. 1 to 255 characters from A-Z a-z 0-9 . _ : ~ + -. A request without the header is refused with 400.

Request body

status'OPEN' | 'CLOSED' required
case_versioninteger required

The case_version this update was based on, as returned by the last read of the case. The update is applied only while the stored version still matches; if the case has been written since, the request is refused with 409 carrying the current version, and nothing is overwritten. Send 0 for a case that has never carried a version. Required: a request that omits it is refused with 428.

Example request

{
  "case_version": 7,
  "status": "CLOSED"
}

Response

Successful Response

Example response

{
  "data": {
    "case_id": "case-abc123",
    "tenant_id": "00000000-0000-4000-8000-000000000000",
    "website_account_id": "account-abc123",
    "session_id": "a1b2c3d4-20240115-103500000",
    "unique_id": "8f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:20:00Z",
    "case_version": 7,
    "current_state": {
      "state_id": "7a54d2a4-5e2f-4b72-9a4a-3276b4af0c11",
      "score": 4,
      "changed_at": "2024-01-15T10:35:00Z",
      "changed_by": "system",
      "reason": "Case created from model prediction"
    },
    "state_history": [
      {
        "case_status": "OPEN",
        "changed_at": "2024-01-15T10:35:00Z",
        "changed_by": "system",
        "reason": "Case created from model prediction",
        "score": 4,
        "session_status": "ACTIVE",
        "state_id": "7a54d2a4-5e2f-4b72-9a4a-3276b4af0c11"
      }
    ],
    "details": {
      "overall_risk_score": 3,
      "fraud_labels": [
        "Account Takeover",
        "Bot"
      ],
      "summary": "Account takeover attempt detected from suspicious IP",
      "highlights": [
        "Multiple failed login attempts",
        "IP from high-risk country"
      ]
    },
    "fraud_occurrences": {
      "15e341ed-6dae-4783-8647-32a7b7a8269a": {
        "explanation": {
          "fraud_reason": "High velocity account creation",
          "fraud_reason_description": "The account was created very fast and may indicate a bot was used.",
          "fraud_types": [
            "Bot Creation"
          ],
          "model_behaviour": [
            {
              "model_name": "bos_session_aggregate_classifier",
              "top_contributors": [
                {
                  "alignment": "supporting",
                  "description": "Total number of events in the session",
                  "direction": "toward_fraud",
                  "direction_specific": "increases_BotActor_probability",
                  "feature": "total_event_count",
                  "feature_value": 30,
                  "impact_level": "critical",
                  "plain_name": "Total Event Count",
                  "shap_value": 1.151
                }
              ],
              "type": "shap"
            }
          ]
        },
        "generated_at": "2024-01-15T10:35:00Z",
        "occurrence_id": "15e341ed-6dae-4783-8647-32a7b7a8269a",
        "prediction_id": "pred_a1b2c3d4-20240115-103500000_2024-01-15T10:35:00Z",
        "risk_score": 4,
        "session_id": "a1b2c3d4-20240115-103500000"
      }
    }
  }
}

Changes

  • 62f04976cbf5Revision changes
    • breaking

      the header request parameter idempotency-key became required

    • breaking

      header request parameter idempotency-key list-of-types was narrowed by removing types null

    • info

      for the header request parameter idempotency-key, the type was generalized from no type to string

  • 9dd568e86298Revision changes
    • breaking

      the response property became optional for the status

    • breaking

      response property current_version list-of-types was widened by adding types null to media type application/json of response 409

    • info

      added the new optional header request parameter idempotency-key