1. Home
  2. For Developers
  3. REST API for Sign-up Nudges

REST API for Sign-up Nudges

Nudgify’s REST API allows you to show the data you want in your Sign-up Nudges without having to rely on any third party integration. Our API makes it easy for developers to turn data into Social Proof.

This documentation describes how to successfully call the Nudgify API to show you sign-up data in Nudges. For convenience, we say sign-ups, but it can be any type of conversion, such as form submissions, newsletter subscriptions etc.

Are you looking to show your purchases or other type of conversions that include line item information? Go to our API documentation for purchases.

Before you start

For the Sign-up Nudges, requests are made to: https://app.nudgify.com/api/conversions

You will need access to the following:
– Your Nudgify Site Key
– Your Nudgify API Key

You can find the Site and API Keys for each site in your Nudgify account on your Sites page.

api social proof

Authentication

The Nudgify API uses HTTP Bearer Authentication to authenticate requests. This allows you to protect the URLs on your web server so that only you and Nudgify can access them.

You use your Nudgify API key as the bearer token. You can find your API Key in your Nudgify account settings. Use: Authorization: Bearer <API key>

Be sure to keep your API Key secure. Do not share your API key in publicly accessible areas such as GitHub, client-side code, and so forth.

All requests must be secure, i.e. https, not http.

Required headers

accept: application/json
content-type: application/json

Parameters

You can use the parameters below to push your conversions into your Sign-Up Nudges.

Field Type Required? Description
site_key uuid required The id we use to identify your site
conversions array or null required
We use this to identify the type of Nudge we send the data to, in this case: the Sign-Up Nudge
email email required The email address of the user to identify that there has been a new conversion
date date (follow the format Y-m-d H:i:s) required The date we use to show in the Nudge how long ago the conversion took place. We use UTC for the timezone, so make sure you send your date in UTC for accurate time on your Nudges
first_name string or null optional The first name of the user, to show in the Nudge
last_name string or null optional The last name of the user, to show in the Nudge
ip string or null optional The ip address of the user, to show the location in case city/state/country are not available
city string or null optional The city of the user, to show in the Nudge
state string or null optional The state of the user, to show in the Nudge
country string or null (Max characters 2 e.g: GB or US) optional The Country of the user, to show in the Nudge

Example request body

{
  "site_key": "510eeb08-814e-456a-b5c1-8c7c70cc4c00",
  "conversions": [{
    "date": "2021-04-15 04:29:42",
    "email": "john0934@gmail.com",
    "first_name": "John",
    "last_name": "Mendes",
    "ip": "92.21.8.106",
    "city": "Houston",
    "state": "Texas",
    "country": "US"
    },
    {
    "first_name": "Cicilia",
    "last_name": "Mendes",
    "email": "MendesCicilia@gmail.com",
    "ip": "92.21.8.106",
    "date": "2021-04-16 04:29:42",
    "city": "London",
    "state": "",
    "country": "GB"
  }]
}

Example request

curl --request POST \
--url https://app.nudgify.com/api/conversions \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer 
IqJ4GRuODEsFBamKJb3LYXfEf456rVXWeRAkFnvCt' \
--data '{
  "site_key":"510eeb08-814e-456a-b5c1-8c7c70cc4c00",
  "conversions":[{
    "date":"2021-04-15 04:29:42",
    "email":"john0934@gmail.com",
    "first_name":"John",
    "last_name":"Mendes",
    "ip":"92.21.8.106",
    "city":"Houston",
    "state":"Texas",
    "country":"US"
  }]
}'

Success response

If your API request has been successful, you get a success response like the one below.

Response type: Json

{ 
"message": "Request successfully saved.", 
"data": [ "141" ] 
}
Field Type Description
message string Indicates that the request has been successful
data array In case of success shows the ids of all the records saved in our database
errors array In case of an error shows the possible error messages

If your request has been successful, you can find the sign-up data that has been sent through in the Sign-ups tab of your Nudgify Data Feeds.

Error response

If your API request has failed, you get an error response like the one below.

Response type: Json

{
  "message": "Bad Request.",
  "errors": {
    "conversions.0.email": [
    "Email is required."
    ],
    "conversions.1.date": [
    "Date is required."
    ]
  }
}

Possible errors

To help you identify why your API request has failed and what you need to adjust to get a success response, we have made an overview of the possible error messages and what they mean.

HTTP Status Code Summary Description
200 – OK Everything worked as expected
400 – Bad Request
The request was unacceptable, often due to missing a required parameter
401 – Unauthorized No valid API key provided
403 – Forbidden
The API key doesn’t have permissions to perform the request
404 – Not Found The requested resource doesn’t exist
500, 502, 503, 504 – Server Errors Something went wrong on Nudgify’s end

 

Error Message Description
Expected Field Validation Error Messages
Bad Request In case of any field validation error the bad request message is displayed
Site key is required
No Site key has been provided, please provide your Site key. You can find it in your Nudgify account
Site key must be valid
The Site key you provided does not follow the format of our Site keys. You can find your Site key in your Nudgify account
Email is required No email address has been provided, please provide an email address
Email does not match the required format yourname@example.com Please provide an email address that follows the format yourname@example.com
Date is required No date has been provided, please provide a date
Date does not match the required UTC format
Please provide a date that follows the format Y-m-d H:i:s, e.g. 2021-04-15 04:29:42
Country can only contain letters
The country name your provided contains other characters than letters. Please enter the country name in ISO 3166-1 alpha-2 format
Country may not be greater than 2 characters
The country name your provided contains more than 2 characters. Please enter the country name in ISO 3166-1 alpha-2 format
Order id is required No order id has been provided, please enter and order id
Order id must be an integer The order id you provided is not an integer, please enter an integer for the order id
Other Validation Messages
Unauthenticated
The Bearer token is not correct. It should follow this format: Bearer {API key}. It most likely means that the API key you provided does not match your Nudgify account. You can find your API key in your Nudgify account.
Authorization Failure, Invalid Site Key
The Site key you provided does not match your Nudgify account. You can find your Site key in your Nudgify account
Forbidden, REST API integration is not enabled
Nudgify has not enabled the API for its users. Please contact Nudgify support to inquire about this
Please configure the REST API to the nudges in order to use this data
You have not enabled the REST API feature in your Nudge set-up. In your Nudgify account, go to a Sign-up or Purchase Nudge> Configure REST API > I’ve done it
REST API integration is disabled on your site. Please contact support
The API integration has been disabled on your site. Please contact Nudgify support so we can investigate
Upgrade your plan to use the REST API REST API feature is not available in the Lite plan. Please upgrade to use it

If you have any questions or comments about our API, please don’t hesitate to get in touch via our support chat.

Updated on April 23, 2021

Was this article helpful?

Related Articles