MENU
Pdcflowlogo
PHP CSharp Perl Ruby
NotificationApi

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.



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.

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

<?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}