To obtain your TopicaPlusSM API account info, please contact your TopicaPlusSM Customer Success Manager, or email us at cs@get.topica.com. You can also call 415-344-0800.
API Documentation
Overview
This documentation will explain how to interact with the TopicaPlusSM API. All calls use this basic structure:
{
"topicaAction" : {
"account" : "your_user",
"password" : "your_pass",
"API_CALL_NAME" : [
{
API JSON CALL BODY
}
]
}
}Below you will find details of each API call and the JSON fields needed to make the call. All calls should be a POST to the URL:
http://app.topicaplus.com/api/Dispatcher/
System Health
Echo Test
This API call allows you to check and see if the server is up.
| Field | Value |
|---|---|
| serverPing | empty |
{
"topicaReply" : {
"status" : "OK"
}
}
List Management
listCreate
This API call allows you to create a new mailing list
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| display | 0 |
| list | Desired name of your mailing list |
{
"topicaReply" : {
"status" : "OK",
"result" : [
{
"status" : "OK",
"list" : "your_first_list"
}
]
}
}
listRemove
This API call allows you to create a mailing list
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| list | Mailing list that you would like to delete |
{
"topicaAction" : {
"username" : "your_user",
"password" : "your_pass",
"listRemove" : [
{
"list" : "your_first_list"
}
]
}
}
listDetail
This API call allows you to create a mailing list
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| list | Mailing list that you would like to get details of |
{
"topicaReply" : {
"status" : "OK",
"result" : [
{
"status" : "OK",
"listid" : "1049",
"listname" : "your list name",
"account" : "your account name"
}
]
}
}
Subscriber Management
subscriberAdd
This API call allows you to add a new subscriber, email address only
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| display | 0 |
| list | Mailing list you would like to add this these subcribers to |
| content | Email addresses that you would like to add seperated by commas |
{
"topicaAction" : {
"username" : "your_user",
"password" : "your_pass",
"subscriberAdd" : {
"list" : "List you are adding to",
"data" : {
"source" : "inline",
"content" : [
"first-user@example.com",
"second-user@example.com",
"third-user@example.com"
]
}
}
}
}
subscriberRemove
This API call allows you to create a mailing list
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| list | Mailing list that you would like to remove the subscribers from |
| addresses | Email addresses that you would like to remove |
{
"topicaReply" : {
"status" : "OK",
"result" : [
{
"email" : "user+3@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+2@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+12@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+15@get.topica.com",
"status" : "NOT_SUBSCRIBED"
},
{
"email" : "user+13@get.topica.com",
"status" : "NOT_SUBSCRIBED"
},
{
"email" : "user+14@get.topica.com",
"status" : "NOT_SUBSCRIBED"
}
]
}
}
subscriberBlock
This API call allows you to create a mailing list
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| list | Mailing list that you would like to get details of |
| addresses | Email addresses that you would like to block |
{
"topicaReply" : {
"status" : "OK",
"result" : [
{
"email" : "user+3@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+2@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+12@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+15@get.topica.com",
"status" : "NOT_SUBSCRIBED"
},
{
"email" : "user+13@get.topica.com",
"status" : "NOT_SUBSCRIBED"
},
{
"email" : "user+14@get.topica.com",
"status" : "NOT_SUBSCRIBED"
}
]
}
}
subscriberStatus
This API call allows you to check the status of a subscriber.
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| addresses | Email addresses that you would like to check the statuses of |
{
"topicaReply" : {
"status" : "OK",
"result" : [
{
"email" : "user+3@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+2@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+12@get.topica.com",
"status" : "UNSUBSCRIBED"
},
{
"email" : "user+15@get.topica.com",
"status" : "NOT_SUBSCRIBED"
},
{
"email" : "user+13@get.topica.com",
"status" : "NOT_SUBSCRIBED"
},
{
"email" : "user+14@get.topica.com",
"status" : "NOT_SUBSCRIBED"
}
]
}
}
subscriberCount
This API call allows you to check the total number of subscribers you have.
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
{
"topicaReply" : {
"status" : "OK",
"result" : [
{
"status" : "OK",
"bid" : "NZ/57",
"count" : "42",
"username" : "Mrs.Beasley"
}
]
}
}
subscriberImport
This API call allows you to bulk import subscribers with demographic details.
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| column-delimiter | , |
| value-delimeter | ; |
| first-row | header or data |
| send-confirmations | true or false |
| mapping | Import file column mapping to user fields. |
| data | Submission data. |
Example
{
"topicaAction" : {
"subscriberImport" : {
"column-delimiter" : ",",
"mapping" : {
"column" : [
{
"order" : 1,
"data-type" : "text",
"field" : "Email"
},
{
"order" : 2,
"category-values" : {
"map" : [
{
"to" : "Yellow",
"from" : "y"
},
{
"to" : "Yellow",
"from" : "yellow"
},
{
"to" : "Black",
"from" : "b"
}
],
"convert-case" : "false",
"value" : []
},
"data-type" : "multi",
"field" : "color"
},
{
"order" : 3,
"data-type" : "text",
"field" : "Address Line 1"
},
{
"order" : 4,
"data-type" : "text",
"field" : "Address Line 2"
},
{
"order" : 5,
"data-type" : "text",
"field" : "City"
},
{
"order" : 6,
"data-type" : "text",
"field" : "State"
}
]
},
"data" : {
"source" : "inline",
"content" : "dXNlcisxMkBnZXQudG9waWNhLmNvbSx5ZWxsb3csMyBHcmFuZGUgQXZlLCBBcHQuICMzMixIYXJ0\nZm9yZCwgQ1QKdXNlcisxM0BnZXQudG9waWNhLmNvbSwsMzEyIE1hcmtldCwsQ2xldmVsYW5kLCBO\nZWJyYXNrYQp1c2VyKzE0QGdldC50b3BpY2EuY29tLHllbGxvdywgNCBCdXR0b24gTGFuZSxTdWl0\nZSA0MDQsU2VhdHRsZSwgV2FzaGluZ3Rvbgp1c2VyKzE1QGdldC50b3BpY2EuY29tLHllbGxvdywx\nIEJhYmJldCBEcml2ZSxBdHRuOiBEZWxpdmVyaWVzLFNhbiBGcmFuY2lzY28sIENBCnVzZXIrM0Bn\nZXQudG9waWNhLmNvbSxyZWQ7eWVsbG93LDMgRXN0ZWxsZSBTdC4sLFBvcnRsYW5kLCBWQQp1c2Vy\nKzJAZ2V0LnRvcGljYS5jb20scmVkO3ksMTIzMiBGdWxzb20sLEV1Z2VuZSwgVVQK\n",
"type" : "csv"
},
"first-row" : "data",
"value-delimiter" : ";",
"send-confirmations" : "false",
"duplicate" : "reject-duplicates",
"list" : "foo"
},
"username" : "topica-cli-test-000001"
}
}
Response
{
"topicaReply" : {
"status" : "OK",
}
}
subscriberExport
This API call allows you to bulk export data.
| Field | Value |
|---|---|
| account | Your Username |
| password | Your Password |
| list | The Mailing you want to export subscribers from. |
{
"topicaReply" : {
"status" : "OK",
"result" : {
"subscriber" : [
{
"field" : [
{
"content" : "",
"label" : "First Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Last Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Job Title",
"type" : "textfield"
},
{
"content" : "",
"label" : "Company Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Work Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Home Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 1",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 2",
"type" : "textfield"
},
{
"content" : "",
"label" : "City",
"type" : "textfield"
},
{
"content" : "",
"label" : "State",
"type" : "textfield"
},
{
"content" : "",
"label" : "Country",
"type" : "textfield"
},
{
"content" : "",
"label" : "ZIP",
"type" : "textarea"
},
{
"content" : "",
"label" : "Gender",
"type" : "textfield"
},
{
"content" : "",
"label" : "Group",
"type" : "textfield"
},
{
"content" : "",
"label" : "FROOGLE",
"type" : "textarea"
},
{
"option" : [
{
"checked" : "N",
"value" : "xxx and foo"
},
{
"checked" : "N",
"value" : "yyy and bar"
},
{
"checked" : "N",
"value" : "zzz and bam"
}
],
"label" : "STROOBLE",
"type" : "dropdown"
},
{
"option" : [
{
"checked" : "N",
"value" : "zz top"
},
{
"checked" : "N",
"value" : "ozzy"
},
{
"checked" : "N",
"value" : "nazareth"
}
],
"label" : "MOOFLE",
"type" : "checkbox"
},
{
"content" : "",
"label" : "Custom Field #6",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #7",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #8",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #9",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #10",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #11",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #12",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #13",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #14",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #15",
"type" : "textfield"
}
]
},
{
"field" : [
{
"content" : "WIN",
"label" : "First Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Last Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Job Title",
"type" : "textfield"
},
{
"content" : "",
"label" : "Company Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Work Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Home Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 1",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 2",
"type" : "textfield"
},
{
"content" : "",
"label" : "City",
"type" : "textfield"
},
{
"content" : "",
"label" : "State",
"type" : "textfield"
},
{
"content" : "",
"label" : "Country",
"type" : "textfield"
},
{
"content" : "",
"label" : "ZIP",
"type" : "textarea"
},
{
"content" : "",
"label" : "Gender",
"type" : "textfield"
},
{
"content" : "",
"label" : "Group",
"type" : "textfield"
},
{
"content" : "ccccc nnnnn",
"label" : "FROOGLE",
"type" : "textarea"
},
{
"option" : [
{
"checked" : "N",
"value" : "xxx and foo"
},
{
"checked" : "Y",
"value" : "yyy and bar"
},
{
"checked" : "N",
"value" : "zzz and bam"
}
],
"label" : "STROOBLE",
"type" : "dropdown"
},
{
"option" : [
{
"checked" : "Y",
"value" : "zz top"
},
{
"checked" : "N",
"value" : "ozzy"
},
{
"checked" : "Y",
"value" : "nazareth"
}
],
"label" : "MOOFLE",
"type" : "checkbox"
},
{
"content" : "",
"label" : "Custom Field #6",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #7",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #8",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #9",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #10",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #11",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #12",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #13",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #14",
"type" : "textfield"
},
{
"content" : "mmmmm",
"label" : "Custom Field #15",
"type" : "textfield"
}
]
},
{
"field" : [
{
"content" : "",
"label" : "First Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Last Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Job Title",
"type" : "textfield"
},
{
"content" : "",
"label" : "Company Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Work Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Home Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 1",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 2",
"type" : "textfield"
},
{
"content" : "",
"label" : "City",
"type" : "textfield"
},
{
"content" : "",
"label" : "State",
"type" : "textfield"
},
{
"content" : "",
"label" : "Country",
"type" : "textfield"
},
{
"content" : "",
"label" : "ZIP",
"type" : "textarea"
},
{
"content" : "",
"label" : "Gender",
"type" : "textfield"
},
{
"content" : "",
"label" : "Group",
"type" : "textfield"
},
{
"content" : "",
"label" : "FROOGLE",
"type" : "textarea"
},
{
"option" : [
{
"checked" : "N",
"value" : "xxx and foo"
},
{
"checked" : "N",
"value" : "yyy and bar"
},
{
"checked" : "N",
"value" : "zzz and bam"
}
],
"label" : "STROOBLE",
"type" : "dropdown"
},
{
"option" : [
{
"checked" : "N",
"value" : "zz top"
},
{
"checked" : "N",
"value" : "ozzy"
},
{
"checked" : "N",
"value" : "nazareth"
}
],
"label" : "MOOFLE",
"type" : "checkbox"
},
{
"content" : "",
"label" : "Custom Field #6",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #7",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #8",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #9",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #10",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #11",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #12",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #13",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #14",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #15",
"type" : "textfield"
}
]
},
{
"field" : [
{
"content" : "",
"label" : "First Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Last Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Job Title",
"type" : "textfield"
},
{
"content" : "",
"label" : "Company Name",
"type" : "textfield"
},
{
"content" : "",
"label" : "Work Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Home Phone",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 1",
"type" : "textfield"
},
{
"content" : "",
"label" : "Address Line 2",
"type" : "textfield"
},
{
"content" : "",
"label" : "City",
"type" : "textfield"
},
{
"content" : "",
"label" : "State",
"type" : "textfield"
},
{
"content" : "",
"label" : "Country",
"type" : "textfield"
},
{
"content" : "",
"label" : "ZIP",
"type" : "textarea"
},
{
"content" : "",
"label" : "Gender",
"type" : "textfield"
},
{
"content" : "",
"label" : "Group",
"type" : "textfield"
},
{
"content" : "",
"label" : "FROOGLE",
"type" : "textarea"
},
{
"option" : [
{
"checked" : "N",
"value" : "xxx and foo"
},
{
"checked" : "N",
"value" : "yyy and bar"
},
{
"checked" : "N",
"value" : "zzz and bam"
}
],
"label" : "STROOBLE",
"type" : "dropdown"
},
{
"option" : [
{
"checked" : "N",
"value" : "zz top"
},
{
"checked" : "N",
"value" : "ozzy"
},
{
"checked" : "N",
"value" : "nazareth"
}
],
"label" : "MOOFLE",
"type" : "checkbox"
},
{
"content" : "",
"label" : "Custom Field #6",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #7",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #8",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #9",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #10",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #11",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #12",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #13",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #14",
"type" : "textfield"
},
{
"content" : "",
"label" : "Custom Field #15",
"type" : "textfield"
}
]
}
]
}
}
}