RESTful API for 1-800 Notify

 

INTRODUCTION

The 1-800 Notify application program interface (API) utilizes a RESTful interface. The current implementation exposes 2 resource endpoints: “jobs” and “notifications”. The API is available from the https://api.1800notify.com URL.

NOTE: the interface is currently using a self signed certificate. CURL will require the “-k” option to allow access. (Once we complete development, we will install a regular signed certificate)

JSON REFERENCES

http://www.json.org/

https://jsonformatter.curiousconcept.com/

https://google.github.io/styleguide/jsoncstyleguide.xml

Access to the API requires standard basic access authentication, which is required for all operations (except PING).

Currently all operations are JSON. So “Accept” and “Content_type” headers do not affect the output. These 2 commands will yield the same result:

curl -k -u USER:PASS -i -H "Accept: application/json" -H "Content_tpe: application/json" -X GET 'https://api.1800notify.com/jobs'

curl -k -u USER:PASS -X GET 'https://api.1800notify.com/jobs'

Also, you may embed the username and password in the URL. The following commands are equivalent:

curl -k -X GET 'https://USER:PASS@api.1800notify.com/jobs'

curl -k -u USER:PASS -X GET 'https://api.1800notify.com/jobs'

The -u option in the examples for clarity. Also, the examples will use the curl “-i” option to display HTML header information.

System identifiers look like this “[1479813810-042407-14801]”. They include brackets (but not the quotes) and consist of three sets of numbers. The first 2 numbers are the Unix time stamp, where the first number is seconds and the second number is milliseconds indicating the time the record was created. The third number is a random session number.  

 

RESULTS

Results, if they are not a JSON list of records, take a general form of:

{"msg": "could not create new job", "success": "false", "p1": "duplicate", “p2”: “”, “p3”: “”, “p4”: “” }

Where:

msg: is an english description of the status of the transaction

success: true/false, whether the transaction was successful

p1-p4: generic parameter based on the message. ID’s are typically save in p1



OPTIONS

Page: to limit the number of results returned a page of 50 results items will be returned. By default, page is set to 1. For example:

curl -u USER:PASS -k -i -X GET 'https://api.1800notify.com/jobs/?page=2'

Will return elements 51 to a maximum 100.

Filter: the filter option takes a json object containing 1 or more field / value combinations.

 

curl -u USER:PASS -k -i -X GET 'https://api.1800notify.com/jobs/?status=pending'

 

Will return the jobs with a status of pending. A job status can be prepare, scheduled, pending, and done.

 

Job_id parameter is required for notifications end point:

curl -u USER:PASS -k -i -X GET 'https://api.1800notify.com/notifications/?job_id=[1479813810-042407-14801]'

 

This will yield all the notification records for the job denoted by the job id [1479813810-042407-14801].

 

EXAMPLES

 

PING: test connectivity by getting the root url. Authentication is not required.

 

curl -k -i -X GET 'https://api.1800notify.com'

 

HTTP/1.1 200 OK

Content-Length: 13

Content-Type: text/html; charset=UTF-8

 

RESTful APIv3

 

Add a job: to add a job

NOTE: as a safety precaution, you can put your account in “Safe Mode” to prevent calls from being made. See here for more information:

 

https://1800notify.zendesk.com/hc/en-us/articles/207479773-How-to-Start-or-Stop-Your-Entire-Account-STOPPED-or-RUNNING-Safe-Mode-

 

NOTE: as system safety precaution, you can only the same file (as given by the file’s MD5 hash) to a given message one time. For instance, if you have a file “APPTS-2017-04-15.csv” and send it to the message “APPOINTMENTS” twice, the second time your upload will fail with a “duplicate” error. If you delete the job, either from the UI or from the API, you may again upload that file to that message.

 

curl -u USER:PASS -k -i -F "message=NextGen-1" -F "upload=@Safe-NextGen2.txt" -X POST 'https://api.1800notify.com/jobs'

 

HTTP/1.1 200 OK

Content-Length: 91

Content-Type: application/json

 

{"msg": "new job has been scheduled", "success": "true", "p1": "[1492357006-434044-25984]"}

 

