~~NOTOC~~

//[[restapi:start|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 =====
<wrap button>[[restapi:appx_phonelist_5_3_52|Tag 5.3.52]]</wrap>


===== 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 =====

<WRAP group>

<WRAP half column>

\\ 

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

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number

</WRAP>

</WRAP>

</WRAP>

==== CSV Sample ====

<code>
"13056708084"
"18133210984"
</code>

===== Recipient List With Parameters =====

<WRAP group>

<WRAP half column>

\\ 
Based on [[restapi:appx_phonelist#basic_csv_recipient_list|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.

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns

  - Mobile Number
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"13056708084","jane","doe"
"18133210984","john","doe"
</code>

<WRAP round tip>
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.
</WRAP>

==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

<WRAP half>
^  A  ^  B  ^  C  ^
| @white:13056708084 | @white:jane | @white:doe | 
| @white:18133210984 | @white:john | @white:doe |
</WRAP>

\\ 
===== SMSs Recipient List =====

<WRAP group>

<WRAP half column>

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

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's Mobile Number
  - From
  - Carrier Name
  - Text
  - Encoding  //Default UTF-8//
  - Timezone
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"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"
</code>

<WRAP round tip>
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.
</WRAP>
==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

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

\\ 
===== SMSs Recipient List (simple) =====

<WRAP group>

<WRAP half column>

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

You can use CSV or Excel format to build this file.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's Mobile Number
  - Text

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"13056708084","Text message for user 13056708084"
"18133210984","Text message for user 18133210984"
</code>


==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

^  A  ^  B  ^
| @white:13056708084 | @white:Text message for user 13056708084 | 
| @white:18133210984 | @white:Text message for user 18133210984 |

===== SMSs Recipient JSON =====

<WRAP group>

<WRAP half column>

\\ 
Similar to the SMSs recipient files this will include the mobilenumber and the text for each recipient
</WRAP>

<WRAP half column>

<WRAP round info>Expected tags, //if not listed it doesn't exist//: 

  - mobilenumber: Recipient's Mobile Number
  - text: The text to be sent to the recipient

</WRAP>

</WRAP>

</WRAP>
==== JSON Sample ====

<code>
[
{"mobilenumber":"00000000","text":"Test1 createBroadcastFromJson"},
{"mobilenumber":"00000001","text":"Test2 createBroadcastFromJson"}
]
</code>

\\

===== Email Recipient List =====

<WRAP group>

<WRAP half column>

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

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Recipient's email address
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"matt_ford@ogangi.com","Matt Ford","April"
"ed_harris@ogangi.com","Ed Harris","March"
</code>

<WRAP round tip>
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.
</WRAP>
==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

^  A  ^  B  ^  C  ^
| @white:matt_ford@ogangi.com | @white:Matt Ford | @white:April |
| @white:ed_harris@ogangi.com | @white:Ed Harris | @white:March |

===== Recipient List (with variables) =====

<WRAP group>

<WRAP half column>
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.
</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile number
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"13056708084","Matt Ford","April"
"18133210984","Ed Harris","March"
</code>

<WRAP round tip>
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.
</WRAP>
==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

^  A  ^  B  ^  C  ^
| 13056708084 | @white:Matt Ford | @white:April |
| 18133210984 | @white:Ed Harris | @white:March |

===== Segmented Recipient List =====

<WRAP group>

<WRAP half column>

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 

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number
  - Parameter 1  //{0}//
  - Parameter 2  //{1}//
  - Parameter 3  //{2}//
  - ...

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"customer_phone_num","name","city"
"13056708084","jane","New York"
"18133210984","john","New York"
</code>

<WRAP round tip>
Please read the [[:file_structure|File structure]] to learn more about this.
</WRAP>

==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

<WRAP half>
^  A  ^  B  ^  C  ^
| @white:customer_phone_num | @white:name | @white:city | 
| @white:13056708084 | @white:jane | @white:New York | 
| @white:18133210984 | @white:john | @white:New York |
</WRAP>

===== Black List (Add Users)=====

<WRAP group>

<WRAP half column>
 
This CSV file has three single columns per register

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number
  - Black List Type
  - Comment

</WRAP>

</WRAP>

</WRAP>

==== CSV Sample ====

<code>
"13053456781","1","comment 1"
"13053456782","2","other comment"
"13053456783","3","more comment"
</code>

===== Black List (Delete Users)=====

<WRAP group>

<WRAP half column>

This CSV file has a single column per register

</WRAP>

<WRAP half column>

<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 

  - Mobile Number

</WRAP>

</WRAP>

</WRAP>
==== CSV Sample ====

<code>
"13053456781"
"13053456782"
"13053456783"
</code>

===== OWNCODE Recipient List =====

<WRAP group>
<WRAP half column>
Two single columns that define the recipient and the text message to send.

You can use CSV or Excel format to build this file.
</WRAP>

<WRAP half column>
<WRAP round info>Expected File's columns, //if not listed it doesn't exist//: 
  - Recipient's Mobile Number
  - Text to send
</WRAP>
</WRAP>
</WRAP>

==== CSV Sample ====

<code>
"13056708084","Text message for user 13056708084"
"18133210984","Text message for user 18133210984"
</code>

==== Excel Sample ====

Note that instead of using double quotes to indicate text fields you have to [[https://support.office.com/en-us/article/Format-a-date-the-way-you-want-8e10019e-d5d8-47a1-ba95-db95123d273e#__toc320186182|change the column format to text]] using excel.

^  A  ^  B  ^
| @white:13056708084 | @white:Text message for user 13056708084 | 
| @white:18133210984 | @white:Text message for user 18133210984 |