To send a call with this API, you'll need to build a web form that references a JavaScript/jQuery library with the parameters listed below. We recommend putting the API key in a text file and storing it on your site's server. Because the API key must be passed in the call, we do not recommend passing these parameters in the URL. Use a library.
GET to /api/add_script_subscription
Due to the limited number of characters available with a HTTP GET request, the request elements are parameters abbreviated.
Parameters indicated by an asterisk (*) are required.
| t* | The topic code to assign subscriptions to. This parameter is also used to identify the account in which to create the subscriber profile. |
| c* | Required as part of the JSONP protocol. This is the name of the javascript callback method that wraps the JSON response. |
| k* | The account API key (this should be compressed). |
| e* | The primary email address for the subscriber. This is the only required subscriber address. |
| s | The secondary email address for the subscriber, if you have collected one. |
| w | The subscriber's wireless address (mobile phone number). This must be in the form of ten digits with no spaces or dashes between the numbers. |
| q_<id> |
This parameter contains the question ID and answer ID(s).
The format of this parameter depends on the type of response required for the question.
Answers for select one and multiple response are specific to a question and can be disabled. If answers are provided that do not correspond to the question or that are disabled, validation errors will occur. |
Below is an example HTML web page with form fields to collect subscriber information. This page references a javascript library that contains the parameters for this API method.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Subscriber API example using JSONP</title>
</head>
<body>
<h1>Example Subscriber API page</h1>
<fieldset>
<legend>Subscriber API</legend>
<ol class="form">
<form method="get" id="the_form" accept-charset="utf-8">
<input type='hidden' name='t', value='<TOPIC_CODE>'/>
<input type='hidden' name='a', value='1'/>
<li>
<label for="e">Primary Email: </label>
<input type="text" name="e" id="e">
</li>
<li>
<label for="w">Wireless: </label>
<input type="text" name="w" id="w">
</li>
<li>
<label for="<QUESTION_ID>">State: </label>
<select name="<QUESTION_ID>" id="<QUESTION_ID>">
<option value="<ANSWER_ID>">Maryland</option>
<option value="<ANSWER_ID>">Minnesota</option>
</select>
</li>
<p>
<input type="submit" value="Submit" id='submit'>
<div id='response' class='hidden'></div>
</p>
</form>
</ol>
</fieldset>
<script
src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> <!--
jquery -->
<script src="json2.js"></script> <!-- something to give you JSON parsing -->
<script src="script_api_script.js"></script> <!-- supporting javascript functions
-->
</body>
</html>
Below is an example of a javascript library containing the parameters for this API method.
$(document).ready(function(){
$('#the_form').submit(function() {
$("input[type=submit]").attr("disabled", "disabled");
$('#response').addClass('hidden');
var url = "https://stage-api.govdelivery.com/api/add_script_subscription";
var values = {};
$.each($('#the_form').serializeArray(), function(i, field) {
if (field.value.length > 0) {
values[field.name] = field.value;
};
});
switch(values["a"])
{
case "1":
values["k"]="Your API key";
break;
}
$.ajax({
url: url,
data: values,
dataType: "jsonp",
jsonp : "c",
jsonpCallback: "jsonpcallback"
});
return false;
});
});
// Named callback function from the ajax call when jsonpbtn2 clicked
function jsonpcallback(response) {
$("input[type=submit]").removeAttr("disabled");
$('#response').removeClass('hidden');
var text = JSON.stringify(response, null, ' ');
$('#response').html("<strong>" + response.message + "</strong><br/>" + text);
}
The JSONP response is a text response with the following format:
<callback>(<json response>)
This response indicates that one or more subscriber profiles were created and assigned to the requested topics. This response would also appear if the subscriber profiles already existed.
jsonpcallback({"topic_id":"ANTHRAX","message":"Subscriber profile successfully created.","citizen_id":19196})
The returned JSON response will be comprised of the following fields.
| citizen_id | This value will be returned if any subscriber profiles were created. It is possible for this value to be returned (indicating created subscriber profiles) within a validation error. For example, the primary subscriber may be created without problems, but the creation of the secondary profile fails due to topic restrictions. |
| topic_id | This value includes the code of the topic. If this field is present, the request successfully located the topic and met the security requirements regarding API Key and account settings. |
| This field will only appear if any errors are returned. It will contain an array of validation errors associated with the primary email address. | |
| secondary_email | This field will only appear if any errors are returned. It will contain an array of validation errors associated with the secondary email address. |
| wireless | This field will only appear if any errors are returned. It will contain an array of validation errors associated with the wireless address (mobile phone number). |
| message | A summary message indicating the results of the request. If multiple failures occur, it will not contain all errors. |
| errors | Contains one or more of the following keys: email, secondary_email or wireless. This tells you which information threw the error. |
Below are some examples of responses. For each example, the callback is JSONP callback.
Unsuccessful Request
There are many causes for this response. The topic code may be missing from the request or the code doesn't exist. The account may be disabled or web services are disabled. The API key might be missing from the request or it doesn't match the API key for the account (accounts may not have an API key).
jsonpcallback({"message":"Topic not found."})
Failed due to invalid primary subscriber email
jsonpcallback({"errors":{"email":["Email is invalid"]},"topic_id":"ANTHRAX","message":"There were problems creating the email profile."})
Failed due to invalid secondary subscriber email
jsonpcallback({"errors":{"secondary_email":["Email is invalid"]},"topic_id":"ANTHRAX","message":"There were problems creating the secondary email profile.","citizen_id":19199})
Failed due to topic restrictions
This request failed to subscribe the secondary profile's address to the topic because of restrictions on the topic. The subscriber profile for the secondary email was created, but they do not have any subscriptions.
jsonpcallback({"errors":{"secondary_email":["Unable to subscribe test@evotest.govdelivery.com to topic ANTHRAX"]},"topic_id":"ANTHRAX","message":"There were problems assigning the secondary email profile to the requested topic.","citizen_id":19200})
Failed due to invalid wireless address
The request was able to create a subscriber profile and identify the topic, but it failed to create a wireless profile due to a validation error.
jsonpcallback({"errors":{"wireless":["Phone can't be blank"]},"topic_id":"ANTHRAX","message":"There were problems creating the wireless profile.","citizen_id":19198})
Failed to update question responses.
The request was successful, but it was unable to update the question responses. Failure to update question responses can be caused by invalid question IDs, valid IDs of disabled questions, or questions that are assigned to specific topics not included in the request. Another potential cause is the question type requires a specific answer ID that was not included.
jsonpcallback({"errors":{"email":["Unable update responses for test@sink.govdelivery.com"]},"topic_id":"ANTHRAX","message":"Subscriber profile successfully created.","citizen_id":19227})
Related Topics
Was this page helpful? Can't find what you need? Let us know
