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 YYYY-MM-DD 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[system_name_of_custom_field] (optional): set the values of custom property fields. To set a subscriber custom property value like ‘Name’, the custom property field must first be created via the VOTO app (https://go.votomobile.org/subscribers/manage). It can then be set via the API using the custom field’s system_name assgined on the platform. Our example would set the Name property this way, property[name] = 'Jane Doe'.

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"
}

Search Subscriber by phone number

Method: GET

URL: https://go.votomobile.org/api/v1/subscribers/search-phone

Parameters:

  • api_key
  • phone: subscriber phone number to search for
  • show_details (optional): get full details from the subscriber [default: false]

Returns:

{
  "status": 200,
  "code": 1001,
  "data": {
      "subscriber":
          {
              "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"
              }
          }
  }
}

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 YYYY-MM-DD 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]
  • preferred_language: Provide a numeric language_id to set the subscriber’s language. Submit as empty (“”) to set the subscriber’s language to unknown. (In this case, subscribers can be prompted for their language at the start of calls, if you’ve configured a language selector prompt.)
  • property[system_name_of_custom_field] (optional): set the values of custom property fields. To set a subscriber custom property value like ‘Work Phone’, the custom property field must first be created via the VOTO app (https://go.votomobile.org/subscribers/manage). It can then be set via the API using the custom field’s system_name assgined on the platform. Our example would set the Name property this way, property[work_phone] = '+2332345678900'.

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"}