Identity Check

v1.1.0Sandbox ready

Match a national ID number against a name and date of birth, and check whether a phone number is registered to the same person.

New in 1.1.0Added phoneMatch to the verification result.

DownloadOpenAPI (JSON)OpenAPI (YAML)Postman collection Generated clients

Authentication

Swap your keys for a token

Send your app's consumer key and secret to the token endpoint using HTTP Basic auth. You get a bearer token that lasts one hour. Send it in the Authorization header of every call.

Sandbox base URL https://devportal.softwaregroup.com/api/sandbox

Get keys for Identity

curl -X POST 'https://devportal.softwaregroup.com/api/sandbox/oauth/v1/token' \
  -u "$LANGO_KEY:$LANGO_SECRET" \
  -d 'grant_type=client_credentials'

Verify a person

POST/identity/v1/verifications

Needs the customer's consent. Send the consent reference you recorded.

Request body

idTypestringrequired: NATIONAL_ID · PASSPORT · ALIEN_ID
idNumberstringrequired: In the sandbox, 00000001 and 00000002 trigger mismatch scenarios.
firstNamestringrequired
lastNamestringrequired
dateOfBirthdate
phoneNumberstring
consentReferencestringrequired: Your record of the customer's consent.

Responses

200The verification result.Fields

200 body

verificationIdstring
outcomestring: MATCH · PARTIAL · NOT_FOUND
nameMatchboolean
dateOfBirthMatchboolean
phoneMatchboolean
checkedAtdate-time

422The ID number is not valid for that ID type.Fields

422 body

errorstring
messagestring
requestIdstring

Sandbox scenarios

Everything matchesdefault

200

Name does not matchidNumber = "00000001"

200

ID not on the registeridNumber = "00000002"

200

Malformed ID numberidNumber = "ABC"

422

curl -X POST 'https://devportal.softwaregroup.com/api/sandbox/identity/v1/verifications' \
  -H "Authorization: Bearer $LANGO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idType": "NATIONAL_ID",
    "idNumber": "27845120",
    "firstName": "Wanjiru",
    "lastName": "Kamau",
    "dateOfBirth": "1991-04-17",
    "phoneNumber": "254712345678",
    "consentReference": "CNS-88213"
  }'

Try it in the sandboxno keys needed

POST/identity/v1/verifications

{
  "idType": "NATIONAL_ID",
  "idNumber": "27845120",
  "firstName": "Wanjiru",
  "lastName": "Kamau",
  "dateOfBirth": "1991-04-17",
  "phoneNumber": "254712345678",
  "consentReference": "CNS-88213"
}

Choose what happens

Fetch a past verification

GET/identity/v1/verifications/{verificationId}

Path parameters

verificationIdstringrequired

Responses

200The stored result.Fields

200 body

verificationIdstring
outcomestring: MATCH · PARTIAL · NOT_FOUND
nameMatchboolean
dateOfBirthMatchboolean
phoneMatchboolean
checkedAtdate-time

Sandbox scenarios

Founddefault

200

curl -X GET 'https://devportal.softwaregroup.com/api/sandbox/identity/v1/verifications/vrf_2m8x4c1z' \
  -H "Authorization: Bearer $LANGO_TOKEN"

Try it in the sandboxno keys needed

GET/identity/v1/verifications/vrf_2m8x4c1z

Choose what happens