> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hawk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get customer case

> Retrieves Hawk-generated customer case statistics by internal case ID. Returns customer risk rating, flagging results, and screening data. 

## OpenAPI

````json GET /v2/customer-checks/{caseId}
{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [
    {
      "url": "https://api.test.aml-ai.net",
      "description": "Default Server URL"
    },
    {
      "url": "https://api.test.aml-ai.net",
      "description": "Default Server URL"
    },
    {
      "url": "https://api.test.aml-ai.net",
      "description": "Generated server url"
    }
  ],
  "security": [
    {
      "API_KEY": []
    }
  ],
  "tags": [
    {
      "name": "customer-case",
      "description": "the customer-case API"
    },
    {
      "name": "transaction-case",
      "description": "the transaction-case API"
    }
  ],
  "paths": {
    "/v2/customer-checks/{caseId}": {
      "get": {
        "tags": [
          "customer-case"
        ],
        "summary": "Get customer case",
        "description": "Retrieves Hawk-generated customer case statistics by internal case ID. Returns customer risk rating, flagging results, and screening data. ",
        "operationId": "getCustomerCase",
        "parameters": [
          {
            "name": "caseId",
            "in": "path",
            "description": "Internal Hawk case ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Case found; all data sources returned successfully. The response contains the complete case payload. ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerCaseResponse"
                }
              }
            }
          },
          "206": {
            "description": "Case found, but one or more data sources (for example screening) were temporarily unavailable, so some fields may be missing. **Why:** a downstream data source did not respond in time. **Recover:** retry with exponential backoff until you receive `200`. ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerCaseResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. **Why:** the `api-key` header was absent or not valid for this tenant. **Recover:** send a valid tenant API key in the `api-key` header. ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "errors": [
                    "Missing or invalid API key"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No customer case exists for the given `caseId`. **Why:** the ID is unknown or belongs to a transaction case. **Recover:** verify the `caseId` from the original submission response and that you are calling the customer endpoint. ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "errors": [
                    "Customer case not found"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. **Why:** requests exceeded the per-second limit agreed for your tenant (shared with `POST`/`PATCH` `/v2/customer-checks`). **Recover:** pause and retry with exponential backoff — for example 1s, 2s, 4s with jitter — and keep overall throughput under the limit. ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "errors": [
                    "Rate limit exceeded"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "The case was found but could not be assembled for the response. **Why:** a transient internal error. **Recover:** retry with backoff; if it persists, contact Hawk. ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "errors": [
                    "Failed to detokenize customer case"
                  ]
                }
              }
            }
          }
        },
        "security": [
          {
            "API_KEY": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "CustomerCaseResponse": {
        "type": "object",
        "properties": {
          "caseId": {
            "type": "string",
            "format": "uuid",
            "description": "Internal Hawk case ID",
            "example": "5f8a3b2c-1d4e-4f5a-9b6c-7d8e9f0a1b2c"
          },
          "correlationId": {
            "type": "string",
            "format": "uuid",
            "description": "Correlation ID linking this case to the original request"
          },
          "tenantId": {
            "type": "string",
            "format": "uuid",
            "description": "Tenant identifier"
          },
          "customerId": {
            "type": "string",
            "description": "Customer identifier associated with this case"
          },
          "accountId": {
            "type": "string",
            "description": "Account identifier associated with this case"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when processing of the case completed (ISO 8601 UTC)"
          },
          "caseStatus": {
            "type": "string",
            "description": "Current lifecycle status of the case. One of: OPEN, NOT_OPENED, AUTO_CLOSED",
            "example": "OPEN"
          },
          "processingStatus": {
            "type": "string",
            "description": "Current processing status of the case. One of: new, unsuspicious, relieved, unsubstantiated, opening, machine-review, operator-review, accepted, escalated, sar-filing, sar-filed, reopening, reopened"
          },
          "assignedTo": {
            "type": "string",
            "description": "ID of the user the case is assigned to"
          },
          "apiType": {
            "type": "string",
            "description": "Type of check that created this case (AMLChecks or CustomerChecks)",
            "example": "CustomerChecks"
          },
          "sourceTags": {
            "type": "array",
            "description": "Source tags applied to this case",
            "items": {
              "type": "string"
            }
          },
          "tenantCategory": {
            "type": "string",
            "description": "Category assigned to the tenant"
          },
          "crrStatistics": {
            "$ref": "#/components/schemas/CrrStatistics"
          },
          "notes": {
            "type": "array",
            "description": "Case notes associated with this customer case",
            "items": {
              "$ref": "#/components/schemas/CaseNote"
            }
          }
        },
        "required": [
          "caseId",
          "caseStatus",
          "createdAt"
        ]
      },
      "ErrorResponse": {
        "properties": {
          "errors": {
            "description": "List of error messages",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "CrrStatistics": {
        "type": "object",
        "description": "Customer Risk Rating statistics",
        "properties": {
          "customerEmail": {
            "type": "array",
            "description": "Email addresses of the customer",
            "items": {
              "type": "string"
            }
          },
          "customerName": {
            "type": "string",
            "description": "Name of the customer"
          },
          "customerStatus": {
            "type": "string",
            "description": "Customer status. One of: proceeded, blocked"
          },
          "customerType": {
            "type": "string",
            "description": "Type of customer"
          },
          "riskLevel": {
            "type": "string",
            "description": "Risk level assigned to the customer"
          },
          "totalPoints": {
            "type": "integer",
            "format": "int32",
            "description": "Total risk points scored"
          },
          "riskFactors": {
            "type": "array",
            "description": "Risk factors identified",
            "items": {
              "type": "string"
            },
            "uniqueItems": true
          },
          "flaggingResults": {
            "type": "array",
            "description": "Flagging results from risk assessment",
            "items": {
              "$ref": "#/components/schemas/FlaggingResult"
            },
            "uniqueItems": true
          },
          "screeningHits": {
            "type": "array",
            "description": "Per-hit screening detail, one entry per screening hit on the case.",
            "items": {
              "$ref": "#/components/schemas/ScreeningHit"
            }
          }
        }
      },
      "CaseNote": {
        "type": "object",
        "description": "A single case note",
        "properties": {
          "noteId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the note"
          },
          "userId": {
            "type": "string",
            "description": "ID of the user who created the note"
          },
          "tenantId": {
            "type": "string",
            "format": "uuid",
            "description": "Tenant identifier"
          },
          "caseId": {
            "type": "string",
            "format": "uuid",
            "description": "Associated case identifier"
          },
          "note": {
            "type": "string",
            "description": "Content of the note"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the note was created"
          },
          "type": {
            "type": "string",
            "description": "Type of the note"
          },
          "subtype": {
            "type": "string",
            "description": "Subtype of the note"
          },
          "subtypeRelatedItemId": {
            "type": "string",
            "description": "ID of the item related to the subtype"
          },
          "userDetails": {
            "$ref": "#/components/schemas/CaseNoteUserDetails"
          },
          "attachments": {
            "type": "array",
            "description": "List of attachments associated with this note",
            "items": {
              "$ref": "#/components/schemas/CaseNoteAttachment"
            }
          }
        }
      },
      "FlaggingResult": {
        "properties": {
          "countriesMatched": {
            "type": "array",
            "description": "Countries that matched this flag",
            "items": {
              "type": "string"
            },
            "uniqueItems": true
          },
          "flag": {
            "description": "Flag identifier",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ScreeningHit": {
        "type": "object",
        "description": "A single screening hit with enriched match detail (matched list record, score, list source, and SAN/SCO classification).",
        "properties": {
          "entityId": {
            "type": "string",
            "description": "Reference to the matched list entry / record in the source list.",
            "example": "DJ-1234567"
          },
          "matchedField": {
            "type": "string",
            "description": "JSON path in the submitted transaction/customer payload where the matched value was found — tells you which field the hit is on (for example the counterparty, account-holder, or usage field). Look up the value in the payload you submitted.",
            "example": "masterData.counterpartyData.name"
          },
          "listSource": {
            "type": "string",
            "description": "Data provider the matched list entry originates from.",
            "example": "Dow Jones"
          },
          "matchScore": {
            "type": "number",
            "format": "double",
            "description": "Match score for this hit on a 0-100 scale (higher means a closer match).",
            "example": "100.0"
          },
          "screeningAreas": {
            "type": "array",
            "description": "Screening areas the matched entity is listed under (e.g. SANCTIONS, PEP, ADVERSE_MEDIA, OTHER_WATCHLIST).",
            "example": [
              "SANCTIONS"
            ],
            "items": {
              "type": "string"
            }
          },
          "listNames": {
            "type": "array",
            "description": "Names of the source lists the matched entity appears on.",
            "example": [
              "OFAC SDN"
            ],
            "items": {
              "type": "string"
            }
          },
          "sanctionsOwnership": {
            "type": "boolean",
            "description": "Distinguishes SAN from SCO for sanctions hits: true when the match is a Sanctions Control & Ownership (SCO) record, false for a direct sanctions-list (SAN) record.",
            "example": false
          },
          "matchedName": {
            "type": "string",
            "description": "Name of the matched list entity (the watchlist record's primary name). Personal data.",
            "example": "John Doe"
          },
          "aliases": {
            "type": "array",
            "description": "Alternative names recorded for the matched entity (AKA / also-known-as and native-script names). The name that actually triggered the match may be an alias rather than the primary name. Personal data.",
            "example": [
              "Johnny Doe",
              "J. Doe"
            ],
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "type": "array",
            "description": "Countries associated with the matched entity (nationality, residence, or registration geography), as recorded by the data provider.",
            "example": [
              "GB",
              "US"
            ],
            "items": {
              "type": "string"
            }
          },
          "datesOfBirth": {
            "type": "array",
            "description": "Dates of birth recorded for the matched entity. Sensitive personal data — see Data protection.",
            "example": [
              "1975-04-12"
            ],
            "items": {
              "type": "string"
            }
          },
          "identifiers": {
            "type": "array",
            "description": "Identity documents / identifiers recorded for the matched entity (national ID, passport, company registration number, etc.). Sensitive personal data — see Data protection.",
            "items": {
              "$ref": "#/components/schemas/ScreeningHitIdentifier"
            }
          },
          "profileNotes": {
            "type": "array",
            "description": "Narrative notes recorded on the matched entity by the data provider — the list classification notes plus the provider's free-text profile narrative (for example adverse-media summaries or sanctions-listing details). May be lengthy. Personal data.",
            "example": [
              "Listed for involvement in sanctions evasion."
            ],
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "description": "Source references for the matched entity (data-provider source links).",
            "items": {
              "$ref": "#/components/schemas/ScreeningHitSource"
            }
          }
        }
      },
      "CaseNoteUserDetails": {
        "type": "object",
        "description": "Details of the user who created the case note",
        "properties": {
          "userId": {
            "type": "string",
            "description": "User identifier"
          },
          "email": {
            "type": "string",
            "description": "Email address of the user"
          },
          "name": {
            "type": "string",
            "description": "Full name of the user"
          },
          "picture": {
            "type": "string",
            "description": "URL or reference to the user's profile picture"
          }
        }
      },
      "CaseNoteAttachment": {
        "type": "object",
        "description": "An attachment uploaded with a case note",
        "properties": {
          "uniqueId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the attachment"
          },
          "fileName": {
            "type": "string",
            "description": "Name of the attached file"
          },
          "fileSizeInBytes": {
            "type": "integer",
            "format": "int64",
            "description": "Size of the file in bytes"
          }
        }
      },
      "ScreeningHitIdentifier": {
        "type": "object",
        "description": "An identity document or identifier recorded for a matched screening entity.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Kind of identifier (for example national ID, passport, or company registration number).",
            "example": "PASSPORT"
          },
          "value": {
            "type": "string",
            "description": "The identifier value. Sensitive personal data.",
            "example": "X1234567"
          },
          "note": {
            "type": "string",
            "description": "Additional context on the identifier, such as the specific document type when `type` is generic (for example SIREN, NIT, or passport).",
            "example": "Document Type: SIREN"
          }
        }
      },
      "ScreeningHitSource": {
        "type": "object",
        "description": "A source reference for a matched screening entity.",
        "properties": {
          "type": {
            "type": "string",
            "description": "The kind of source reference.",
            "example": "SOURCE"
          },
          "url": {
            "type": "string",
            "description": "Link to the source record, when the reference is a URL.",
            "example": "https://example.org/list/entry/123"
          },
          "note": {
            "type": "string",
            "description": "Source citation text, when the reference is textual rather than a plain link.",
            "example": "OFAC SDN list, 25-Feb-2022"
          }
        }
      }
    },
    "securitySchemes": {
      "API_KEY": {
        "in": "header",
        "name": "api-key",
        "type": "apiKey"
      }
    }
  }
}
````