Communication Channels API

API for accessing users' email addresses, SMS phone numbers, Twitter, and Facebook communication channels.

In this API, the :user_id parameter can always be replaced with self if the requesting user is asking for his/her own information.

A Communication Channel object looks like:

{
  // The ID of the communication channel.
  "id": 16,

  // The address, or path, of the communication channel.
  "address": "sheldon@caltech.example.com",

  // The type of communcation channel being described. Possible values
  // are: "email", "sms", "chat", "facebook" or "twitter". This field
  // determines the type of value seen in "address".
  "type": "email",

  // The position of this communication channel relative to the user's
  // other channels when they are ordered.
  "position": 1,

  // The ID of the user that owns this communication channel.
  "user_id": 1,

  // The current state of the communication channel. Possible values are:
  // "unconfirmed" or "active".
  "workflow_state": "active"
}

List user communication channels CommunicationChannelsController#index

GET /api/v1/users/:user_id/communication_channels

Returns a list of communication channels for the specified user, sorted by position.

Example Request:

curl https://<canvas>/api/v1/users/12345/communication_channels \ 
     -H 'Authorization: Bearer <token>'
Returns a list of Communication Channels

Create a communication channel CommunicationChannelsController#create

POST /api/v1/users/:user_id/communication_channels

Creates a new communication channel for the specified user.

Request Parameters:

  • communication_channel[address]

    An email address or SMS number.

  • communication_channel[type]
    email|sms

    The type of communication channel.

  • skip_confirmation
    Optional

    Only valid for site admins making requests; If '1', the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.

Example Request:

curl https://<canvas>/api/v1/users/1/communication_channels \ 
     -H 'Authorization: Bearer <token>' \ 
     -d 'communication_channel[address]=new@example.com' \ 
     -d 'communication_channel[type]=email' \
Returns a Communication Channel

Delete a communication channel CommunicationChannelsController#destroy

DELETE /api/v1/users/:user_id/communication_channels/:id

Delete an existing communication channel.

Example Request:

curl https://<canvas>/api/v1/users/5/communication_channels/3
     -H 'Authorization: Bearer <token>
     -X DELETE
Returns a Communication Channel