This indicates a successful job at where the job id is [1492357006-434044-25984]. If this command is run a second time, it will yield a “duplicate” error:

 

curl -u USER:PASS -i -F "message=APPOINTMENTS" -F "upload=@APPTS-2017-04-15.csv" -X POST 'https://api.1800notify.com/jobs/’

 

HTTP/1.1 200 OK

Content-Length: 74

Content-Type: application/json

 

{"msg": "could not create new job", "success": "false", "p1": "duplicate"}



GET first page of jobs (50)

curl -k -u USER:PASS -i -H "Accept: application/json" -H "Content_type: application/json" -X GET 'https://api.1800notify.com/jobs'

 

HTTP/1.1 200 OK

Content-Length: 15375

Content-Type: application/json

 

{"[1492357006-434044-25984]": {"transfer": "", "timezone": "EST", "caller_id": "386-334-6434", "status": "done", "start": "1487424326", "total_contacts": "1", "hash": "4d9cbe48dcd1545eafbe8ea5b0049f59", "use_variable_lines": "", "date_start": "1487424600", "email_from": "martin@1800notify.com", "transfer3": "", "date_end": "", "date_days": "", "type": "", "file": "1800notify-schedule-for-demo.csv", "transfer2": "", "name": "test", "end": "1487424348", "info": "", "date": "2017-02-18", "attempt": ""}, "[1479213438-226088-26661]": {"transfer": "386-334-6434", "timezone": "EST", "caller_id": "386-506-8224", "status": "done", "start": "1479213451", "total_contacts": "1", "hash": "d10fbbc27f748f59b0c3b54fd5543436", "use_variable_lines": "", "date_start": "1479213900", "email_from": "martin@1800notify.com", "transfer3": "800-939-1853", "date_end": "", "date_days": "", "type": "", "file": "clientname_1_2016-11-11_15-10-spanish-test.xml", "transfer2": "386-506-8224", "name": "----Spanish-testing-oz", "end": "1479213596", "info": "", "date": "2016-11-15", "attempt": ""}}

 

Explicitly request page 1 of the results.

curl -k -u USER:PASS -i -H "Accept: application/json" -H "Content_type: application/json" -X GET 'https://api.1800notify.com/jobs?page=1'

 

This will give the same results as above.

 

Explicitly request page 2 of the results.

curl -k -u USER:PASS -i -H "Accept: application/json" -H "Content_type: application/json" -X GET 'https://api.1800notify.com/jobs?page=2'

 

This will give similar results as above.

 

GET a single job.

curl -k -u USER:PASS -i -H "Accept: application/json" -H "Content_tpe: application/json" -X GET 'https://api.1800notify.com/jobs/[1492357006-434044-25984]'

 

HTTP/1.1 200 OK

Content-Length: 505

Content-Type: application/json

 

{"[1492357006-434044-25984]": {"transfer": "", "timezone": "EST", "caller_id": "386-334-6434", "status": "done", "start": "1487424326", "total_contacts": "1", "hash": "4d9cbe48dcd1545eafbe8ea5b0049f59", "use_variable_lines": "", "date_start": "1487424600", "email_from": "martin@1800notify.com", "transfer3": "", "date_end": "", "date_days": "", "type": "", "file": "1800notify-schedule-for-demo.csv", "transfer2": "", "name": "test", "end": "1487424348", "info": "", "date": "2017-02-18", "attempt": ""}}



GET the notifications for this job (job_id query parameter is required), where job_id is [1492357006-434044-25984]:

curl -k -u USER:PASS -i -X GET 'https://api.1800notify.com/notifications?job_id=[1492357006-434044-25984]'

 

GET the notifications for this job, second page:

curl -k -u USER:PASS -i -X GET 'https://api.1800notify.com/notifications?job_id=[1492357006-434044-25984]&page=2'

 

GET a single notification with notification id of [1487424609-657769-10538]

curl -k -u USER:PASS -i -X GET 'https://api.1800notify.com/notifications/[1487424609-657769-10538]'



DELETE the job.

curl -k -u USER:PASS -i -X DELETE 'https://api.1800notify.com/jobs/[1492357006-434044-25984]'

 

