> ## 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. # Start a detection > Verify one document. Supply the document with `source_url` or with `upload_id`, but not with both. The API answers before the analysis starts. Read the verdict from `GET /v1/detection/{detection_id}`. A `source_url` that the API cannot download makes this request fail with `422`. The API downloads the URL during the request, so a slow host makes a slow answer. Send the header `X-Sample-Run: true` to make the run non-billable. That header needs the scope `DocumentVerification:detections:create_sample`. Sample documents are limited per end customer by your contract; see [Billing](/document-verification/billing) and confirm your allowance with Trelent. **Scope:** `DocumentVerification:detections:create` ## OpenAPI ````yaml document-verification/api-reference/openapi.json POST /v1/detection 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: post: tags: - Detections summary: Start a detection description: >- Verify one document. Supply the document with `source_url` or with `upload_id`, but not with both. The API answers before the analysis starts. Read the verdict from `GET /v1/detection/{detection_id}`. A `source_url` that the API cannot download makes this request fail with `422`. The API downloads the URL during the request, so a slow host makes a slow answer. Send the header `X-Sample-Run: true` to make the run non-billable. That header needs the scope `DocumentVerification:detections:create_sample`. Sample documents are limited per end customer by your contract; see [Billing](/document-verification/billing) and confirm your allowance with Trelent. **Scope:** `DocumentVerification:detections:create` operationId: create_detection_v1_detection_post parameters: - name: x-sample-run in: header required: false schema: type: boolean default: false title: X-Sample-Run requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DetectionCreate' responses: '202': description: The detection is queued. content: application/json: schema: $ref: '#/components/schemas/DetectionQueuedResponse' '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' '413': description: The request is more than a size limit or a count limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '503': description: The detection could not be scheduled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] components: schemas: DetectionCreate: properties: upload_id: anyOf: - type: string pattern: ^[A-Za-z0-9-]+$ - type: 'null' title: Upload Id description: >- The prefix `uploads//` that already holds exactly one file. Use this field only if you write to object storage yourself. Give either this field or `source_url`, but not both. source_url: anyOf: - type: string - type: 'null' title: Source Url description: >- An http or https URL that the API downloads. A presigned URL is acceptable. The API does not keep the URL. The document must be 50 MB or less, and must be a PDF, PNG, JPEG, TIFF, or WebP file. doc_type: $ref: '#/components/schemas/DocType' description: The type of document that you expect. region: $ref: '#/components/schemas/Region' description: The jurisdiction that issued the document. submitted_by: anyOf: - type: string - type: 'null' title: Submitted By description: >- The owner of this detection. Give the identifier of your end user to keep the detections of your users separate. The API uses your OAuth client if you omit this field. type: object required: - doc_type - region title: DetectionCreate description: One document, named either by upload id or by a URL the API fetches. examples: - doc_type: id_card region: BR source_url: https://files.example.com/applicants/1234/id-card.pdf DetectionQueuedResponse: properties: id: type: string title: Id description: The detection id. Use it to read the result. status: $ref: '#/components/schemas/DetectionStatus' description: Always `QUEUED` for a new detection. billable: type: boolean title: Billable description: False if the request set `X-Sample-Run`. type: object required: - id - status - billable title: DetectionQueuedResponse description: The receipt for a new detection. The verdict is not ready yet. 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 DocType: type: string enum: - passport - id_card - paystub - benefit_statement - bank_statement title: DocType Region: type: string enum: - US - CA - BR title: Region description: >- Supported countries: Brazil (BR), Canada (CA), and the United States (US). Mexico is coming soon. See [Coverage](/document-verification/coverage). DetectionStatus: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED title: DetectionStatus 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 securitySchemes: HTTPBearer: type: http scheme: bearer ````