Offline devices (SMS) 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. SMS authentication should be enabled in the admin console. For configuration details, please refer to Manage PingID SDK applications in the PingID administrator guide.

Pair an SMS device to a user (POST)

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

Relative Path

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

Request body structure

{
  "automaticPairing": <true or false>,
  "phoneNumber": "<phone number>",
  "message": "<the SMS message>",
  "sender": "<the sender>",
  "deviceNickname": "<the device nickname>",
}

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 SMS message.
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 SMS pairing message. Mandatory for manual pairing, and ignored in automatic pairing. No SMS 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 not exceed 160 characters, including the trailing space and 6 characters of the OTP. Attempts to send a message which exceeds this limit will result in an error. The message may be sent in any language.
sender	The sender ID of the SMS message, which is optional for manual pairing and ignored in automatic pairing. Mandatory for manual pairing, and ignored in automatic pairing. If the sender is specified: Only numbers, English characters and spaces are allowed. Length may be up to a maximum of 11 characters. Default Ping Identity and custom Twilio sender accounts: By default, Ping Identity uses Twilio as the SMS and Voice provider. In some countries, including the US, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For International alphanumeric sender support, please refer to https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID. If the sender field is empty, the SMS sender will be an arbitrary PingID phone number, except for India. If the SMS recipient is located in India, the sender will appear as "PingID", which is the required registered sender ID in India. Custom Syniverse sender accounts: In cases where Syniverse is the SMS and Voice provider, your organization should purchase a specific alpha shortcode and also configure an alias for a specific senderId. See Syniverse's article https://sdcsupport.syniverse.com/hc/en-us/articles/115002280774-Sender-ID-Auto-Alias-Purchase-Number-Masking- for more details.
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 “Mobile 1” (or “Mobile 2”, “Mobile n” etc., incrementing the trailing digit depending on the number of SMS devices for that user).

Automatic pairing example

Automatic pairing request body

curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \     
	"phoneNumber": "12025556666", \     
	"automaticPairing": true, \
	"deviceNickname": "User1 SMS Device" \
}' 'https:// sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/smspairings'

Automatic pairing response

{
 "id": "pairing_webs_caed1a87-fbca-41b9-9271-9b5594508d6c",
 "phoneNumber": "12025556666",
 "automaticPairing": true,
 "deviceNickname": "User1 SMS Device"
}

Manual pairing example

Manual pairing request body

curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \
     "phoneNumber": "12025556666", \
     "message": "Your pairing code is: ${otp}", \
     "sender": "Company" \
}' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/smspairings'

Manual pairing response

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

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}”, 
 “sender”: “”,
 “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}/smspairings/{pairingId}/otp

Request body structure

Use the following request body structure:

{
  "otp": "<the OTP>",
  "deviceNickname": "<device nickname>"
}

Request parameters

Parameter	Description
deviceNickname	It is possible to name the device in this request. Optional. If the device was already named, renaming it at this stage overrides the previous device nickname. If the device was not previously named, the PingID SDK service will name the device “Mobile 1” (or “Mobile 2”, “Mobile n” etc., incrementing the trailing digit depending on the number of SMS devices for that user). If the device nickname is empty or missing, and the device was named when creating the pairing resource, the device name remains unchanged. The device nickname must not exceed 100 characters and can be in any language.
otp	The value of the OTP received from the user.

Parameter

Description

deviceNickname

It is possible to name the device in this request.

Optional.

If the device was already named, renaming it at this stage overrides the previous device nickname.

If the device was not previously named, the PingID SDK service will name the device “Mobile 1” (or “Mobile 2”, “Mobile n” etc., incrementing the trailing digit depending on the number of SMS devices for that user).

If the device nickname is empty or missing, and the device was named when creating the pairing resource, the device name remains unchanged.

The device nickname must not exceed 100 characters and can be in any language.

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' \
--header 'Authorization: PINGID-HMAC=<JWT>' \
-d '{ \
      "otp": "172358", \
      "deviceNickname": "SMS Device 1" \
}' 'https://sdk.pingid.com/pingid/v1/accounts/bb09a7a1-b359-418c-9c66-d8b91d83fda4/applications/3f02bbd2-1291-41ae-9663-3a2b75956d6a/users/user1/smspairings/pairing_webs_5dca4cfb-257c-4f90-a31f-eb18d9c992e2/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 an SMS 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}/smspairings/{pairingId}

Pairing resource read request 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/smspairings/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}”, 
“sender”: “Company”, 
“automaticPairing”: false

Delete an SMS 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}/smspairings/{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/smspairings/pairing_webs_db78f5fd-ddad-45fd-921f-d3f59fd1b28e'