NAV

Subscription API(Last Updated : 01/11/2017)

Create Subscriptions

You can create a subscription profile for a subscriber. This profile is required if you wish to send messages to the subscriber.

You can create multiple subscriptions at once by creating multiple Subscription objects and adding them into the Subscriptions list. The required parameters are shown below, and you can refer to the REST API documentation for more details.

Fields

Field Name Description
Names of Lists Subscribers will be added to specified distribution lists.
Subscriptions See Subscription Object table below.

Subscription Object

Field Name Description
First name First name of subscription.
Last name Last name of subscriber.
Voice device If you would like to send voice messages to the subscriber, you must specify voice_device. When setting the voice_device attribute, you must register the respective landline or mobile number.

Note: Supported countries for voice messages are US, Canada, Guam and Puerto Rico.
Target At least one of the following contents must be required. Multiple targets can be set. See Target Object table below.
Custom data Below is a list of Target parameters. You must set at least one parameter.

Target Object

Field Name Description
email Email address of the subscriber.
mobile Mobile number of the subscriber.
landline Landline number of the subscriber.

The following example demonstrates how you can create multiple Subscriptions that are subscribed to the same Distribution List.

try { List<String> listNames = Arrays.asList("myList1", "myList2"); List<Subscription> subscriptions = Arrays.asList( new Subscription.Builder() .firstName("Hayden") .lastName("Lee") .email("hayden@example.com") .build(), new Subscription.Builder() .mobile(Subscription.PhoneNumber.of(1, "3334445555")) .build() ); SubscriptionCreationResult result = SubscriptionApi.with(apiContext) .bulkCreate(BulkSubscriptions.of(listNames, subscriptions)) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The BasicApiResult object contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Retrieve All Subscription IDs

The following shows you how to retrieve all the IDs for the created Subscriptions:

ApiClient apiClient = ... ApiContext apiContext = ... try { List<Long> ids = SubscriptionApi.with(apiContext) .listAllIds() .executeOn(apiClient); // Process with subscription ids... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

Each Long value within the list corresponds to a Subscription ID.

Retrieve a specific Subscription

The following shows you how you can retrieve details for the Subscription by using the Subscription ID:

ApiClient apiClient = ... ApiContext apiContext = ... try { long subscriptionId = 12345L; SubscriptionInfo subscriptionInfo = SubscriptionApi.with(apiContext) .get(subscriptionId) .executeOn(apiClient); // Process subscription info... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The returned SubscriptionInfo object will have the following fields:

Fields

Method Name Data Returned Description
getListIds(): List<Long> List IDs Registered distribution list IDs.
getCreatedDate(): LocalDate Created date Signup date for the subscriber.
getEmail(): SubscriptionInfo.Email E-mail Email address of the subscriber.
getMobile(): SubscriptionInfo.PhoneNumber Mobile Mobile number of the subscriber.
getLandline(): SubscriptionInfo.PhoneNumber Landline Landline number of the subscriber.
getFirstName(): String First name First name of subscriber.
getLastName(): String Last name Last name of subscriber.
getCustomDataList(): List<SubscriptionInfo.CustomData> Custom data Custom data of the subscriber, like birthday, age, etc.

Subscription Update

You can update a subscription profile for a subscriber after creation. You must pass the following parameters when updating a Subscription.

Fields

Field Name Description
Names of Lists Subscribers will be added to specified distribution lists.
Subscriptions See Subscription Object table below.

Subscription Object

Field Name Description
First name First name of subscription.
Last name Last name of subscriber.
Voice device If you would like to send voice messages to the subscriber, you must specify voice_device. When setting the voice_device attribute, you must register the respective landline or mobile number.

Note: Supported countries for voice messages are US, Canada, Guam and Puerto Rico.
Target At least one of the following contents must be required. Multiple targets can be set. See Target Object table below.
Custom data Below is a list of Target parameters. You must set at least one parameter.

Target Object

Field Name Description
E-mail Email address of the subscriber.
Mobile Mobile number of the subscriber.
Landline Landline number of the subscriber.

ApiClient apiClient = ... ApiContext apiContext = ... List<String> newListNames = Arrays.asList("foo", "bar", "baz"); // can be ommitted SubscriptionUpdate update = new SubscriptionUpdate.Builder(newListNames) .firstName("Foo") .lastName("Bar") .build(); try { long subscriptionId = 12345L; SubscriptionUpdateResult result = SubscriptionApi.with(apiContext) .update(listId, listUpdate) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The BasicApiResult object is returned when you update a Subscription. It contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Subscription Delete

The following sample code demonstrates how you can delete a specific Subscription.

ApiClient apiClient = ... ApiContext apiContext = ... try { long subscriptionId = 12345L; SubscriptionDeletionResult result = SubscriptionApi.with(apiContext) .delete(subscriptionId) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The BasicApiResult object is returned when you delete a Subscription. It contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Report Retrieval

You can retrieve the status of your subscription creation/update/deletion request. The following example shows how you can use the Result object from your API request to make a call which will fetch the status of that request.

ApiClient apiClient = ... ApiContext apiContext = ... try { long subscriptionId = 12345L; SubscriptionDeletionResult delResult = SubscriptionApi.with(apiContext) .delete(subscriptionId) .executeOn(apiClient); VariableResult<SubscriptionReport, ApiStatusReport> report = delResult.getReportRequest(apiContext) .executeOn(apiClient); // Process the report... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

VariableResult

After retrieving the report, you will receive an VariableResult object that is either a success or a failure status. For more details please refer to the javadoc.

Subscription Create Report

If your original request contained successful requests and failed requests, you may receive a SubscriptionCreationFailureReport for each failure.

Each SubscriptionCreationFailureReport has the following fields:

Fields

Method Name Data Returned Description
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.
getRequestedData(): Map<String, Object> Requested data Original requested data.

If all of the subscription creation requests in your original request failed, you will receive a SubscriptionBulkCreationFailureReport.
A SubscriptionBulkCreationFailureReport has the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getStatuscode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.
getErrorData(): List<String> Error data This is the additional data for the error returned by the status code.

If the subscription was created successfully, a report request will return a VariableResult with a SubscriptionReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getId(): long Subscription ID The subscriber's unique ID number.
Subscription Update/Delete Report

If the subscription was updated/deleted successfully, a report request will return a VariableResult with a SubscriptionReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getId(): long Subscription ID The subscriber's unique ID number.

If the subscription was not updated/deleted successfully, a report request return a VariableResult with an ApiStatusReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.