Notification Service API

The Notification Service allows easy integration for getting data about Emails and SMS Notifications.

Authentication and authorization for the NotificationService will be done with a Base64 encoded username:password, passed in through the BASIC HTTP Authorization Header.

General Service Notes

`GET`	Retrieve a single entity or a list of entities.
`RESPONSE`	In general, fields will only be returned if their value is not null or empty.

Email Configuration

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/configure
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/configure

Enable or Disable Email OptOut
A POST will create or update a ConfigureMail object.
A GET will retrieve a ConfigureMail object for the companyId provided.

ConfigureMail Object

Attribute	Description
useOptOut boolean	Should the company use the email OptOut logic.

Email Validate

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/validate

Validate a list of email addresses to check if they have Opted Out or Bounced.

POST an EmailAddressList object to see which email addresses have Opted Out or Bounced

If all valid an HttpStatus 200 is returned.
If any/all invalid an HttpStatus 400 is returned.

Any failures will be returned in a RequestErrorList object with an error and description for each invalid email address

Request EmailAddressList

Attribute	Description
emailAddressList Alphanumeric List75	The list of Email Addresses to validate.

Email Blocked Search

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search

POST EmailBlockedSearchParameters to this url to get an EmailBlockedList containing all blocked email addresses that match the search parameters.

Request EmailBlockedSearchParameters

Attribute	Description
emailAddressList Alphanumeric List75	A list of email addresses to filter the search by.
startDate Alphanumeric19	Starting date to limit the search by. Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
endDate Alphanumeric19	Ending date to limit the search by. Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
reasonList ListN/A	Filters results by the listed blocked reason(s). If this value is not included, results will contain emails that have been `OPTED_OUT` and `BOUNCED`. Valid values: `OPTED_OUT` `BOUNCED` Note: Other values will be ignored.
recordCount NumericN/A	Limits the number of records returned by the search. Default: 2000 Max: 5000
recordStart NumericN/A	Starting index of the returned results. Default: 0

Response EmailBlockedList

Attribute	Description
emailBlockedList ListN/A	A list of `EmailBlocked` objects.

EmailBlocked

Attribute	Description
companyId Numeric8	The company id associated with the email address that has been blocked.
emailAddress Alphanumeric75	The email address that has been blocked.
date Alphanumeric19	The date the email address was blocked. Format: ISO-8601 (YYYY-MM-DD HH:mm:ss)
reason Alphanumeric19	The reason the email address was blocked. Possible values: `OPTED_OUT` - A user has opted out of receiving emails from this company id `BOUNCED` - An email address was unable to be delivered

Email Unblock

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/unblock

Unblock a list of email addresses. This will remove them from the Opted Out and/or Bounced list.
NOTE: This endpoint will ignore invalid email addresses and/or those not blocked.

POST an EmailAddressList object to unblock the email addresses.

HttpStatus 200 is returned for a valid request.
HttpStatus 400 is returned for an invalid request. Errors will be provided in a RequestErrorList object.

Request EmailAddressList

Attribute	Description
emailAddressList Alphanumeric List75	The list of Email Addresses to unblock.

SMS Validate

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}

Request to validate a Phone Number. This includes checking if the Phone Number has Opted Out from receiving SMS.

GET to see if the phone number has Opted Out

If valid an HttpStatus 200 is returned.
If invalid an HttpStatus 400 is returned.

A failure will be returned in a RequestErrorList object with the error(s) and description for the invalid phone number

REST Fault

RequestErrorList

Attribute	Description
requestErrorList ListN/A	A list of `RequestError` objects containing errors. Constraint(s): Only returned when errors occur.

RequestError

Attribute	Description
code Alpha3	The code for the validation error.
errorCode Numeric5	The error code of the validation error.
description AlphanumericN/A	The description of the validation error.
retriable Boolean5	Boolean to specify if the same request can be retried. This indicates a temporary failure.
apiFieldNameList ListN/A	List of `ApiFieldName` with the specified `RequestError`

ApiFieldName

Attribute	Description
apiFieldName Alphanumeric	The name of the Api Field.
apiFieldValue Alphanumeric	The value of the Api Field. When the Api Field is a list, this will show the specific list value which failed.

Sample Code

This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the Notification Service REST API and are not meant for production use.

To complete a full test, you will need to obtain a valid username and password. To obtain these please Request a Sandbox Account, or contact our Sales Department at sales@pdcflow.com or 1.877.732.4814 for more information.

Result Status Codes

Expected Http Status codes

Status '200':
Description = 'Success.'

Status: '400':
Description = 'Malformed request. The request is either incorrectly formatted, or there are validation errors.'

