Subscribers

A subscriber is an individual with a phone number and a language (if known), who can receive calls or SMS messages depending on their preferences. You can track the history of all calls and messages received by a subscriber.

Create Subscriber

Method: POST

URL: https://go.votomobile.org/api/v1/subscribers

Parameters:

  • api_key
  • phone: phone number of subscriber in local or international format
  • receive_voice (optional): set to 1 as true if the subscriber should receive voice content [default: 1]
  • receive_sms (optional): set to 1 as true if the subscriber should receive sms content [default: 0]
  • starting_date (optional): starting date in 2013-09-27 format; used in creating relative dates for the subscriber’s “routine” schedule [default: current date]
  • groups (optional): comma-separated list of group ids to which the subscriber will be added [default: none]
  • active (optional : 1 for active and 0 for inactive) : subscriber should be set to receive Outgoing Calls [defaut: true]
  • preferred_language (optional) : id of subscriber’s preferred language [default : not set – will prompt using language selector if provided]
  • property[name_of_property]: set the values of custom fields. Custom fields can be created via the VOTO app.

Note: Support for name, location and comments:

name, location, comments can now be set using the property[name_of_property] sytnax, i.e: property[name] for name, property[location] for location and property[comments] for comments

Returns: id of new subscriber

{"status":200,"message":"Subscriber Created","data":{id: 430}}

Parameters For Creating Bulk Subscribers

These parameters can be posted together with the above parameters (api_key is compulsary) to create anonymous subscribers with only phone number(s) ( with options: specify content to receive, and specify a group to add to immediately. Option to control what happens if the phone number already exists: ignore, just add to group, or create duplicate).

  • phone_numbers : In this case, provide a comma-separated list of phone numbers to create multiple subscribers. You can provide a single phone number as well. Example; 12232434343,+2343242343,4545645646
  • if_phone_number_exists: { “skip”, “create_duplicate”, “add_to_groups_only” } [Default if not provided: create_duplicate]

Returns: an array of subscriber ids {“status”:200,”message”:”Subscriber(s) Created Successfully”,”data”:{[181,182,183,184,185]}}

List Subscribers

Method: GET

URL: https://go.votomobile.org/api/v1/subscribers

Parameters:

  • api_key
  • limit (optional): Specify the pagination limit for number of results to return on one page [max: 500]. You can follow the URLs given for nextURL and previousURL in the ‘pagination’ section of the response to navigate through pages.

Returns:

{
  "status": 200,
  "code": 1001,
  "data": {
      "subscribers": [
          {
              "id": "373648",
              "receive_sms": "0",
              "receive_voice": "1",
              "receive_data": "0",
              "receive_ussd": "0",
              "phone": "233264164182",
              "active": "1",
              "start_date": "2014-09-10",
              "language_id": "200247",
              "is_test_subscriber": "0",
              "group_ids": "201031, 201409, 204128, 204129, 204130, 204131, 204132, 204133, 204134, 204135, 204136, 204137",
              "properties": {
                  "name": "Kodjo Antwi",
                  "location": "Ejisu",
                  "comments": "Out flying kites"
              }
          },
          {
              "id": "376089",
              "receive_sms": "1",
              "receive_voice": "0",
              "receive_data": "0",
              "receive_ussd": "0",
              "phone": "233230762734",
              "active": "0",
              "start_date": "2014-03-17",
              "language_id": "200247",
              "is_test_subscriber": "0",
              "group_ids": "201409",
              "properties": {
                  "name": "Ekua",
                  "location": "",
                  "comments": ""
              }
          }
      ]
  },
  "message": "Subscribers fetched successfully",
  "more_info": "",
  "pagination": {
      "nextURL": "https://go.votomobile.org/api/v1/subscribers?limit=2&page_after=376089",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/subscribers?limit=2"
}

List Subscribers in a Group

Method: GET

URL: https://go.votomobile.org/api/v1/subscribers/groups/[group_id]

Parameters:

  • api_key

Returns:

{
  "status": 200,
  "code": 1001,
  "data": {
      "subscribers": [
          {
              "id": "373648",
              "receive_sms": "0",
              "receive_voice": "1",
              "receive_data": "0",
              "receive_ussd": "0",
              "phone": "233264164182",
              "active": "1",
              "start_date": "2014-09-10",
              "language_id": "200247",
              "is_test_subscriber": "0",
              "group_ids": "201409",
              "properties": {
                  "name": "Kodjo Antwi",
                  "location": "Ejisu",
                  "comments": "Out flying kites"
              }
          },
          {
              "id": "376089",
              "receive_sms": "1",
              "receive_voice": "0",
              "receive_data": "0",
              "receive_ussd": "0",
              "phone": "233230762734",
              "active": "0",
              "start_date": "2014-03-17",
              "language_id": "200247",
              "is_test_subscriber": "0",
              "group_ids": "201409",
              "properties": {
                  "name": "Ekua",
                  "location": "",
                  "comments": ""
              }
          }
      ]
  },
  "message": "Subscribers in Group 201409 fetched successfully",
  "more_info": "",
  "pagination": {
      "nextURL": "null",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/subscribers/groups/201409"
}

List Subscriber Details

Method: GET

URL: https://go.votomobile.org/api/v1/subscribers/[subscriber_id]

Parameters:

  • api_key

Returns:

{"status":200,
"message":"Subscriber Details",
data:{
     subscriber :
     {
        "id": "33105",
        "receive_sms": "1",
        "receive_voice": "1",
        "receive_data": "0",
        "receive_ussd": "0",
        "phone": "255754280903",
        "active": "1",
        "start_date": "2015-11-13",
        "language_id": "200715",
        "is_test_subscriber": "0",
        "group_ids": "31,32",
        "properties":{
            "name_of_custom_property": "value",
            "name": "Firstname Othernames",
            "location": "Someplace",
            "comments": "This is a comment",
        }
    }
  }
}

Modify Subscriber Details

Method: PUT

URL: https://go.votomobile.org/api/v1/subscribers/[subscriber_id]

Parameters: Specify only subscriber parameters to be changed.

Tip

All subscriber properties that can be created can also be modified.

  • api_key
  • phone (optional): phone number of subscriber in local or international format
  • starting_date (optional): starting date in 2013-09-27 format; used in creating relative dates for the subscriber’s “routine” schedule
  • groups (optional): comma-separated list of group ids; if provided, the subscriber will be set to belong to only these groups
  • active (optional : 1 for active and 0 for inactive) : subscriber should be set to receive Outgoing Calls. [defaut: true]
  • property[name_of_property]: set the values of custom fields. Custom fields can be created via the VOTO app.

Note: Support for name, location and comments:

name, location, comments can now be set using the property[name_of_property] sytnax, i.e: property[name] for name, property[location] for location and property[comments] for comments

Returns:

{"status":200,"message":"Subscriber Modified","data":{id:2}}

Delete Subscriber

Method: DELETE

URL: https://go.votomobile.org/api/v1/subscribers/[subscriber_id]

Parameters: Specify subscriber id to delete

  • api_key

Returns:

{"status":200,"data":null,"message":"Succesfully deleted subscriber"}