Create a verification

Depending on the services configured for an account a verification will either use Number Verify or OTP. The default services included are Number Verify, Smart Verification Routing, and Email OTP. WhatsApp is an optional addition to the VaaS flow as a first OTP failover.

Smart Verification Routing involves automatically sending an OTP to the best messaging channel depending on the destination.

If the type in the response is silent, this means the silent authentication of the Number Verify service will be used. This service requires the person, whose phone number is being checked, to use their mobile data to load a web address (the sessionUrl).

An email address can also be included in the request, to allow an email OTP as a final failover.

It is possible, when requesting a verification, to exclude channels from the failover, in the case that a user would like to opt-out of receiving the failover OTP on specific channel(s).

Request

URL

POST https://api.cm.com/verification-service/v1/verify

Headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Body

{
  "phoneNumber": "+31612345678",
  "email": "[email protected]",
  "callbackUrl": "https://mycallbackurl",
  "excludeChannels": [
    "sms",
    "voice"
  ]
}

Parameters

Property	Type	Required	Description
phoneNumber	string	Yes	The phone number of the user to verify. This must be a valid phone number in E.164 format.
email	string	No	The email address to send an Email OTP as an optional final verification failover.
callbackUrl	string	Yes	Updates regarding the verification will be sent to the callback URL. The URL must begin with `https://`. See Events for more information.
excludeChannels	array	No	Array of channels to exclude during failover. Possible items are `whatsapp`, `voice`, `sms`, `rcs`, `viber`. To exclude Email, do not provide the `email` property in the request.

Response

{
  "id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
  "state": "pending",
  "type": "silent",
  "sessionUrl": "http://example.com/v1/dm/session/d635424bb0a54d388477cb17fa308655"
}

Parameters

Property	Description
id	Unique identifier of the verification. In UUID format. Use this to update the verification in case of an OTP failover.
state	Status of the verification. `pending`, `success`, `failed`, `expired` are the possible values. Will always be `pending` when requesting. Verifications always expire after 5 minutes.
type	`silent`, `whatsapp`, `smart`, `voice`, `email` are the possible values. Depends on the last service used to verify the user.
sessionUrl	The URL to be loaded from the mobile device using mobile data. This parameter is only included if type is `silent`.
lowConversionMode	Only included if the verification was created during a period of low conversion of Smart Verification Routing (`smart`) verifications with value `true`. This means the channel `smart` will be replaced with `voice`.

Update a verification

If the verification had to failover to one of the OTP services, the user will be required to fill in a 6 digit verification code.

Request

URL

PUT https://api.cm.com/verification-service/v1/verify/{verificationId}

Headers

Content-Type: application/json
Authorization: Bearer GENERATED_TOKEN_HERE

Body

{
  "verificationCode": "123456"
}

URL parameter

Parameter	Type	Description
verificationId	string	The unique identifier of the verification, returned in the response after requesting the initial verification.

Parameters

Property	Type	Required	Description
verificationCode	string	Yes	The verification code the user received via WhatsApp, Smart Verification Routing, or Email. The received code will always be 6 digits of length.

Response

{
  "id": "6f8d0a9d-b85c-4c3f-9e69-5699f1e00f49",
  "state": "success",
  "type": "smart"
}

Parameters

Property	Description
id	Unique identifier of the verification. In UUID format. Use this to update the verification in case of an OTP failover.
state	Status of the verification. `pending`, `success`, `failed`, `expired` are the possible values.
type	Type of verification used. `whatsapp`, `smart`, `voice`, `email` are the possible values. Depends on the last service used to verify the user.