A CONNECT user might have zero or more phones linked to their account and can use the phone to authenticate. A phone can be in two states: verified and unverified. When a phone is in the verified state we know that the CONNECT user has access to the phone. A phone is considered verified when the CONNECT user has either used the phone to log in (and confirmed ownership through the authentication PIN sent to the phone) or simply by entering a verification PIN sent to the phone. The phone will then be set to verified for a while until it must be re-verified.

Phones 

Phone collection resource 

The phone collection contains all of the user’s phones, both verified and unverified.

Create new phone
/id/users/{connectId}/phones

Add a new phone to the CONNECT user identified by connectId. If you set the verified flag to true the phone will be verified without a need for an SMS round-trip. It is highly recommended that you let the CONNECT users themselves manage this through the My CONNECT account client (at https://connect.telenordigital.com/gui/mypage)

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

  • Request
  • Only the number field is required, all others are optional. Note that the type field isn’t used for anything but informational purposes. The phone number must be given in an international dialling format (E.164), ie <country code><phone number> without a plus sign (e.g. 4791231231)

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
        "number": "<phone number>",
        "priority": 0,
        "verified": false,
        "verificationCode": ""
        "type": "mobile phone type",
    }
  • Response  201
  • The phone has been created and the new phone is returned. Its initial state will be unverified unless the verified field was set in the request. Note that you have to initiate the SMS verification manually if the CONNECT user should receive a verification SMS.

    Headers
    Content-Type: application/json
    Body
    {
      "href": "https://api.telenor.io/id/users/588/phones/596",
      "id": "596",
      "generation": 597,
      "number": "4791231231",
      "priority": 0,
      "verified": false,
      "verificationCode": "",
      "type": "",
      "link": [
        {
          "rel": "self",
          "href": "/id/users/588/phones/596",
          "type": null,
          "idref": null
        },
        {
          "rel": "user",
          "href": "/id/users/588/",
          "type": null,
          "idref": null
        },
        {
          "rel": "sendsms",
          "href": "/id/users/588/phones/596/sendsms",
          "type": "action",
          "idref": null
        },
        {
          "rel": "verify",
          "href": "/id/users/588/phones/596/verify",
          "type": "action",
          "idref": null
        },
        {
          "rel": "deverify",
          "href": "/id/users/588/phones/596/deverify",
          "type": "action",
          "idref": null
        }
      ]
    }
  • Response  400
  • The phone number is invalid. Ensure that the phone number is properly formatted and contains a valid country code.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 400,
      "errorMessage": "Phone number <number> is not a valid number."
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The CONNECT ID can’t be found.

    Headers
    Content-Type: text/html
  • Response  409
  • The phone number is in use by another CONNECT user.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 409,
      "errorMessage": "Phone number <number> is already in use."
    }
  • Response  500
  • An internal error has occurred when creating the phone. Try again in a while and if the error persists please let us know. Note that you might get this return code if you forget to include a request body as well.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "<error message>"
    }
Get all phones
/id/users/{connectId}/phones

Retrieve a list of all phones stored on a CONNECT user.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.phone.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • The response contains an array of phones named phone containing all of the phones on the CONNECT account, both verified and unverified. Note that there are no uniqueness constraints on the priority field so there might be more than one phone with the same priority.

    Headers
    Content-Type: application/json
    Body
    {
      "phone": [
        {
          "href": "/id/users/588/phones/596",
          "id": "596",
          "generation": 597,
          "number": "4791231231",
          "priority": 0,
          "verified": false,
          "verificationCode": "",
          "type": "",
          "link": [
            {
              "rel": "self",
              "href": "/id/users/588/phones/596",
              "type": null,
              "idref": null
            },
            {
              "rel": "user",
              "href": "/id/users/588/",
              "type": null,
              "idref": null
            },
            {
              "rel": "sendsms",
              "href": "/id/users/588/phones/596/sendsms",
              "type": "action",
              "idref": null
            },
            {
              "rel": "verify",
              "href": "/id/users/588/phones/596/verify",
              "type": "action",
              "idref": null
            },
            {
              "rel": "deverify",
              "href": "/id/users/588/phones/596/deverify",
              "type": "action",
              "idref": null
            }
          ]
        }
      ]
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404
  • The CONNECT ID can’t be found. Note that the MIME type returned will be text/html.

    Headers
    Content-Type: text/html
  • Response  500
  • There was an error querying for the given CONNECT ID and/or phones. Retry the request in a while and if the error persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "<error message>"
    }

