This collection allows you to verify identity documents (ID cards, passports, residence permits) by sending document images to the Roommatik KYC API.
\nSet your credentials in the collection variables:
\napiUrl: Your KYC API base URL (e.g. https://kyc.roommatik.com)apiKey: Your API key provided by RoommatikaccountName: Your account namePrepare your document image: Convert your document image to Base64 format (without the data:image/...;base64, prefix). You can use online tools or the following command:
base64 -i document.png\nSend a request: Use the \"Verify Document - Front Side\" request to verify a document. For two-sided documents (ID cards, residence permits), send a second request with the back side using \"Verify Document - Back Side\".
\nAll requests require the X-Api-Key header with your API key. Optionally, include X-Account-Name with your account name.
Rate limits are configured per account (per minute and per day). Contact your Roommatik account manager for details on your limits.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Roommatik KYC API - Identity Document Verification","slug":"roommatik-kyc-api-identity-document-verification"}],"owner":"14975409","collectionId":"a47cb292-99c0-4af6-9ecc-543127f5ea39","publishedId":"2sBXijJBVF","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-03-21T09:55:04.000Z"},"item":[{"name":"Document Verification","item":[{"name":"Verify Document - OCR Only (fastest)","id":"6c8ff03e-bdac-44ce-a303-232ff5d7bb04","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","description":"Request content type
\n","value":"application/json"},{"key":"X-Api-Key","description":"API key for authentication (required)
\n","value":""},{"key":"X-Account-Name","description":"Account name (optional, improves routing)
\n","value":""}],"body":{"mode":"raw","raw":"{\"image\": \"\", \"returnType\": [\"Data\"], \"isMappingApplied\": true}","options":{"raw":{"language":"json"}}},"url":"https://kyc.roommatik.com/api/kyc","description":"Extract text data from a document image. This is the fastest and lightest configuration: it only returns extracted text fields without facial photo or signature images.
\nreturnType: [\"Data\"] is the fastest option. The API skips face and signature extraction, returning a smaller response with only text fields.
To also get the facial photo, use returnType: [\"Data\", \"Face\"] (see the \"With Face Embedding\" request).
Request content type
\n"},{"key":"X-Api-Key","value":"","description":"API key for authentication (required)
\n"},{"key":"X-Account-Name","value":"","description":"Account name (optional, improves routing)
\n"}],"body":{"mode":"raw","raw":"{\n \"image\": \"\",\n \"returnType\": [\"Data\"],\n \"isMappingApplied\": true\n}","options":{"raw":{"language":"json"}}},"url":"https://kyc.roommatik.com/api/kyc","description":"Send the back side of a two-sided identity document for data extraction.
\nUse this request after verifying the front side for:
\nNot needed for passports (single-sided).
\nAfter receiving both responses, merge the data objects:
const fullData = { ...frontResponse.data, ...backResponse.data };\nAPI key for authentication (required)
\n","value":""},{"key":"X-Account-Name","description":"Account name (optional, improves routing)
\n","value":""}],"body":{"mode":"raw","raw":"{\"image\": \"\", \"returnType\": [\"Data\", \"Face\", \"Signature\"], \"isMappingApplied\": true}","options":{"raw":{"language":"json"}}},"url":"https://kyc.roommatik.com/api/kyc","description":"Extract text data plus the cropped facial photograph and signature image from the document.
\nUse this when you need the document photo (e.g. to display to the user, for visual verification, or as a prerequisite for face embedding). This is slightly slower than OCR-only because the API also extracts and crops the face and signature regions.
\nSame as OCR-only, but with:
\nface: Base64-encoded cropped facial photographsignature: Base64-encoded cropped signature imageRequest content type
\n","value":"application/json"},{"key":"X-Api-Key","description":"API key for authentication (required)
\n","value":""},{"key":"X-Account-Name","description":"Account name (optional, improves routing)
\n","value":""}],"body":{"mode":"raw","raw":"{\"image\": \"\", \"returnType\": [\"Data\", \"Face\"], \"isMappingApplied\": true, \"face_vector\": true}","options":{"raw":{"language":"json"}}},"url":"https://kyc.roommatik.com/api/kyc","description":"Extract text data and compute a 512-dimensional face embedding vector from the document photo. This vector can be used for biometric face matching (e.g. comparing the document photo against a live selfie).
\nreturnType must include \"Face\". Without it, the API does not extract the facial photograph and FaceVector will always be null.
Same as standard verification, plus:
\nUse cosine similarity to compare two face vectors. A score above 0.5 generally indicates the same person:
\nfunction cosineSimilarity(a, b) {\n let dot = 0, normA = 0, normB = 0;\n for (let i = 0; i < a.length; i++) {\n dot += a[i] * b[i];\n normA += a[i] * a[i];\n normB += b[i] * b[i];\n }\n return dot / (Math.sqrt(normA) * Math.sqrt(normB));\n}\nAPI key for authentication (required)
\n","value":"","key":"X-Api-Key"},{"description":"Account name (optional, improves routing)
\n","value":"","key":"X-Account-Name"}],"body":{"mode":"formdata","formdata":[{"description":"Document image file (JPEG, PNG)
\n","key":"file","value":"","type":"file"},{"description":"Comma-separated return types: Data, Face, Signature
\n","key":"returntype","value":"Data","type":"text"},{"description":"Normalize field names
\n","key":"IsMappingApplied","value":"true","type":"text"},{"description":"Set to true to compute face embedding (requires Face in returntype)
\n","key":"face_vector","value":"false","type":"text"}]},"url":"https://kyc.roommatik.com/api/kyc","description":"Send the document as a file instead of Base64. Useful when you have the image as a file and want to avoid base64 encoding overhead.
\nNote: Do not set the Content-Type header manually. Postman sets it automatically with the multipart boundary.
Request content type
\n"},{"key":"X-Api-Key","value":"","description":"API key for authentication (required)
\n"},{"key":"X-Account-Name","value":"","description":"Account name (optional, improves routing)
\n"}],"body":{"mode":"raw","raw":"{\"image1\": \"\", \"image2\": \"\", \"returnType\": [\"Data\", \"Face\", \"Signature\"], \"isMappingApplied\": true, \"combineBothSides\": false, \"detect_orientation\": true}","options":{"raw":{"language":"json"}}},"url":"https://kyc.roommatik.com/api/v1/kyc","description":"/api/kyc.\\n\\n### Endpoint\\n\\n\\nPOST {API_URL}/api/v1/kyc\\n\\n\\n### Request Body Fields\\n\\n| Field | Type | Default | Description |\\n|-------|------|---------|-------------|\\n| image1 | string (base64) or File | — | Required. Front side of the document. Base64 encoded or file upload. |\\n| image2 | string (base64) or File | — | Required. Back side of the document. Base64 encoded or file upload. |\\n| image1Url | string | — | Alternative: S3 presigned URL for image 1 (instead of image1). |\\n| image2Url | string | — | Alternative: S3 presigned URL for image 2 (instead of image2). |\\n| combineBothSides | boolean | false | When true, the server combines both images into one before processing (server-side stitching). When false, each side is processed independently. |\\n| returnType | string[] | [\\\"Data\\\"] | Same as standard endpoint: \\\"Data\\\", \\\"Face\\\", \\\"Signature\\\". |\\n| isMappingApplied | boolean | false | When true, normalizes field names and merges fields from both sides, keeping the highest-scoring value for each field. Strongly recommended. |\\n| face_vector | boolean | false | Compute 512-dimensional face embedding. Requires \\\"Face\\\" in returnType. |\\n| detect_orientation | boolean | false | Auto-detect and correct document orientation. |\\n\\n### Response when combineBothSides: false\\n\\nEach side is processed independently:\\n\\njson\\n{\\n \\\"Image1Response\\\": {\\n \\\"keyValues\\\": { \\\"VIZ_Surname\\\": \\\"DOE\\\", ... },\\n \\\"keyScores\\\": { \\\"VIZ_Surname\\\": 0.95, ... },\\n \\\"documentInfo\\\": { \\\"nationality\\\": \\\"GBR\\\", \\\"documentType\\\": \\\"UK - Id Card\\\", \\\"documentSide\\\": 1 },\\n \\\"face\\\": \\\"data:image/jpeg;base64,...\\\"\\n },\\n \\\"Image2Response\\\": {\\n \\\"keyValues\\\": { \\\"MRZ_Surname\\\": \\\"DOE\\\", ... },\\n \\\"keyScores\\\": { \\\"MRZ_Surname\\\": 1.0, ... },\\n \\\"documentInfo\\\": { \\\"nationality\\\": \\\"GBR\\\", \\\"documentType\\\": \\\"UK - Id Card\\\", \\\"documentSide\\\": 2 }\\n }\\n}\\n\\n\\nWhen isMappingApplied: true, the gateway automatically merges fields from both sides, keeping the highest-scoring value for each field.\\n\\n### Response when combineBothSides: true\\n\\nThe server combines both images into one — the response is identical to the standard /api/kyc endpoint.\\n\\n### When to use each mode\\n\\n| Scenario | combineBothSides |\\n|----------|--------------------|\\n| Need to know which side each field came from | false |\\n| Different field priorities per side | false |\\n| Simple integration, server-side combination | true |\\n| Single-sided documents (passports) | Use standard /api/kyc instead |Endpoints for verifying identity documents. Send a document image encoded in Base64 and receive extracted data fields (name, document number, expiry date, etc.).
\n","_postman_id":"325adcbc-a4a0-49f0-90d3-5e81a9d91b45"},{"name":"Utilities","item":[{"name":"Health Check","id":"5832976c-0a7f-43f3-bf8d-72232fcaa4bf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://kyc.roommatik.com/health","description":"Check if the KYC API server is online and healthy.
\nThis request uses the frontImageBase64 collection variable. To use it:
frontImageBase64 variableLinux/macOS:
\nbase64 -i document.png | tr -d '\\n' | pbcopy\nWindows PowerShell:
\n[Convert]::ToBase64String([IO.File]::ReadAllBytes(\"document.png\")) | Set-Clipboard\nThen paste the result into the frontImageBase64 variable.
Request content type
\n","key":"Content-Type"},{"value":"","description":"API key for authentication (required)
\n","key":"X-Api-Key"}],"body":{"mode":"raw","raw":"{\"Base64Data\": \"{{qrBase64Data}}\"}","options":{"raw":{"language":"json"}}},"url":"https://kyc.roommatik.com/api/qr/midni","description":"Decode and verify a QR code generated by the Spanish miDNI mobile app.
\n*Exactly one of Base64Data or HexData must be provided.
Important: This endpoint expects the raw binary data from the QR code, not an image of the QR. Use a QR scanning library to extract the payload first.
\nThe response uses the same normalized field names as the OCR endpoint (firstName, lastName, documentNumber, etc.), plus QR-specific fields like signatureValid, dataExpired, address, and birthPlace.
The API automatically validates:
\nHelper requests for testing and debugging.
\n","_postman_id":"0b9dcf88-5d3c-4cd0-a5d7-f7a69dcdc613"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["// Ensure API URL doesn't have trailing slash","let apiUrl = pm.collectionVariables.get('apiUrl');","if (apiUrl && apiUrl.endsWith('/')) {"," pm.collectionVariables.set('apiUrl', apiUrl.slice(0, -1));","}"],"id":"87f2a920-b9d5-4b73-8b0e-792ad6a8e055"}},{"listen":"test","script":{"type":"text/javascript","exec":["// Common tests for all requests","pm.test('Response time is acceptable', function () {"," pm.expect(pm.response.responseTime).to.be.below(60000);","});","","if (pm.response.code === 200) {"," pm.test('Response has data object', function () {"," const json = pm.response.json();"," pm.expect(json).to.have.property('data');"," pm.expect(json).to.have.property('responseTime');"," });",""," pm.test('Document side is identified', function () {"," const json = pm.response.json();"," pm.expect(json.data).to.have.property('DocumentSide');"," });","}"],"id":"07f917bb-9d74-4821-8a38-811bab70117e"}}],"variable":[{"key":"apiUrl","value":"https://kyc.roommatik.com","type":"string","description":"KYC API base URL. Provided by Roommatik."},{"key":"apiKey","value":"","type":"string","description":"Your API key for authentication. Provided by Roommatik."},{"key":"accountName","value":"","type":"string","description":"Your account name (optional, improves request routing)."},{"key":"frontImageBase64","value":"","type":"string","description":"Base64-encoded front side image (without data:image prefix). Paste your image here."},{"key":"backImageBase64","value":"","type":"string","description":"Base64-encoded back side image (without data:image prefix). Paste your image here."}]}