> ## Documentation Index > Fetch the complete documentation index at: https://docs.trelent.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a detection > Read one detection and its result. Poll this operation until `status` is `COMPLETED` or `FAILED`. The `status` field always shows the durable record. The `verdict` field comes from the workflow history, which expires after the retention period, so an old `COMPLETED` detection can have `verdict: null`. `score` is null when one check determined the document verification result alone. The `authoritative` object then carries the document check finding. A `FAILED` detection gives the reason in `failure_code` and `failure_message`. **Scope:** `DocumentVerification:detections:get` ## OpenAPI ````yaml document-verification/api-reference/openapi.json GET /v1/detection/{detection_id} openapi: 3.1.0 info: title: Trelent Document Verification API description: > Trelent Document Verification integrates with your platform to assess fraud risk in financial and identity documents. The API returns a fraud score and detailed reasoning. Your team builds the integration to display these results in your interface and support human review. Trelent can help you build that integration. Use cases include loan application review and legal document review. Your end-users submit documents through your platform. Document Verification is always deployed in your cloud environment. Your data is never sent to or retained on Trelent servers. ## How a detection runs Detection is asynchronous. `POST /v1/detection` answers `202` immediately with a detection id and the status `QUEUED`. A workflow then prepares the document, runs the deterministic checks, and runs the analysis agent. Read the result with `GET /v1/detection/{detection_id}` until the status is `COMPLETED` or `FAILED`. ## How you supply a document Each create request names its documents in one of two ways, and exactly one of the two must be present: - `source_url` — the API downloads the document from a URL that you supply. Use this method for API integrations. - `upload_id` — the caller has already written the files to object storage. API integrations should use `source_url`. ## Authentication Every `/v1` operation needs an OAuth2 access token from the `client_credentials` grant. Put the token in the `Authorization` header as `Bearer `. In most cases the scope `DocumentVerification:*` covers every operation, so request that if your client holds it. The description of each operation also names the narrower scope it needs. version: 1.0.0 servers: [] security: [] tags: - name: Detections description: >- Verify one document. A detection starts as `QUEUED` and gives no verdict until the status becomes `COMPLETED`. - name: Authentication description: Exchange client credentials for an access token. paths: /v1/detection/{detection_id}: get: tags: - Detections summary: Get a detection description: >- Read one detection and its result. Poll this operation until `status` is `COMPLETED` or `FAILED`. The `status` field always shows the durable record. The `verdict` field comes from the workflow history, which expires after the retention period, so an old `COMPLETED` detection can have `verdict: null`. `score` is null when one check determined the document verification result alone. The `authoritative` object then carries the document check finding. A `FAILED` detection gives the reason in `failure_code` and `failure_message`. **Scope:** `DocumentVerification:detections:get` operationId: get_detection_v1_detection__detection_id__get parameters: - name: detection_id in: path required: true schema: type: string title: Detection Id responses: '200': description: The detection record, with the verdict if it exists. content: application/json: schema: $ref: '#/components/schemas/DetectionDetail' '401': description: The bearer token is absent, expired, or not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The token does not hold the necessary scopes. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No such record. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: DetectionDetail: properties: id: type: string title: Id status: $ref: '#/components/schemas/DetectionStatus' description: '`QUEUED`, `RUNNING`, `COMPLETED`, or `FAILED`.' failure_code: anyOf: - type: string - type: 'null' title: Failure Code description: The reason for a `FAILED` status. Null in all other states. score: anyOf: - type: integer - type: 'null' title: Score description: >- The fraud score, normally 0 to 100. A higher score means a higher likelihood of fraud, but does not guarantee fraud. Humans should always review high-risk cases. Null while the detection runs, and null when one check determined the document verification result alone. billable: type: boolean title: Billable created_at: type: string format: date-time title: Created At completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At submitted_by: anyOf: - type: string - type: 'null' title: Submitted By batch_id: anyOf: - type: string - type: 'null' title: Batch Id description: The batch that holds this detection, if one exists. filename: anyOf: - type: string - type: 'null' title: Filename content_type: anyOf: - type: string - type: 'null' title: Content Type size_bytes: anyOf: - type: integer - type: 'null' title: Size Bytes s3_key: anyOf: - type: string - type: 'null' title: S3 Key description: Where the API keeps the document. discovered: anyOf: - items: type: string type: array - type: 'null' title: Discovered description: Facts that the pipeline found in the document, such as `qr_present`. authoritative: anyOf: - $ref: '#/components/schemas/AuthoritativeResult' - type: 'null' description: >- Set if one check determined the document verification result alone. The agent does not run in that case, so `verdict` and `score` are both null. verdict: anyOf: - $ref: '#/components/schemas/VerdictResult' - type: 'null' description: >- The result of the analysis. Null while the detection runs, and null again after the workflow history expires. agent_error: anyOf: - type: string - type: 'null' title: Agent Error description: Why the analysis agent failed. agent_run_id: anyOf: - type: string - type: 'null' title: Agent Run Id description: The agent run, for support requests. failure_message: anyOf: - type: string - type: 'null' title: Failure Message description: A sentence that explains `failure_code`. readOnly: true type: object required: - id - status - score - billable - created_at - completed_at - submitted_by - batch_id - filename - content_type - size_bytes - s3_key - failure_message title: DetectionDetail description: The durable record plus, once completed, the workflow result. ErrorResponse: properties: detail: type: string title: Detail type: object required: - detail title: ErrorResponse description: Every error answer holds one message in `detail`. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DetectionStatus: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED title: DetectionStatus AuthoritativeResult: properties: check_id: type: string title: Check Id description: The check that proved the result. Today only `signature.pdf` can. trust: anyOf: - type: string - type: 'null' title: Trust description: >- `corroborated`, `unverified`, or `unattested`. `unattested` covers both an absent credential and one that fails verification. directive: anyOf: - type: string - type: 'null' title: Directive description: What the check found. type: object required: - check_id - trust - directive title: AuthoritativeResult description: >- A document check finding that determined the verification result before the analysis agent ran. VerdictResult: properties: fraud_score: type: integer title: Fraud Score description: >- The fraud score, normally 0 to 100. A higher score means a higher likelihood of fraud, but does not guarantee fraud. Humans should always review high-risk cases. document_type_match: type: boolean title: Document Type Match description: True if the document is the `doc_type` that you declared. actual_doc_type: anyOf: - type: string - type: 'null' title: Actual Doc Type description: >- The type that the agent found, in plain words. It repeats the declared type when `document_type_match` is true. reasoning: anyOf: - type: string - type: 'null' title: Reasoning description: >- The full explanation. This text expires after the retention period, and it is then null. per_check: items: $ref: '#/components/schemas/PerCheckResult' type: array title: Per Check description: What each check contributed. type: object required: - fraud_score - document_type_match - actual_doc_type - reasoning - per_check title: VerdictResult description: What the analysis concluded about one document. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError PerCheckResult: properties: check_id: type: string title: Check Id description: The stable id of the check, such as `metadata.dates`. importance: anyOf: - type: integer - type: 'null' title: Importance description: >- How much this finding mattered to this verdict, 0 to 10. The value is contextual; it is not a fixed weight for the check. reasoning: anyOf: - type: string - type: 'null' title: Reasoning description: Why the check reached its conclusion. type: object required: - check_id - importance - reasoning title: PerCheckResult description: One check's contribution to the verdict. securitySchemes: HTTPBearer: type: http scheme: bearer ````