Status '401':
Description = 'Invalid credentials.'

Status '403':
Description = 'Service not activated.'

Status '404':
Description = 'The requested resource was not found.'

Status '500':
Description = 'An internal error has occurred.'

All requests will return a status code. For example, in the case of status code 400, check for a requestErrorList in the response, containing information on validation failure.

Sample Email Validate

<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate';

$data = [
  'emailAddressList' => [
    'email1@example.com',
    'email2@example.com'
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data),
  ]);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);

$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

// View response
print_r(json_decode($result, true));

if($statusCode == '200') {
  echo $result;
}
else {
  echo "Error #:" . $statusCode;
}
curl_close($curl);

#!/usr/bin/perl

use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting

eval {
    my $data = {
        'emailAddressList' => {
            'email1@example.com',
            'email2@example.com'
        }
    }

    $data = JSON::XS->new->utf8->encode ($data);
    my $url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate';

    my $req = HTTP::Request->new( 'POST', $url );
    $req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
    $req->content_type('application/json');
    $req->content_length( length($data) );
    $req->content( $data );

    my $lwp = LWP::UserAgent->new;
    $lwp->timeout(30);
    my $response = $lwp->request( $req );

    if ( $response->is_success ) {
        print "Success: " . $response->decoded_content;
    }
    else {
        die $response->status_line . ": " . $response->decoded_content;
    }
};

if ( $@ ) {
  print "Error: $@\n";
}

#!/usr/bin/ruby

require 'curl'
require 'curb'
require 'json'

begin

    data = {
        'emailAddressList' => {
            'email1@example.com',
            'email2@example.com'
        }
    }

    c = Curl::Easy.new
    c.url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate'
    c.http_auth_types = :basic
    c.username = 'SomeSecretUsername'
    c.password = 'SomeSecretPassword'
    c.connect_timeout = 5
    c.timeout = 30
    c.verbose = true

    headers={}
    headers['Content-Type'] = 'application/json'
    headers['Content-Length'] = data.to_json.length
    payload = data.to_json

    c.headers = headers
    c.http_post(payload)

    puts JSON.parse c.body_str

    if c.response_code == 200 then
        puts "Success " + c.status
    else
        puts "Error " + c.status
    end
rescue
    puts "Caught: #$!\n"
end

POST an EmailAddressList object to see which email addresses have Opted Out or Bounced

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/validate

Sample EmailBlocked Search

<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search';

$data = [
  'emailAddressList': [
    'email1@example.com',
    'email2@example.com'
  ],
  'startDate': '2021-08-01 00:00:00',
  'endDate': '2021-08-09 23:59:59',
  'reasonList': [
    'OPTED_OUT'
  ],
  'recordCount': 5000,
  'recordStart': 0
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data),
  ]);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);

$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

// View response
print_r(json_decode($result, true));

if($statusCode == '200') {
  echo $result;
}
else {
  echo "Error #:" . $statusCode;
}
curl_close($curl);

#!/usr/bin/perl

use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting

eval {
    my $data = {
        'emailAddressList': {
            'email1@example.com',
            'email2@example.com'
        },
        'startDate': '2021-08-01 00:00:00',
        'endDate': '2021-08-09 23:59:59',
        'reasonList': {
            'OPTED_OUT'
        },
        'recordCount': 5000,
        'recordStart': 0
    }

    $data = JSON::XS->new->utf8->encode ($data);
    my $url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search';

    my $req = HTTP::Request->new( 'POST', $url );
    $req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
    $req->content_type('application/json');
    $req->content_length( length($data) );
    $req->content( $data );

    my $lwp = LWP::UserAgent->new;
    $lwp->timeout(30);
    my $response = $lwp->request( $req );

    if ( $response->is_success ) {
        print "Success: " . $response->decoded_content;
    }
    else {
        die $response->status_line . ": " . $response->decoded_content;
    }
};

if ( $@ ) {
  print "Error: $@\n";
}

#!/usr/bin/ruby

require 'curl'
require 'curb'
require 'json'

begin

    data = {
        'emailAddressList': {
            'email1@example.com',
            'email2@example.com'
        },
        'startDate': '2021-08-01 00:00:00',
        'endDate': '2021-08-09 23:59:59',
        'reasonList': {
            'OPTED_OUT'
        },
        'recordCount': 5000,
        'recordStart': 0
    }

    c = Curl::Easy.new
    c.url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/email/validate'
    c.http_auth_types = :basic
    c.username = 'SomeSecretUsername'
    c.password = 'SomeSecretPassword'
    c.connect_timeout = 5
    c.timeout = 30
    c.verbose = true

    headers={}
    headers['Content-Type'] = 'application/json'
    headers['Content-Length'] = data.to_json.length
    payload = data.to_json

    c.headers = headers
    c.http_post(payload)

    puts JSON.parse c.body_str

    if c.response_code == 200 then
        puts "Success " + c.status
    else
        puts "Error " + c.status
    end
