--- title: "Book-level Fraud Signals" method: GET path: "/v2/detect/book/{book_uuid}/signals" tags: ["Detect"] --- # Book-level Fraud Signals `GET /v2/detect/book/{book_uuid}/signals` Scan every <> in an uploaded <> for signs of potentially fraudulent tampering. --- > ๐Ÿ“˜ This is the better version! > This endpoint supersedes our existing [Suspicious Activity Flags endpoint](https://docs.ocrolus.com/ocrolus-api/reference/suspicious-activity), as well as the `primary_recon_error_reason` and `secondary_recon_error_reason` attributes returned by the [Analytics endpoints](https://docs.ocrolus.com/ocrolus-api/reference/analytics). A deprecation plan will be announced in the future. ## Path parameters - `book_uuid` string, uuid, required ## Query parameters - `exclude_dashboard_url` boolean ## Response `200` The <> was scanned for potential fraud, and the results are enclosed. - SignalAnalysis โ€” The result of the fraud analysis that was requested for the provided <>. - `book_uuid` string, uuid โ€” The unique identifier of the Book that was provided to the endpoint's request. - `doc_analysis` DocumentAnalysis[] โ€” Details about potential indicators of fraud found within the analyzed <>. Each object in this array represents one document. - `uploaded_doc_uuid` string, uuid โ€” The unique identifier of the uploaded document. - `uploaded_doc_type` 'BANK_STATEMENT' | 'PAYSTUB' | 'FORM' โ€” The type of the uploaded document. We currently only support signal analysis on the types that are listed here. - `mixed_uploaded_doc_uuid` string, uuid, nullable โ€” The unique identifier of the Mixed Document that this object represents. This field will be `null` if this was not a Mixed Document. - `detect_status` 'PENDING' | 'COMPLETED' | 'UNABLE_TO_PROCESS' | 'UNSUPPORTED' | 'DELETED' โ€” The current state of this document in our processing pipeline. The statuses are as follows: - *`PENDING`:* This document is still being processed, and no results are available yet. Check back later. - *`COMPLETED`:* This document has been completely processed, and complete results are enclosed. - *`UNABLE_TO_PROCESS`:* This document could not be processed, most likely because it's of an unsupported type. - *`UNSUPPORTED`:* This document is of unsupported file type. - *`DELETED`:* This document has been deleted. - `form_analysis` FormAnalysis[] โ€” Analysis results on each form in this document. Each object represents a different form. - `form_type` 'BANK_STATEMENT' | 'PAYSTUB' | 'W2' โ€” The type of the form that was processed. We currently only support signal analysis on document types that are listed here. - `form_uuid` string, uuid โ€” The unique identifier of the form that was processed. - `signals` Signal[] โ€” Details about the suspected fraud signals uncovered in this form's analysis. Each object represents a possible instance of fraud. - `identifier` string โ€” An identifier that describes the type of suspected fraud signal. This value is stable and can be relied upon in your application logic. For a list of all possible values, [visit our guide on Detect Signals](https://docs.ocrolus.com/reference/signal-definition#identifier) - `display_name` string โ€” A human-friendly name for the fraud signal named in `identifier`. This value is unlikely to change, but you shouldn't rely on it for application logic. You should display this value within your own application where applicable. - `signal_count` integer โ€” The number of fraud signals that we've identified. Will be the same as the length of the `supporting_data` array. - `page_number` integer, nullable โ€” The (one-indexed) number of the flagged page. Will be `null` if the fraud signal isn't specific to any particular page, such as for inconsistent data or erroneous arithmetic. This number refers to the index of the page within the document, rather than any number that's captured from the page or its metadata. In other words, this value will be `1` for the first page of a document, even "Page 2" is written in one of its corners. - `signal_type` 'RISK' | 'INFO' | 'TRUST' โ€” Indicates the category of the signal. RISK signals are potential fraud indicators. INFO signals provide contextual information about the document that is not itself a fraud indicator, such as noting that the document is fillable or was produced by a known PDF library. - `description` string โ€” A human-readable explanation of what this signal detected and why it was flagged. Intended to be displayed within your application to give context on the signal without requiring a separate lookup. May be an empty string for some INFO signals where no further explanation is available. - `supporting_data` PageSupportingData[] โ€” The specific captured data that supports a claim of fraudulent activity. - `values` PageSupportingDataValue[] โ€” The data that supports a claim of potentially fraudulent activity. The meaning of each object depends on the fraud signal. - `key` string โ€” An identifier for the type of information described in the `value` field. It will take one of the following values depending on the signal identifier. For more details visit [this](https://docs.ocrolus.com/reference/supportingdatavalues-definition#supporting-data-possible-keys) page. - `value` string โ€” The value that supports a claim of fraudulent activity. The meaning of this field differs depending on the value given in `key`. - `data_type` 'str' | 'int' | 'float' | 'bool' โ€” The logical type of the data that's described in `value`. The `value` attribute will always be represented in JSON as a string, regardless of the value given in this field. - `visualizations` Visualization[] โ€” Contains visualized details about instances of potential fraud, where applicable. Not all fraud signals support visualization, therefore this array may not include every signal in the `signals` list. - `page_number` integer โ€” The 1-indexed page that this visualization describes. This field only considers the sequence of the page within its <>, rather than the numbering within the page itself. For example, a value of `1` indicates the first page even if it calls itself Page 2. - `page_visualizations` VisualizationRegion[] โ€” The list of suspected fraud signals on this page, including visualizations. - `visual_type` 'tamper_overview' | 'edit_regions' | 'original_pdf' | 'tampered_fonts' | 'added_fonts' | 'overwritten_text' โ€” A machine-readable identifier that indicates the type of file tampering visualization offered in this image. This value will not change; you may rely on it in your application logic. - *`tamper_overview`:* Tampered fields are highlighted in red. - *`edit_regions`:* Red highlights indicate the areas of the original document that were changed. - *`original_pdf`:* Red highlights indicate the areas of the original document that were changed. - *`tampered_font`:* The same field appears to use multiple fonts. Where possible, the fonts within a field are highlighted with different colors. - *`added_fonts`:* Text that was added to the document is highlighted in red. - *`overwritten_text`:* Text has been added to (or modified from) the original document. Where possible, unchanged text will be highlighted in green while added text will be highlighted in red. In some cases, only one of these two regions will be shown; this still indicates suspicious activity. - `display_name` string โ€” A human-readable version of the value given in `identifier`. You should display this value within your application. - `description` string โ€” A human-readable description of the visualized fraud signal and guidance on how to interpret it. You should display this value within your application. - `image_url` string, url โ€” A URL to an image that represents this visualization. The image's content is the analyzed page with translucent colored squares overlaid on the regions of suspected fraud. The image requires authentication to access, which means it can't be hot-linked within your own web apps. You can provide your credentials to retrieve it the same way you would with our other endpoints. The image is stored indefinitely, but will be deleted if the associated <> or <> is deleted. - `form_dashboard_url` string โ€” A unique Ocrolus Dashboard URL that links directly to the Dashboard for the given <>. - `form_authenticity` object โ€” Details authenticity score of the document - `version` string โ€” The version number of the authenticity score. Version number will be updated following any major change to the logic determining score. - `score` integer โ€” The authenticity score 0-100 indicates the authenticity of the document. - `reason_codes` object[] - `code` string โ€” A unique string identifier associated with the reason code. - `confidence` string โ€” HIGH/MEDIUM/LOW confidence associated with reason code. - `description` string โ€” A string indicating the cause of the reason code. - `is_image_based_pdf` string โ€” Determines whether the document is an image based PDF (a scan of a PDF or an export of a PDF or similar) or an original PDF produced by a financial institution or payroll provider. - `book_dashboard_url` string โ€” A unique Ocrolus Dashboard URL that links directly to the Dashboard for the given <>. ## Other responses - `400` โ€” The provided value of `book_uuid` wasn't a valid UUID. Ensure that it's correctly-formatted and that it comes from the right source. - `401` โ€” The provided access token can't be used to grant you access to this resource. Make sure the token hasn't expired. - `404` โ€” No <> with the UUID given in `book_uuid` could be found. --- [API](https://skmtc.net/ocrolus/apis/user-management.md) ยท [All operations](https://skmtc.net/ocrolus/apis/user-management/llms.txt) ยท [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ocrolus/user-management/revisions/3571ef602d13/schema)