{"openapi":"3.1.0","info":{"title":"ThisVerify API","version":"2026-10-01","description":"Document forgery detection for bank transfers, payment-app screenshots, bank statements, payslips, medical documents and invoices. Create a scan, then poll it or receive a signed webhook when it completes.","contact":{"name":"ThisVerify","url":"https://thisverify-green.vercel.app/developers"}},"servers":[{"url":"https://thisverify-green.vercel.app/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Scans"},{"name":"Account"},{"name":"Webhooks","description":"Outgoing events, signed with HMAC-SHA256."}],"paths":{"/":{"get":{"tags":["Account"],"summary":"Verify the API key","operationId":"whoami","responses":{"200":{"description":"Key details","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"api_key"},"organization":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/scans":{"post":{"tags":["Scans"],"summary":"Create a scan","operationId":"createScan","description":"Upload a document for analysis. Returns 202 with a queued scan. Analysis usually completes within 15–60 seconds. Send an `Idempotency-Key` header to make retries safe.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"context":{"type":"string","description":"JSON-encoded ScanContext"},"metadata":{"type":"string","description":"JSON-encoded string map"},"lang":{"type":"string","enum":["he","en"]},"client_reference":{"type":"string","maxLength":200}}}},"application/json":{"schema":{"$ref":"#/components/schemas/CreateScanJson"}}}},"responses":{"200":{"description":"Idempotent replay of an earlier request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"202":{"description":"Scan accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"get":{"tags":["Scans"],"summary":"List scans","operationId":"listScans","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["queued","processing","completed","failed"]}},{"name":"verdict","in":"query","schema":{"type":"string","enum":["low_risk","review","high_risk"]}},{"name":"client_reference","in":"query","schema":{"type":"string"}},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A page of scans","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Scan"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/scans/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Scans"],"summary":"Retrieve a scan and its report","operationId":"getScan","parameters":[{"name":"include","in":"query","schema":{"type":"string","enum":["report","summary"],"default":"report"}}],"responses":{"200":{"description":"The scan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Scans"],"summary":"Delete a scan permanently","operationId":"deleteScan","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"const":true}}}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/usage":{"get":{"tags":["Account"],"summary":"Current period usage","operationId":"getUsage","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":["integer","null"]},"remaining":{"type":["integer","null"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}}}}}}}}},"webhooks":{"scan.completed":{"post":{"tags":["Webhooks"],"summary":"A scan finished","description":"Verify the `ThisVerify-Signature` header: `t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>`. Reject events older than 5 minutes. Respond with 2xx within 10 seconds; failed deliveries are retried with backoff.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"scan.failed":{"post":{"tags":["Webhooks"],"summary":"A scan could not be completed","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"tv_live_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}},"schemas":{"ScanContext":{"type":"object","description":"Expected values to cross-check against the document.","properties":{"docTypeHint":{"type":"string","enum":["bank_transfer","payment_app","bank_statement","account_confirmation","balance_confirmation","check","deposit_receipt","card_statement","payslip","invoice","tax_form","id_document","utility_bill","loan_document","medical","contract","other"]},"expectedAmount":{"type":"string"},"expectedName":{"type":"string"},"expectedDate":{"type":"string","format":"date"},"expectedReference":{"type":"string"},"notes":{"type":"string"}}},"CreateScanJson":{"type":"object","properties":{"file":{"type":"object","properties":{"name":{"type":"string"},"content_base64":{"type":"string"}}},"file_url":{"type":"string","format":"uri","description":"Public https URL (e.g. a pre-signed S3 link). Fetched within 15 seconds; redirects are not followed."},"file_name":{"type":"string"},"context":{"$ref":"#/components/schemas/ScanContext"},"lang":{"type":"string","enum":["he","en"],"description":"Language of report texts"},"client_reference":{"type":"string","maxLength":200,"description":"Your own identifier (application id, case number)"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"maxProperties":20}}},"Box":{"type":"object","description":"Location in percent of the page","properties":{"page":{"type":"integer"},"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}}},"Finding":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["metadata","structure","pixel","content","ai","history"]},"engine":{"type":["string","null"]},"category":{"type":"string","enum":["text_edit","font_mismatch","alignment","background_patch","copy_paste","compression","pixel_manipulation","layout_template","logo_branding","status_misleading","date_time_logic","amount_logic","identity_mismatch","screenshot_artifact","ai_generated","editing_software","file_structure","file_history","signature","duplicate","expectation_mismatch","embedded_instructions","other"]},"severity":{"type":"string","enum":["info","low","medium","high","critical"]},"confidence":{"type":"number"},"impact":{"type":["integer","null"],"description":"Points contributed to risk_score"},"title":{"type":"string"},"detail":{"type":"string"},"evidence":{"type":["string","null"]},"box":{"oneOf":[{"$ref":"#/components/schemas/Box"},{"type":"null"}]}}},"Scan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"scan"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"stage":{"type":"string"},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"client_reference":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"file":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"size":{"type":"integer"},"sha256":{"type":"string"},"available":{"type":"boolean"}}},"verdict":{"type":["string","null"],"enum":["low_risk","review","high_risk",null]},"risk_score":{"type":["integer","null"],"minimum":0,"maximum":100},"document_type":{"type":["string","null"],"enum":["bank_transfer","payment_app","bank_statement","account_confirmation","balance_confirmation","check","deposit_receipt","card_statement","payslip","invoice","tax_form","id_document","utility_bill","loan_document","medical","contract","other",null]},"issuer":{"type":["string","null"]},"channel":{"type":["string","null"],"enum":["native_pdf","scanned_pdf","app_screenshot","web_screenshot","photo_of_screen","photo_of_paper","image_export","unknown",null]},"report":{"type":"object","properties":{"summary":{"type":"string"},"recommended_actions":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"checks":{"type":"array","items":{"type":"object"}},"extracted":{"type":"object"},"forensic_analysis":{"type":["object","null"]}}}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["scan.completed","scan.failed","ping"]},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/Scan"}}}}}}}}