Rate this page

Validated Phone Numbers

An account management application can use the validatedPhoneNumbers SCIM sub-resource to deliver a one-time code to confirm a user’s ownership of a phone number. Once this is done, the phone number may be used to receive one-time password codes as an authentication factor.

The following table describes the fields of a telephony validation request.

Field Type Required? Description
schemas array yes The SCIM schema of the telephony verification request. Always has the value urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest.
meta complex no Will always contain a resourceType sub-attribute with the default value Phone Number Validator. Will always contain a location attribute with the validated phone number resource’s canonical URI.
attributePath string yes The SCIM attribute path containing the phone number. For example, phoneNumbers[type eq "mobile"].
attributeValue string no The phone number.
message complex yes The message used when sending the verification code. This is an object with two fields, described in the following table.
messagingProvider string yes The messaging provider (for example, “Twilio SMS Provider”) to use when sending the verification code.
verifyCode string yes A verification code to submit for confirmation.

The value of the message field is an object with two fields:

Field Type Required? Description
message string yes The message to be delivered. This field must contain a %code% placeholder string for the validation code.
language string no The language and locale of the message.

The following table describes the fields of a telephony validation response.

Field Type Provided? Description
schemas array always The SCIM schema of the password resource. Always has the value urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest.
meta complex no Will always contain a resourceType sub-attribute with the value Phone Number Validator. Will always contain a location attribute with the validated phone number resource’s canonical URI.
attributePath string always The SCIM attribute path containing the telephone number. For example, phoneNumbers[type eq "mobile"].
attributeValue string The phone number.
validated boolean Whether the current phone number was successfully validated.
validatedAt datetime The last time the current phone number was successfully validated.
codeSent boolean Whether a verification code was sent and is pending validation.

Retrieve a user’s validated phone number states for all configured attribute paths

GET /scim/v2/Users/{id}/validatedPhoneNumbers

GET /scim/v2/Me/validatedPhoneNumbers

The Data Governance Broker administrator may configure one or more SCIM attribute paths to identify a phone number that may be validated. A GET to a user’s root validatedPhoneNumbers sub-resource will return a list response containing zero or more matching resources corresponding to these attribute paths. The validated field of each resource indicates if that phone number has already been validated. The validatedAt field of each resource, if present, indicates when the phone number was validated.

Example request:

GET /scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Length: 563
Content-Type: application/scim+json
Date: Tue, 13 Sep 2016 00:58:20 GMT

{
    "Resources": [
        {
            "attributePath": "secondFactorPhoneNumber", 
            "attributeValue": "1-555-244-2888", 
            "id": "secondFactorPhoneNumber", 
            "messagingProvider": "Twilio SMS Provider", 
            "meta": {
                "location": "https://example.com/scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/secondFactorPhoneNumber", 
                "resourceType": "Phone Number Validator"
            }, 
            "schemas": [
                "urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest"
            ], 
            "validated": true, 
            "validatedAt": "2016-09-12T22:32:15.440Z"
        }
    ], 
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ], 
    "totalResults": 1
}

Retrieve a user’s validated phone number states for a specific attribute path

GET /scim/v2/Users/{id}/validatedPhoneNumbers/{attributePath}

GET /scim/v2/Me/validatedPhoneNumbers/{attributePath}

The Data Governance Broker administrator may configure one or more SCIM attribute paths to identify a phone number that may be validated. A client can perform a GET to a user’s validatedPhoneNumbers sub-resource using an attribute path as the sub-resource ID. The validated field of the response will indicate if that phone number has already been validated. The validatedAt field, if present, indicates when the phone number was validated.

Example request:

GET /scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/secondFactorPhoneNumber HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Type: application/scim+json
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Length: 465
Content-Type: application/scim+json
Date: Tue, 13 Sep 2016 00:57:32 GMT

