Offline devices (voice) pairing API

A device may be paired with a user, only in the context of an application. As a prerequisite, the user and application must be created before device pairing can take place. Voice authentication should be enabled in the admin console. For configuration details, please refer to Manage PingID SDK applications in the PingID administrator guide.

Pair a voice device to a user (POST)

The POST method is used in order to pair a user with a voice device.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/voicepairings

Request body structure

{
  "automaticPairing": <true or false>,
  "deviceNickname": "<the device nickname>",
  "locale": "string",
  "phoneNumber": "<phone number>",
  "message": "string",
  "voiceParameters": {},
  "voice": "Alice"
}

Request parameters

Parameter	Description
automaticPairing	Determine whether the pairing is automatic or manual. Optional. Valid values: True: The user will be automatically paired False (default): After making this call, the authentication must be finalized using the OTP received from the user, who in turn, received it in the voice message.
deviceNickname	It is possible to name the device in this request. Optional. The device nickname must not exceed 100 characters and can be in any language. If the device nickname is empty, the PingID SDK service will name the device “Phone 1” (or “Phone 2”, “Phone n” etc., incrementing the trailing digit depending on the number of voice devices for that user).
locale	The international locale for voice configuration. Optional. Default is "en_US". Ignored in automatic pairing.
phoneNumber	The phone number to be paired. Mandatory. Valid values: The phone number must begin with the country code. Any format may be used, as the PingID SDK server filters out all characters except for digits. Pairing a user with an invalid phone number results in an error.
message	The voice pairing message. Mandatory for manual pairing, and ignored in automatic pairing. No voice message is sent in automatic pairing. The OTP is generated in the PingID SDK server, and sent in this message. The ${otp} parameter may optionally be used in the message to embed the OTP value in a specific position of the message, for example, “Your pairing code is: ${otp}”. The value of ${otp} is dynamically populated at message transmission time. The ${otp} parameter is not case sensitive. The ${otp} parameter may be used multiple times in the message. If the ${otp} parameter is not used in the message, the message will be appended with one space followed by the value of the OTP. The message may be sent in any supported language. Application parameters defined in the voiceParameters declaration may be used for embedding application values into the voice message. Note: The length of the message may impact the cost of the call. The following substitution place holders may be embedded in the message: <pause1sec> Pauses the message narration for 1 second. <sayCharValue> .. </sayCharValue> Reads the character name of each character of the enclosed string separately. <repeatMessage val=x> .. </repeatMessage> Narrates the enclosed text <val> number of times. In the following message example, ${OTP} is assigned the value “123456”, and ${email} is assigned the value “joe@bxz.com”: `Hello <pause1sec> your authentication code is <sayCharValue>${OTP}</sayCharValue> <repeatMessage val=2>I repeat your code is <sayCharValue>${OTP}</sayCharValue></repeatMessage> <pause1sec> Mail <sayCharValue>${email}</sayCharValue> for help` The narrated message on the voice call will sound like: `HELLO <1 second silence> YOUR AUTHENTICATION CODE IS ONE TWO THREE FOUR FIVE SIX I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX <1 second silence> MAIL JAY OH EE AT BEE EX ZEE DOT SEE OH EM FOR HELP`
vendor	Deprecated.
voice	Vendor specific supported voices. Currently supported Twilio voices: Alice (default) Supported locales (default: en_US): da_DK, de_DE, en_AU, en_CA, en_GB, en_IN, en_US, ca_ES, es_ES, es_MX, fi_FI, fr_CA, fr_FR, it_IT, ja_JP, ko_KR, nb_NO, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, sv_SE, zh_CN, zh_HK, zh_TW Man, Woman Supported locales (default: en): en, en_GB, es, fr, de Currently supported Syniverse voices: Supported locales (default: en_US): en_US, en_GB, es_ES, fr_FR, de_DE, it_IT Syniverse's default voices are used, based on locale and gender. Using Alice and Woman in the API are interpreted as Female in Syniverse. Using Man in the API is interpreted as Male in Syniverse. Priority is given first to locale (en_US is default), and then gender (Female is default).
voiceParameters	User defined parameters, for the purpose of embedding application values into the voice message. Optional. You can define any application parameters, except for ${otp} or parameters starting with ${pingid_}

Automatic pairing example

Automatic pairing request body

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "automaticPairing": true, \ 
   "deviceNickname": "My Voice Device", \ 
   "locale": "en_US", \ 
   "phoneNumber": "12025556666", \ 
   "message": "Hi your code is", \ 
   "voiceParameters": {}, \ 
   "voice": "Alice" \ 
}' 'https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/user1/voicepairings'

Automatic pairing response

"application": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/or1/voicepairings/pairing_webs_9ded2324-aa57-4edc-90a7-48c5e7ccafb5"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/users/user1"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d"
  },
  "voiceParameters": {},
  "voice": "Alice",
  "phoneNumber": "12025556666",
  "message": "Hi your code is",
  "automaticPairing": true,
  "id": "pairing_webs_9ded2324-aa57-4edc-90a7-48c5e7ccafb5",
  "deviceId": "1a840326-e989-b079-1a84-0326e989b079",
  "deviceNickname": "My Voice Device",
  "deviceType": "VOICE",
  "locale": "en_US"
}

