The CONNECT phones API

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

POST

/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.

RequestShowHide
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 201ShowHide

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 400ShowHide
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 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
The CONNECT ID can’t be found.

Headers
```
Content-Type: text/html
```
Response 409ShowHide

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 500ShowHide
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

GET

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Response 200ShowHide

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 401ShowHide

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 404ShowHide
The CONNECT ID can’t be found. Note that the MIME type returned will be text/html.

Headers
```
Content-Type: text/html
```
Response 500ShowHide
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

GET

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Bearer <access token>

Response 200ShowHide

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 401ShowHide

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 404ShowHide
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 503ShowHide
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

DELETE

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Basic <Base64 encoding of username:password>

Response 204ShowHide
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 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
The CONNECT ID used in the request is unknown. Note that the MIME type returned is text/html

Headers
```
Content-Type: text/html
```
Response 500ShowHide
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

POST

/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.

RequestShowHide

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 200ShowHide
Headers
```
Content-Type: application/json
```
Response 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
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 503ShowHide
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

POST

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Basic <Base64 encoding of username:password>

Response 200ShowHide
Phone verification flag is successfully set.

Headers
```
Content-Type: application/json
```
Response 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
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 500ShowHide
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

POST

/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.

RequestShowHide

Headers

Accept: application/json
Authorization: Basic <Base64 encoding of username:password>

Response 200ShowHide
Phone verification flag is successfully set.

Headers
```
Content-Type: application/json
```
Response 401ShowHide

Headers

Content-Type: text/html
WWW-Authenticate: Basic realm="Sylfide API"

Response 404ShowHide
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 500ShowHide
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>,"
}
```