{"openapi":"3.0.3","info":{"title":"Identity Check","version":"1.1.0","summary":"Confirm a customer is who they say they are.","description":"Match a national ID number against a name and date of birth, and check whether a phone number is registered to the same person."},"x-lango":{"slug":"identity-check","auth":"oauth2_client_credentials","changelog":"Added `phoneMatch` to the verification result."},"paths":{"/identity/v1/verifications":{"post":{"operationId":"createVerification","summary":"Verify a person","description":"Needs the customer's consent. Send the consent reference you recorded.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationRequest"},"example":{"idType":"NATIONAL_ID","idNumber":"27845120","firstName":"Wanjiru","lastName":"Kamau","dateOfBirth":"1991-04-17","phoneNumber":"254712345678","consentReference":"CNS-88213"}}}},"responses":{"200":{"description":"The verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"422":{"description":"The ID number is not valid for that ID type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-sandbox-scenarios":[{"key":"match","title":"Everything matches","default":true,"status":200,"delayMs":380,"response":{"verificationId":"{{id:vrf}}","outcome":"MATCH","nameMatch":true,"dateOfBirthMatch":true,"phoneMatch":true,"checkedAt":"{{now}}"}},{"key":"name_mismatch","title":"Name does not match","match":{"field":"body.idNumber","equals":"00000001"},"status":200,"delayMs":380,"response":{"verificationId":"{{id:vrf}}","outcome":"PARTIAL","nameMatch":false,"dateOfBirthMatch":true,"phoneMatch":true,"checkedAt":"{{now}}"}},{"key":"not_found","title":"ID not on the register","match":{"field":"body.idNumber","equals":"00000002"},"status":200,"delayMs":380,"response":{"verificationId":"{{id:vrf}}","outcome":"NOT_FOUND","nameMatch":false,"dateOfBirthMatch":false,"phoneMatch":false,"checkedAt":"{{now}}"}},{"key":"invalid_id","title":"Malformed ID number","match":{"field":"body.idNumber","equals":"ABC"},"status":422,"delayMs":30,"response":{"error":"INVALID_ID_NUMBER","message":"idNumber must be 7 or 8 digits for NATIONAL_ID.","requestId":"{{id:req}}"}}]}},"/identity/v1/verifications/{verificationId}":{"get":{"operationId":"getVerification","summary":"Fetch a past verification","parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string"},"example":"vrf_2m8x4c1z"}],"responses":{"200":{"description":"The stored result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}}},"x-sandbox-scenarios":[{"key":"found","title":"Found","default":true,"status":200,"delayMs":50,"response":{"verificationId":"{{path.verificationId}}","outcome":"MATCH","nameMatch":true,"dateOfBirthMatch":true,"phoneMatch":true,"checkedAt":"{{now}}"}}]}}},"components":{"schemas":{"VerificationRequest":{"type":"object","required":["idType","idNumber","firstName","lastName","consentReference"],"properties":{"idType":{"type":"string","enum":["NATIONAL_ID","PASSPORT","ALIEN_ID"]},"idNumber":{"type":"string","description":"In the sandbox, 00000001 and 00000002 trigger mismatch scenarios."},"firstName":{"type":"string"},"lastName":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"phoneNumber":{"type":"string"},"consentReference":{"type":"string","description":"Your record of the customer's consent."}}},"Verification":{"type":"object","properties":{"verificationId":{"type":"string"},"outcome":{"type":"string","enum":["MATCH","PARTIAL","NOT_FOUND"]},"nameMatch":{"type":"boolean"},"dateOfBirthMatch":{"type":"boolean"},"phoneMatch":{"type":"boolean"},"checkedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"servers":[{"url":"https://devportal.softwaregroup.com/api/sandbox","description":"Sandbox"},{"url":"https://devportal.softwaregroup.com/api/live","description":"Production"}]}