{
    "attributePath": "secondFactorPhoneNumber",
    "attributeValue": "1-555-244-2888",
    "id": "secondFactorPhoneNumber",
    "messagingProvider": "Twilio SMS Provider",
    "meta": {
        "location": "https://example.com/scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/secondFactorPhoneNumber",
        "resourceType": "Phone Number Validator"
    },
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest"
    ],
    "validated": true,
    "validatedAt": "2016-09-12T22:32:15.440Z"
}

Validate a user’s phone number

A web application may validate a user’s phone number using a special multi-step flow.

Deliver a validation code

POST /scim/v2/Users/{id}/validatedPhoneNumbers

POST /scim/v2/Me/validatedPhoneNumbers

Submitting a POST request to a user’s validatedPhoneNumbers sub-resource will cause a verification code to be delivered to the phone number specified in the request. The Data Governance Broker’s response will include a special temporary resource representing a stateful verification request, with the request state encoded in the resource ID. The response will use a 201 Created status code, with the temporary state URI provided in the Location header and meta.location attribute. This URI will be used in the next step when confirming the verification code provided by the user.

Example request:

POST /scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 338
Content-Type: application/scim+json
Host: example.com

{
    "attributePath": "secondFactorPhoneNumber",
    "attributeValue": "1-555-244-2888",
    "message": {
        "language": "en-US",
        "message": "Your verification code: %code%"
    },
    "messagingProvider": "Twilio SMS Provider",
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest"
    ]
}

Example response:

HTTP/1.1 201 Created
Content-Length: 899
Content-Type: application/scim+json
Date: Mon, 12 Sep 2016 22:29:18 GMT
Location: https://example.com/scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/AaKriHSNeanzmgAWpSqJWJU0IY_xAAAAAAAAAADOyPm6kEQ1aUX6DBMvr15dybDB9zdj7myTN7c4i5Wq4lvnq-a-3yuM7zsCfBItWHgAvCSIplccM48dzNrreM3lmY4sjjP0NYlLA3oagOfRKDxiiGzXFIlWVpxxNSyANRVTMrqIts3Dv7CDAtxgL0SIyIJbRV8af6mzgaoUF3hbrxCjqlDl39Jm_s8ggNBtdxuB4BO1LbNfsDLmSzWX-0wb

{
    "attributePath": "secondFactorPhoneNumber",
    "attributeValue": "1-555-244-2888",
    "codeSent": true,
    "id": "AaKriHSNeanzmgAWpSqJWJU0IY_xAAAAAAAAAADOyPm6kEQ1aUX6DBMvr15dybDB9zdj7myTN7c4i5Wq4lvnq-a-3yuM7zsCfBItWHgAvCSIplccM48dzNrreM3lmY4sjjP0NYlLA3oagOfRKDxiiGzXFIlWVpxxNSyANRVTMrqIts3Dv7CDAtxgL0SIyIJbRV8af6mzgaoUF3hbrxCjqlDl39Jm_s8ggNBtdxuB4BO1LbNfsDLmSzWX-0wb",
    "messagingProvider": "Twilio SMS Provider",
    "meta": {
        "location": "https://example.com/scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/AaKriHSNeanzmgAWpSqJWJU0IY_xAAAAAAAAAADOyPm6kEQ1aUX6DBMvr15dybDB9zdj7myTN7c4i5Wq4lvnq-a-3yuM7zsCfBItWHgAvCSIplccM48dzNrreM3lmY4sjjP0NYlLA3oagOfRKDxiiGzXFIlWVpxxNSyANRVTMrqIts3Dv7CDAtxgL0SIyIJbRV8af6mzgaoUF3hbrxCjqlDl39Jm_s8ggNBtdxuB4BO1LbNfsDLmSzWX-0wb",
        "resourceType": "Phone Number Validator"
    },
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest"
    ],
    "validated": false
}

Confirm a delivered validation code

PUT /scim/v2/Users/{id}/validatedPhoneNumbers/{verificationId}

PUT /scim/v2/Me/validatedPhoneNumbers/{verificationId}