Phone resource 

Retrieve phone
/id/users/{connectId}/phones/{phoneId}

Retrieve a single phone.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.phone.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    phoneId
    string (required) 

    The ID of the phone.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • The returned data structure contains the following fields

    • id: The ID of the phone.

    • generation: The phone generation. This will change if the phone is updated.

    • number: The phone number

    • priority: The priority. Lower numbers are preferred.

    • verified: Verification flag. Set to true if the CONNECT user has verified the phone through an SMS round-trip.

    • verificationCode: The verification code. This field is not currently in use.

    • type: The type of mobile phone. Used for informational purposes only.

    • link: An array of links to related resources.

    Headers
    Content-Type: application/json
    Body
    {
      "href": "/id/users/588/phones/596",
      "id": "596",
      "generation": 597,
      "number": "4791231231",
      "priority": 0,
      "verified": false,
      "verificationCode": "",
      "type": "",
      "link": [
        {
          "rel": "self",
          "href": "/id/users/588/phones/596",
          "type": null,
          "idref": null
        },
        {
          "rel": "user",
          "href": "/id/users/588/",
          "type": null,
          "idref": null
        },
        {
          "rel": "sendsms",
          "href": "/id/users/588/phones/596/sendsms",
          "type": "action",
          "idref": null
        },
        {
          "rel": "verify",
          "href": "/id/users/588/phones/596/verify",
          "type": "action",
          "idref": null
        },
        {
          "rel": "deverify",
          "href": "/id/users/588/phones/596/deverify",
          "type": "action",
          "idref": null
        }
      ]
    }
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404
  • Then CONNECT ID or phone can’t be found. Note that the MIME type of the response is text/html.

    Headers
    Content-Type: text/html
  • Response  503
  • There was an error retrieving the phone and/or the CONNECT user. Retry the request in a while and if it persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "<error message>"
    }
Remove phone
/id/users/{connectId}/phones/{phoneId}

Remove a phone stored on the CONNECT user.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    phoneId
    string (required) 

    The ID of the phone.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204
  • The phone has been removed from the CONNECT user. Note that you’ll get this response regardless if the phone exists or not.

    Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The CONNECT ID used in the request is unknown. Note that the MIME type returned is text/html

    Headers
    Content-Type: text/html
  • Response  500
  • There was an error removing the phone and/or retrieving the CONNECT user. Retry the request in a while and if it persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "<error message>"
    }

SMS PIN code 

Send PIN code
/id/users/{connectId}/phones/{phoneId}/sendsms

Trigger an SMS round-trip to the CONNECT user. Note that this only triggers sending of the SMS and the CONNECT user won’t necessarily get any guidance in the SMS on how to verify the SMS.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    phoneId
    string (required) 

    The ID for this phone.

  • Request
  • Any locale specified in locale can pe passed in the body.

    Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
      "locale": "nb_NO"
    }
  • Response  200
  • Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The CONNECT user or phone can’t be found. Note that the MIME type in the response is text/html.

    Headers
    Content-Type: text/html
  • Response  503
  • The SMS service is unavailable at the moment. Retry the operation in a while and if the problem persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 503,
      "errorMessage": "PIN generation call failed."
    }

Verify 

Verify phone
/id/users/{connectId}/phones/{phoneId}/verify

Set the verified flag for a phone to true.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    phoneId
    string (required) 

    The ID of the phone.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  200
  • Phone verification flag is successfully set.

    Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The phone or the CONNECT ID cannot be found. Note that the MIME type for the returned document is text/html.

    Headers
    Content-Type: text/html
  • Response  500
  • As the error message says, something went wrong when updating the verified flag on the phone. Retry the operation in a while and if the problem persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "Something went wrong verifying phone <phone> on userId <connect id>,"
    }

Remove verification 

Remove verification from phone
/id/users/{connectId}/phones/{phoneId}/deverify

Set the verified flag for a phone to false.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    phoneId
    string (required) 

    The ID for this phone.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  200
  • Phone verification flag is successfully set.

    Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404
  • The phone or the CONNECT ID cannot be found. Note that the MIME type for the returned document is text/html.

    Headers
    Content-Type: text/html
  • Response  500
  • As the error message says, something went wrong when updating the verified flag on the phone. Retry the operation in a while and if the problem persists please let us know.

    Headers
    Content-Type: application/json
    Body
    {
      "errorCode": 500,
      "errorMessage": "Something went wrong verifying phone <phone> on userId <connect id>,"
    }

© 2017 Telenor Digital AS