6/9/2022
Nudge Application
Technical API Document
PREPARED BY: Ateeq Ur Rehman
Nudge Application Technical API Document
Table of Contents
1. Enviornment .....................................................................................................................................................3
2. API Objects Overview ......................................................................................................................................3
2.1 API Key .......................................................................................................................................................3
2.2 Nudge ...........................................................................................................................................................3
2.3 Email Nudge ................................................................................................................................................3
2.4 SMS Nudge ..................................................................................................................................................4
2.5 WhatsApp Nudge........................................................................................................................................4
3. Authentication...................................................................................................................................................4
4. Getting Started..................................................................................................................................................5
4.1 ContactData API ............................................................................................................................................5
4.1.1 Resource description ........................................................................................................................5
4.1.2 Resource URL ...................................................................................................................................5
4.1.3 Parameters ........................................................................................................................................5
4.1.4 Request body .....................................................................................................................................6
4.1.5 Response ............................................................................................................................................6
4.2 Email API ........................................................................................................................................................6
4.2.1 Schedule Email Nudge ................................................................................................................................6
4.2.1.1. Resource description ....................................................................................................................6
4.2.1.2. Resource URL ...............................................................................................................................6
4.2.1.3. Parameters ....................................................................................................................................7
4.2.1.4. Request body .................................................................................................................................7
4.2.1.5. Response ........................................................................................................................................7
4.2.2 Send Real Time Email Nudge .....................................................................................................................7
4.2.2.1. Resource description ....................................................................................................................7
4.2.2.2. Resource URL ...............................................................................................................................7
4.2.2.3. Parameters ....................................................................................................................................8
4.2.2.4. Request body .................................................................................................................................8
4.2.2.5. Response ........................................................................................................................................8
4.3 SMS API ..........................................................................................................................................................9
4.3.1 Schedule SMS Nudge ..................................................................................................................................9
1|Page Version: 1.0
Nudge Application Technical API Document
4.3.1.1. Resource description ....................................................................................................................9
4.3.1.2. Resource URL ...............................................................................................................................9
4.3.1.3. Parameters ....................................................................................................................................9
4.3.1.4. Request body .................................................................................................................................9
4.3.1.5. Response ........................................................................................................................................9
4.3.2 Send Real Time SMS Nudge .................................................................................................................... 10
4.3.2.1. Resource description ................................................................................................................. 10
4.3.2.2. Resource URL ............................................................................................................................ 10
4.3.2.3. Parameters ................................................................................................................................. 10
4.3.2.4. Request body .............................................................................................................................. 10
4.3.2.5. Response ..................................................................................................................................... 11
4.4 WhatsApp API ............................................................................................................................................. 11
4.4.1 Schedule WhatsApp Nudge ..................................................................................................................... 11
4.4.1.1. Resource description ................................................................................................................. 11
4.4.1.2. Resource URL ............................................................................................................................ 11
4.4.1.3. Parameters ................................................................................................................................. 11
4.4.1.4. Request body .............................................................................................................................. 11
4.4.1.5. Response ..................................................................................................................................... 12
4.4.2 Send Real Time WhatsApp Nudge.......................................................................................................... 12
4.4.2.1. Resource description ................................................................................................................. 12
4.4.2.2. Resource URL ............................................................................................................................ 12
4.4.2.3. Parameters ................................................................................................................................. 12
4.4.2.4. Request body .............................................................................................................................. 13
4.4.2.5. Response ..................................................................................................................................... 13
2|Page Version: 1.0
Nudge Application Technical API Document
1. Enviornment
This document is intended to describe the nudge APIs through which users can access data and perform
operations in the “Nudge Platform”.
Base URL: All the enpoints are accessible through the qa.nudge.pro host.
2. API Objects Overview
To understand the API document, you must need to review the main objects of the application that are
involved in the API calls.
2.1 API Key
The registered user will get authenticated through the API key which is unique for registered users. It is
system-generated which will be created by the user in the “Nudge Platform” and will be used later in the
API requests such as importing contact data, sending email, SMS and WhatsApp nudges. The registered
user can generate more than one API keys in his nudge account.
Example of API Key:
L1B/PUgtBPVu9wEbhTx7LnuiGuqplbEA+D7Wj28uAiOyaqqZBimqGFucQkzAYROrKdfbiz/tx5Xqsy
4YVdDW2w==
2.2 Nudge
The nudge is a system object that comes in a variety of forms, including email nudges, SMS nudges, and
WhatsApp nudges. NudgeID is its unique identifier, which will be used in API queries to retrieve data.
It's an integer number for utilising API calls to deliver nudges across the platform. It may not always be
unique because a registered user can resend the failed nudge in case of having low balance in his account.
Example of Nudge ID: 212
2.3 Email Nudge
The email nudge that sent in real time using API call have a unique identifier that system provides in API
response which is emailId. The API response will have emailId that is unique for each real time nudge.
The scheduled email nudge does not have emailId as it is scheduled on the specified date and time. The
emailId is hexadecimal-formatted.
Example of EmailId: 627997370f0ab8e06adeba70
3|Page Version: 1.0
Nudge Application Technical API Document
2.4 SMS Nudge
The SMS nudge that is sent in real time using API call will also have unique identifier which is smsId
formatted in hexadecimal having unique value for each SMS nudge. The registered user can send SMS
nudges after verifying his toll free mobile number.
Example of SMSId: 627997370f0ab8e06adeba70
2.5 WhatsApp Nudge
The WhatsApp nudge sent in real time using API call will have unique identifier whatsAppId which is
formatted in hexadecimal having unique value for each WhatsApp nudge.
Example of WhatsAppID: 627997370f0ab8e06adeba70
3. Authentication
Before calling APIs for sending different type of nudges, the user must have to create API keys in the
system that will be used for authorization of the API requests lator for sending nudges. To create API key,
the user must have to be registered in the “Nudge Platform”.
Steps for Sign up
1. Open URL “https://qa.nudge.pro” in web browser.
2. Click on “Sign up free” button.
3. Enter a valid “Business email” and strong “password” then click on “Signup” button.
4. Click on “Verify your email” or open the link from your email
5. Fill all the values for company profile and click on “Submit” button
Steps for Generating API key
1. Click on “Name” from top right side.
2. Click on “Configuration” from popup menu
3. Click on “API Management” tab
4. Click on “Create new API Key”
5. Enter name of your API key & click on “Generate” button
6. Copy the Key & click on the “Done” button.
4|Page Version: 1.0
Nudge Application Technical API Document
4. Getting Started
The user must first register an account on the "Nudge Platform" before using the Nudge APIs. Different
types of nudges will be sent using the API Key. As a result, there will be two key requirements that must
be met in order to use nudging APIs.
• An Nudge Account
• API Key which will be used.
4.1 ContactData API
4.1.1 Resource description
The user will upload contact data in CSV file for existing nudges.
4.1.2 Resource URL
To upload contact data CSV file, the following URL will be used:
https://qa.nudge.pro/api/v1/ContactData/Import
4.1.3 Parameters
The parameters for the importing contact data API call are:
• NudgeId = 212 (Integer Value)
• NudgeType = email (sms/email/whatsapp)
• File = contact.csv (csv file)
5|Page Version: 1.0
Nudge Application Technical API Document
4.1.4 Request body
The API call will be authorized through the user’s API key. The Crul for the importing contact data
file will be:
curl -X 'POST' \
'https://qa.nudge.pro/api/v1/ContactData/Import' \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Content-Type: multipart/form-data' \
-F 'NudgeId=212' \
-F 'NudgeType=sms' \
-F '[email protected];type=text/csv'
4.1.5 Response
The response of the importing contact data file will be:
{
"data": null
"errors": [],
"hasErrors": false,
"errorGuid": null
}
4.2 Email API
4.2.1 Schedule Email Nudge
4.2.1.1. Resource description
The email nudge will sechdule to be run now through using this API call. It means that the scheduled
email nudge will be send now using this API call. The POST method will be used for sending
scheduled email nudge: POST /v1/Email/LaunchNudge
4.2.1.2. Resource URL
To send the scheduled nudge now, the following URL will be used:
https://qa.nudge.pro/api/v1/Email/
6|Page Version: 1.0
Nudge Application Technical API Document
4.2.1.3. Parameters
The parameters for the scheduling email to be send now will use following parameters:
• NudgeId = 212 (Integer Value)
4.2.1.4. Request body
The API call will be authorized through the user’s API key. The Crul for the sending email nudge now
will be:
curl -X 'POST' \
'https://qa.nudge.pro/api/v1/Email/LaunchNudge \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json' \
-d '{
"nudgeId": 0
}'
4.2.1.5. Response
The response of sending scheduled email nudge will be:
{
"errors": [],
"hasErrors": false,
"errorGuid": null
}
4.2.2 Send Real Time Email Nudge
4.2.2.1. Resource description
The real time email nudge will be send now through using this API call. It cannot be scheduled and
send after creation in real time. The POST method will be used for sending real time email nudge:
POST /v1/Email/SendForNudge
4.2.2.2. Resource URL
To send the real time nudge now, the following URL will be used:
https://qa.nudge.pro/api/v1/Email/SendForNudge
7|Page Version: 1.0
Nudge Application Technical API Document
4.2.2.3. Parameters
The parameters for the sending real time email nudge now will use following parameters:
{
"nudgeId": 0,
"toEmail": "string",
"toName": "string",
"mergeTags": [
{
"tagName": "string",
"tagValue": "string"
}
]
}
Parameters are shown in JSON format.
4.2.2.4. Request body
The API call will be authorized through the user’s API key. The Crul for the sending real time email
nudge will be:
curl -X 'POST' \
'https://qa.nudge.pro/api/v1/Email/SendForNudge \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Authorization:
-H 'Content-Type: application/json' \
-d '{
"nudgeId": 0
}'
4.2.2.5. Response
The response of sending real time email nudge will be:
{
"data": {
"emailId": "627997370f0ab8e06adeba70"
},
"errors": [],
"hasErrors": false,
"errorGuid": null
}
8|Page Version: 1.0
Nudge Application Technical API Document
4.3 SMS API
4.3.1 Schedule SMS Nudge
4.3.1.1. Resource description
The SMS nudge will sechdule to be run now through using this API call. It means that the scheduled
SMS nudge will be send now using through API call. The POST method will be used for sending
scheduled SMS nudge: POST /v1/Sms/LaunchNudge
4.3.1.2. Resource URL
To send the scheduled nudge now, the following URL will be used:
'https://qa.nudge.pro/api/v1/Sms/LaunchNudge
4.3.1.3. Parameters
The parameters for the scheduling SMS nudge to be send now will use following parameter:
• NudgeId = 212 (Integer Value)
4.3.1.4. Request body
The API call will be authorized through the user’s API key. The Crul for the sending SMS nudge now
will be:
curl -X 'POST' \
'https://qa.nudge.pro/api/v1/Sms/LaunchNudge \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Authorization:
-H 'Content-Type: application/json' \
-d '{
"nudgeId": 0
}'
4.3.1.5. Response
The response of sending scheduled SMS nudge will be:
{
"errors": [],
"hasErrors": false,
"errorGuid": null
}
9|Page Version: 1.0
Nudge Application Technical API Document
4.3.2 Send Real Time SMS Nudge
4.3.2.1. Resource description
The real time SMS nudge will be send now through using this API call. It cannot be scheduled and
send after creation in real time. The POST method will be used for sending real time SMS nudge:
POST /v1/Sms/SendForNudge
4.3.2.2. Resource URL
To send the real time SMS nudge now, the following URL will be used:
https://qa.nudge.pro/api/v1/Sms/SendForNudge
4.3.2.3. Parameters
The parameters for the sending real time SMS nudge will use following parameters:
{
"nudgeId": 0,
"toPhoneNumber": "string",
"mergeTags": [
{
"tagName": "string",
"tagValue": "string"
}
]
}
Parameters are shown in JSON format.
4.3.2.4. Request body
The API call will be authorized through the user’s API key. The Crul for the sending real time SMS
nudge will be:
{
'https://qa.nudge.pro/api/v1/Sms/SendForNudge' \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json' \
-d '{
"nudgeId": 0
}'
10 | P a g e Version: 1.0
Nudge Application Technical API Document
4.3.2.5. Response
The response of sending real time SMS nudge will be:
{
"data": {
"smsId": "627997370f0ab8e06adeba70"
},
"errors": [],
"hasErrors": false,
"errorGuid": null
}
4.4 WhatsApp API
4.4.1 Schedule WhatsApp Nudge
4.4.1.1. Resource description
The WhatsApp nudge will sechdule to be run now through using this API call. It means that the
scheduled WhatsApp nudge will be send now using through API call. The POST method will be used
for sending scheduled WhatsApp nudge: POST /v1/WhatsApp/LaunchNudge
4.4.1.2. Resource URL
To send the scheduled WhatsApp nudge now, the following URL will be used:
https://qa.nudge.pro/api/v1/WhatsApp/LaunchNudge
4.4.1.3. Parameters
The parameters for the scheduling WhatsApp nudge to be send now will use following parameter:
• NudgeId = 212 (Integer Value)
4.4.1.4. Request body
The API call will be authorized through the user’s API key. The Crul for the sending WhatsApp now
nudge will be:
curl -X 'POST' \
'https://qa.nudge.pro/api/v1/WhatsApp/LaunchNudge' \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json' \
-d '{
"nudgeId": 0
11 | P a g e Version: 1.0
Nudge Application Technical API Document
}'
4.4.1.5. Response
The response of sending scheduled WhatsApp nudge will be:
{
"errors": [],
"hasErrors": false,
"errorGuid": null
}
4.4.2 Send Real Time WhatsApp Nudge
4.4.2.1. Resource description
The real time WhatsApp nudge will be send now through using this API call. It cannot be scheduled
and send after creation in real time. The POST method will be used for sending real time WhatsApp
nudge: POST /v1/ WhatsApp/SendForNudge
4.4.2.2. Resource URL
To send the real time WhatsApp nudge now, the following URL will be used:
https://qa.nudge.pro/api/v1/ContactData/Import
4.4.2.3. Parameters
The parameters for the sending real time WhatsApp nudge will use following parameters:
{
"nudgeId": 0,
"toEmail": "string",
"toName": "string",
"mergeTags": [
{
"tagName": "string",
"tagValue": "string"
}
]
}
Parameters are shown in JSON format.
12 | P a g e Version: 1.0
Nudge Application Technical API Document
4.4.2.4. Request body
The API call will be authorized through the user’s API key. The Crul for the sending real time
WhatsApp nudge will be:
curl -X 'POST' \
'https://qa.nudge.pro/api/v1/ContactData/Import' \
-H 'Authorization: <API_KEY>' \
-H 'accept: text/plain' \
-H 'Authorization:
J3/V4x5ow5K3BB3cSNx3mpYLUcwaRARvp3RXtXvafS8oScEJi4oKpJVViLwQqqAbiHw4ZX5fZ
PM7SAy+pMl/5w==' \
-H 'Content-Type: application/json' \
-d '{
"nudgeId": 0
}'
4.4.2.5. Response
The response of sending real time WhatsApp nudge will be:
{
"data": {
" whatsAppId": "627997370f0ab8e06adeba70"
},
"errors": [],
"hasErrors": false,
"errorGuid": null
}
13 | P a g e Version: 1.0