HTTP/1.1 200 OK

Content-Length: 51

Content-Type: application/json

 

{"msg": "Job marked as deleted", "success": "true"}



Phone #’s that can be used for calling and testing your account:

Currently these phone #’s will answer and generate a “1” tone confirming the appt.

 

12028029993

13862182699

12012443301

13869514406

12054099095

13212046441

13862468903

12046743408

13866733291

12046743404

13865970409

13862462392

13862182698

13864787305



curl -k -u USER:PASS -i -F "message=ABC001-ABC1" -F "upload=@sample.json" -X POST 'https://api.1800notify.com/jobs'

 

NOTE: If new appointment, then set user1 = “1”

Put language code into user2

 

{

 "0": {

"name": "Smith, Joseph",

"phone": "2028029993",

"mobile": "",

"apptTime": "9:30 am",

"apptDate": "04/20/2017",

"apptTov": "F/U",

"apptStatus": "pending",

"apptLabs": "B12",

"balance": "12.50",

"provider": "Dr. Pepper",

"location": "Building 1",

"user1": "1",  

"user2": "English",   

"user3": "",

"clientCode": "ABC001",

"patientCode": "ReminderID",

"caseCode": "ApptID",

"medicalCode": "000-medicalCode",

"facilityCode": "ABC1",

"reminderType": "P",

"email": "jsmith@acme.com"

 },

 "1": {

"name": "O'malley, Thomas",

"phone": "3862182699",

"mobile": "",

"apptTime": "10:15 AM",

"apptDate": "04/20/2017",

"apptTov": "X-ray",

"apptStatus": "pending",

"apptLabs": "",

"balance": "4.21",

"provider": "Dr. Pepper",

"location": "Building 1",

"user1": "0",

"user2": "",

"user3": "",

"clientCode": "ABC001",

"patientCode": "ReminderID",

"caseCode": "ApptID",

"medicalCode": "001-medicalCode",

"facilityCode": "ABC1",

"reminderType": "P",

"email": "t.omally@nowhere.com"

 }

}



CALLBACK (to discuss)

The callback option will perform a GET on the url provided when the job is completed.

 

curl -u USER:PASS -i -F "message=APPOINMENTS" -F “callback=https://www.somewhere.com/myresults” -F "upload=@APPTS-2017-04-15.csv" -X POST 'https://api.1800notify.com/jobs/’

 

HTTP/1.1 200 OK

Content-Length: 74

Content-Type: application/json

 

{"msg": "new job has been scheduled", "success": "true", "p1": "[1492357006-434044-25984]"}

 

When the job completes, a GET will be made to “https://www.somewhere.com/myresults” with results like this:

 

HTTP/1.1 200 OK

Content-Length: 74

Content-Type: application/json

 

{"msg": "new job completed", "success": "true", "p1": "[1492357006-434044-25984]"}



Here the p1 parameter is the job identifier of the the completed job. To get the status of the notifications, use the notifications resource:

 

curl -k -u USER:PASS -i -X GET 'https://api.1800notify.com/notifications?job_id=[1492357006-434044-25984]'

 

HTTP/1.1 200 OK

Content-Length: 36224

Content-Type: application/json

 

{"[1487424609-551007-69947]": {"provider": "", "time": "", "patient_mobile": "12012443301", "data": "", "status": "done", "case_code": "", "facility_phone": "land", "client_code": "", "phone_night": "", "user2": "text", "medical_code": "", "name": "Samantha Parker", "location": "", "appt_dob": "", "user3": "", "user1": "susan@company.com", "phone": "12012443301", "appt_time": "9:00 AM", "facility_address": "land", "fax": "", "phone_alt": "", "patient_code": "", "appt_status": "", "email": "", "appt_tov": "NEW", "facility_code": "", "balance": "", "appt_date": "7/11/2017", "appt_labs": "", "tags": "", "id_job": "[1487424604-808990-58956]", "info": "Appointment confirmed", "message": "", "date": "", "reminder_type": "", "callfile": ""}}

Have more questions? Submit a request

Comments

Powered by Zendesk