rescue
    puts "Caught: #$!\n"
end

POST EmailBlockedSearchParameters to search for email addresses that have been blocked

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search

Sample Email Unblock

<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock';

$data = [
  'emailAddressList' => [
    'email1@example.com',
    'email2@example.com'
  ]
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data),
  ]);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);

$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

// View response
print_r(json_decode($result, true));

if($statusCode == '200') {
  echo $result;
}
else {
  echo "Error #:" . $statusCode;
}
curl_close($curl);

#!/usr/bin/perl

use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting

eval {
    my $data = {
        'emailAddressList' => {
            'email1@example.com',
            'email2@example.com'
        }
    }

    $data = JSON::XS->new->utf8->encode ($data);
    my $url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock';

    my $req = HTTP::Request->new( 'POST', $url );
    $req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
    $req->content_type('application/json');
    $req->content_length( length($data) );
    $req->content( $data );

    my $lwp = LWP::UserAgent->new;
    $lwp->timeout(30);
    my $response = $lwp->request( $req );

    if ( $response->is_success ) {
        print "Success: " . $response->decoded_content;
    }
    else {
        die $response->status_line . ": " . $response->decoded_content;
    }
};

if ( $@ ) {
  print "Error: $@\n";
}

#!/usr/bin/ruby

require 'curl'
require 'curb'
require 'json'

begin

    data = {
        'emailAddressList' => {
            'email1@example.com',
            'email2@example.com'
        }
    }

    c = Curl::Easy.new
    c.url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock'
    c.http_auth_types = :basic
    c.username = 'SomeSecretUsername'
    c.password = 'SomeSecretPassword'
    c.connect_timeout = 5
    c.timeout = 30
    c.verbose = true

    headers={}
    headers['Content-Type'] = 'application/json'
    headers['Content-Length'] = data.to_json.length
    payload = data.to_json

    c.headers = headers
    c.http_post(payload)

    puts JSON.parse c.body_str

    if c.response_code == 200 then
        puts "Success " + c.status
    else
        puts "Error " + c.status
    end
rescue
    puts "Caught: #$!\n"
end

POST an EmailAddressList object to unblock the email addresses

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/unblock

Sample SMS Validate

<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/1235551234';

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  "Authorization: BASIC " . base64_encode('companyUsername'.':'.'companyPassword')
]);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);  //num seconds to try connecting
curl_setopt($curl, CURLOPT_TIMEOUT, 30); //max number of seconds to allow execution

$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

// View response
print_r(json_decode($result, true));

if($statusCode == '200') {
  echo $result;
}
else {
  echo "Error #:" . $statusCode;
}
curl_close($curl);

#!/usr/bin/perl

use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting

eval {
   my $uri = URI->new("https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/1235551234");

   my $req = HTTP::Request->new( 'GET', $uri );
   $req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );

   my $lwp = LWP::UserAgent->new;
   my $response = $lwp->request( $req );

   if ( $response->is_success ) {
      print "Success: " . $response->decoded_content;
   }
   else {
      die $response->status_line . ": " . $response->decoded_content;
   }
};
if ( $@ ) {
   print "Error: $@\n";
}

#!/usr/bin/ruby

require 'curl'
require 'curb'
require 'json'

begin

   url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/1235551234'

   c = Curl::Easy.new( url )
   c.http_auth_types = :basic
   c.username = 'SomeSecretUsername'
   c.password = 'SomeSecretPassword'
   c.connect_timeout = 5
   c.timeout = 30
   c.verbose = true
   c.perform

   puts JSON.parse c.body_str

   if c.response_code == 200 then
      puts "Success " + c.status
   else
      puts "Error " + c.status
   end
rescue
   puts "Caught: #$!\n"
end

GET to validate a Phone Number. This includes checking if the Phone Number has Opted Out from receiving SMS.

Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}

Services:

Notification Service API

Email Configuration

ConfigureMail Object

Email Validate

Request EmailAddressList

Email Blocked Search

Request EmailBlockedSearchParameters

Response EmailBlockedList

EmailBlocked

Email Unblock

Request EmailAddressList

SMS Validate

REST Fault

RequestErrorList

RequestError

ApiFieldName

Sample Code

Result Status Codes

Sample Email Validate

Sample EmailBlocked Search

Sample Email Unblock

Sample SMS Validate