If the result of the POST request above was successful, then the application can prompt the user to provide the verification code received at his or her phone number. The application should then make a PUT request to the new URI from the previous POST response, including the verification code provided by the user in the verifyCode field.

If the verification code is confirmed by the Data Governance Broker, then a 200 OK response will be returned, and the application may consider the phone number verified. If not — either because an invalid code was submitted or the code has expired — a 400 Bad Request response will be returned with a scimType value of invalidValue.

Request:

PUT /scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/AaKriHSNeanzmgAWpSqJWJU0IY_xAAAAAAAAAADOyPm6kEQ1aUX6DBMvr15dybDB9zdj7myTN7c4i5Wq4lvnq-a-3yuM7zsCfBItWHgAvCSIplccM48dzNrreM3lmY4sjjP0NYlLA3oagOfRKDxiiGzXFIlWVpxxNSyANRVTMrqIts3Dv7CDAtxgL0SIyIJbRV8af6mzgaoUF3hbrxCjqlDl39Jm_s8ggNBtdxuB4BO1LbNfsDLmSzWX-0wb HTTP/1.1
Accept: application/scim+json
Authorization: Bearer eyJhbGciOi...
Content-Length: 1023
Content-Type: application/scim+json
Host: example.com

{
    "attributePath": "secondFactorPhoneNumber",
    "attributeValue": "1-555-244-2888",
    "codeSent": true,
    "id": "AaKriHSNeanzmgAWpSqJWJU0IY_xAAAAAAAAAADOyPm6kEQ1aUX6DBMvr15dybDB9zdj7myTN7c4i5Wq4lvnq-a-3yuM7zsCfBItWHgAvCSIplccM48dzNrreM3lmY4sjjP0NYlLA3oagOfRKDxiiGzXFIlWVpxxNSyANRVTMrqIts3Dv7CDAtxgL0SIyIJbRV8af6mzgaoUF3hbrxCjqlDl39Jm_s8ggNBtdxuB4BO1LbNfsDLmSzWX-0wb",
    "messagingProvider": "Twilio SMS Provider",
    "meta": {
        "location": "https://example.com/scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/AaKriHSNeanzmgAWpSqJWJU0IY_xAAAAAAAAAADOyPm6kEQ1aUX6DBMvr15dybDB9zdj7myTN7c4i5Wq4lvnq-a-3yuM7zsCfBItWHgAvCSIplccM48dzNrreM3lmY4sjjP0NYlLA3oagOfRKDxiiGzXFIlWVpxxNSyANRVTMrqIts3Dv7CDAtxgL0SIyIJbRV8af6mzgaoUF3hbrxCjqlDl39Jm_s8ggNBtdxuB4BO1LbNfsDLmSzWX-0wb",
        "resourceType": "Phone Number Validator"
    },
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest"
    ],
    "validated": false,
    "verifyCode": "591740"
}

Response:

HTTP/1.1 200 OK
Content-Length: 465
Content-Type: application/scim+json
Date: Mon, 12 Sep 2016 22:32:15 GMT

{
    "attributePath": "secondFactorPhoneNumber",
    "attributeValue": "1-555-244-2888",
    "id": "secondFactorPhoneNumber",
    "messagingProvider": "Twilio SMS Provider",
    "meta": {
        "location": "https://example.com/scim/v2/Users/b3cc7239-e704-4c24-8c3f-d64e48163e26/validatedPhoneNumbers/secondFactorPhoneNumber",
        "resourceType": "Phone Number Validator"
    },
    "schemas": [
        "urn:pingidentity:scim:api:messages:2.0:TelephonyValidationRequest"
    ],
    "validated": true,
    "validatedAt": "2016-09-12T22:32:15.440Z"
}

The following example shows the response to a request that used an expired code:

HTTP/1.1 400 Bad Request
Content-Length: 143
Content-Type: application/scim+json
Date: Tue, 13 Sep 2016 00:55:11 GMT

{
    "detail": "The verification code has expired",
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "scimType": "invalidValue",
    "status": 400
}