RESTful API

Phone List Guidelines

Generally when sending blasts you will need to create a recipient list. This recipient list its a file that contains the detailed information for each recipient. The file could also contain additional parameters for each recipient. Parameters can help to customize information.

We have different file format depending on each case.

Previous Versions

Tag 5.3.52

List Name

The subscription lists have a name, which is useful to identify them easily when using them. The use of any string of characters is allowed as long as it meets the following conditions:

  • Blank names are not allowed.
  • The following characters are not allowed: / : < > &
  • The number of characters must be less than or equal to 200.

Basic CSV Recipient List


This CSV file has only a single column with the recipient mobile number.

Expected File's columns, if not listed it doesn't exist:

  1. Mobile Number

CSV Sample

"13056708084"
"18133210984"

Recipient List With Parameters


Based on Basic CSV file this file adds optional parameters to store additional information per recipient.

You can use CSV or Excel format to build this file.

Expected File's columns

  1. Mobile Number
  2. Parameter 1 {0}
  3. Parameter 2 {1}
  4. Parameter 3 {2}
  5. …

CSV Sample

"13056708084","jane","doe"
"18133210984","john","doe"

Parameters mechanism:
You may include placeholders in your message's content using {#} notation (# its a real number starting in 0), if you include them, they will be replaced for the respective column's content starting from the 2nd column in this case.

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B C
13056708084 jane doe
18133210984 john doe


SMSs Recipient List


The first 6 columns of this file are mandatory. Starting on the 7th column will be optional and must be related with the content of your message.

You can use CSV or Excel format to build this file.

Expected File's columns, if not listed it doesn't exist:

  1. Recipient's Mobile Number
  2. From
  3. Carrier Name
  4. Text
  5. Encoding Default UTF-8
  6. Timezone
  7. Parameter 1 {0}
  8. Parameter 2 {1}
  9. Parameter 3 {2}
  10. …

CSV Sample

"13056708084","19893653744","CarrierName","UTF-8","America/New_York","Hi {0}. Welcome to {1}","Matt Ford","this test"
"18133210984","19893653744","CarrierName","UTF-8","America/New_York","Hi {0}. Welcome to {1}","Ed Harris","this test"

Parameters mechanism:
You may include placeholders in your message's content using {#} notation (# its a real number starting in 0), if you include them, they will be replaced for the respective column's content starting from the 7th column in this case.

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B C D E F G H
13056708084 19893653744 CarrierName UTF-8 America/New_York Hi {0}. Welcome to {1} Matt Ford this test
18133210984 19893653744 CarrierName UTF-8 America/New_York Hi {0}. Welcome to {1} Ed Harris this test


SMSs Recipient List (simple)


Two single columns that define the recipient and the text message to send.

You can use CSV or Excel format to build this file.

Expected File's columns, if not listed it doesn't exist:

  1. Recipient's Mobile Number
  2. Text

CSV Sample

"13056708084","Text message for user 13056708084"
"18133210984","Text message for user 18133210984"

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B
13056708084 Text message for user 13056708084
18133210984 Text message for user 18133210984

SMSs Recipient JSON


Similar to the SMSs recipient files this will include the mobilenumber and the text for each recipient

Expected tags, if not listed it doesn't exist:

  1. mobilenumber: Recipient's Mobile Number
  2. text: The text to be sent to the recipient

JSON Sample

[
{"mobilenumber":"00000000","text":"Test1 createBroadcastFromJson"},
{"mobilenumber":"00000001","text":"Test2 createBroadcastFromJson"}
]


Email Recipient List


The first column of this file is mandatory. Starting on the 2nd column will be optional and must be related with the content of your message.

You can use CSV or Excel format to build this file.

Expected File's columns, if not listed it doesn't exist:

  1. Recipient's email address
  2. Parameter 1 {0}
  3. Parameter 2 {1}
  4. Parameter 3 {2}
  5. …

CSV Sample

"matt_ford@ogangi.com","Matt Ford","April"
"ed_harris@ogangi.com","Ed Harris","March"

Parameters mechanism:
You may include placeholders in your message's content using {#} notation (# its a real number starting in 0), if you include them, they will be replaced for the respective column's content starting from the 7th column in this case.

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B C
matt_ford@ogangi.com Matt Ford April
ed_harris@ogangi.com Ed Harris March

Recipient List (with variables)

The first column of this file is mandatory. Starting on the 2nd column will be optional and must be related with the content of your message.

You can use CSV or Excel format to build this file.

Expected File's columns, if not listed it doesn't exist:

  1. Mobile number
  2. Parameter 1 {0}
  3. Parameter 2 {1}
  4. Parameter 3 {2}
  5. …

CSV Sample

"13056708084","Matt Ford","April"
"18133210984","Ed Harris","March"

Parameters mechanism:
You may include placeholders in your message's content using {#} notation (# its a real number starting in 0), if you include them, they will be replaced for the respective column's content starting from the 7th column in this case.

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B C
13056708084 Matt Ford April
18133210984 Ed Harris March

Segmented Recipient List

All parameters on the file are optional, the only mandatory parameter is the recipient and it has to be at the first column

You can use CSV or Excel format to build this file. Both cases requires a header row at the beginning

Expected File's columns, if not listed it doesn't exist:

  1. Mobile Number
  2. Parameter 1 {0}
  3. Parameter 2 {1}
  4. Parameter 3 {2}
  5. …

CSV Sample

"customer_phone_num","name","city"
"13056708084","jane","New York"
"18133210984","john","New York"

Please read the File structure to learn more about this.

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B C
customer_phone_num name city
13056708084 jane New York
18133210984 john New York

Black List (Add Users)

This CSV file has three single columns per register

Expected File's columns, if not listed it doesn't exist:

  1. Mobile Number
  2. Black List Type
  3. Comment

CSV Sample

"13053456781","1","comment 1"
"13053456782","2","other comment"
"13053456783","3","more comment"

Black List (Delete Users)

This CSV file has a single column per register

Expected File's columns, if not listed it doesn't exist:

  1. Mobile Number

CSV Sample

"13053456781"
"13053456782"
"13053456783"

OWNCODE Recipient List

Two single columns that define the recipient and the text message to send.

You can use CSV or Excel format to build this file.

Expected File's columns, if not listed it doesn't exist:

  1. Recipient's Mobile Number
  2. Text to send

CSV Sample

"13056708084","Text message for user 13056708084"
"18133210984","Text message for user 18133210984"

Excel Sample

Note that instead of using double quotes to indicate text fields you have to change the column format to text using excel.

A B
13056708084 Text message for user 13056708084
18133210984 Text message for user 18133210984