Manual pairing example

Manual pairing request body

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "automaticPairing": false, \ 
   "deviceNickname": "My Voice Device", \ 
   "locale": "en_US", \ 
   "phoneNumber": "12025556666", \ 
   "message": "Hi your code is", \ 
   "voiceParameters": {}, \ 
   "voice": "Alice" \ 
 }' 'https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/user1/voicepairings'

Manual pairing response

{
  "application": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6"
  },
  "self": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/user1/voicepairings/pairing_webs_4248475d-3e9d-4cbe-962a-a6e7f8c98e43"
  },
  "user": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/users/user1"
  },
  "account": {
    "href": "https://sdk.pingid.com/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d"
  },
  "voiceParameters": {},
  "voice": "Alice",
  "phoneNumber": "12025556666",
  "message": "Hi your code is",
  "automaticPairing": false,
  "id": "pairing_webs_4248475d-3e9d-4cbe-962a-a6e7f8c98e43",
  "deviceId": "4c93e321-a7a2-4f92-4c93-e321a7a24f92",
  "deviceNickname": "My Voice Device",
  "deviceType": "VOICE",
  "locale": "en_US"
}

Finalizing manual pairing

The POST method using the "automaticPairing": true parameter completes automatic pairing. However, manual pairing requires an additional finalizing step to reach completion.

Any attempt to finalize pairing with OTP when the device was automatically paired, results with an error.

In order to finalize manual pairing, you must update the pairing resource with the OTP received from the user. For example, if you received the following response after creating the pairing resource:

{
 "id": "pairing_webs_5dca4cfb-257c-4f90-a31f-eb18d9c992e2",  
 "phoneNumber": "12025556666", 
 "message": "Your pairing code is: ${otp}", 
 "automaticPairing": false
}

The created pairing id is pairing_webs_5dca4cfb-257c-4f90-a31f-eb18d9c992e2.

Once you receive the OTP from the user, you can finalize the pairing process by using the PUT method to call the URL in the following relative path:

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/voicepairings/{pairingId}/otp

Request body structure

Use the following request body structure:

{
  "otp": "<the OTP>"
}

Request parameters

Parameter	Description
otp	The value of the OTP received from the user.

Manual pairing finalizing request example

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
   "otp": "102030" \
 }' 'http://localhost:8082/pingid/v1/accounts/a3407e72-71af-4831-a6a1-37e5e94fc07d/applications/dad9528a-f889-4b90-9300-b929d995a2b6/users/user1/voicepairings/pairing_webs_19a25134-e4b1-4a4d-873b-ef1e9730f378/otp'

Entering an incorrect OTP returns an error response, for example:

{ 
"message": "Couldn’t pair user", 
"details": [ 
            {
             "message": "Invalid passcode", 
             "target": "otp", 
             "code": "INVALID_VALUE"
            }
           ],
"code": "REQUEST_FAILED" 
}

Entering 3 incorrect OTPs in succession terminates the pairing process, results in the deletion of the pairing resource, and returns an error response, for example:

{ 
"message": "Couldn’t pair user", 
"details": [ 
            {
             "message": "Exceeded max passcode retry limit" , 
             "target": "otp", 
             "code": "RETRY_LIMIT_EXCEEDED"
            }
           ],
"code": "REQUEST_FAILED" 
}

Read a Voice pairing resource (GET)

When a pairing process is invoked, a temporary pairing resource is created, which has a maximum lifetime of 30 minutes. The pairing resource is automatically deleted after successful completion of pairing, and in the case of a failure following entry of 3 incorrect OTPs.

While the pairing resource exists, the GET method may be used in order to read it.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/voicepairings/{pairingId}

Pairing resource read request example

REPLACE THE FOLLOWING EXAMPLE

curl -X GET \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user4/voicepairings/pairing_webs_db78f5fd-ddad-45fd-921f-d3f59fd1b28e'

Pairing resource read request response example

"id": "pairing_webs_db78f5fd-ddad-45fd-921f-d3f59fd1b28e",
"phoneNumber": "12025556666",
"message": "Your pairing code is: ${otp}", 
"automaticPairing": false

Delete a voice pairing resource (DELETE)

If a pairing process is manual, it is possible to cancel the process by deleting the temporary pairing resource which was created at its inception. However, deletion of the temporary pairing resource for an automatic pairing process will not unpair the device.

Use the DELETE method to cancel a manual pairing process.

Relative Path

/accounts/{accountId}/applications/{applicationId}/users/{username}/voicepairings/{pairingId}

Pairing resource deletion request example

curl -X DELETE \
--header 'Accept: application/json'--header 'Authorization: PINGID-HMAC=<JWT>'
'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user4/voicepairings/pairing_webs_db78f5fd-ddad-45fd-921f-d3f59fd1b28e'