Updated in For Developers

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.

Our REST API requires some coding and is meant to be used by developers. Are you not a developer and do you not have access to one? It might be better to choose one of the other integration options to connect your Sign-ups.

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

Activate the REST API as data source

Before you send your request, you need to enable the REST API in your Nudgify account. Follow these steps to activate the REST API.

  • Add a Sign-up Nudge to your Stream. Select the REST API from the dropdown of data sources, and click “Configure”.

rest api configure

  • This triggers a pop up that invited you to click the “Enable REST API button”. Click this button to enable the REST API for you Nudgify account.

  • The REST API is now enabled and you can send your request. Follow the steps below to send sign-up data to Nudgify via our REST API.

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.

FieldTypeRequired?Description
site_keyuuidrequiredThe id we use to identify your site
conversionsarray or nullrequired
We use this to identify the type of Nudge we send the data to, in this case: the Sign-Up Nudge
datedate (follow the format Y-m-d H:i:s)requiredThe 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
emailemailoptionalThe email address of the user to identify that there has been a new conversion
first_namestring or nulloptionalThe first name of the user, to show in the Nudge
last_namestring or nulloptionalThe last name of the user, to show in the Nudge
ipstring or nulloptionalThe ip address of the user, to show the location in case city/state/country are not available
citystring or nulloptionalThe city of the user, to show in the Nudge
statestring or nulloptionalThe state of the user, to show in the Nudge
countrystring or null (Max characters 2 e.g: GB or US)optionalThe 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": "[email protected]",
    "first_name": "John",
    "last_name": "Mendes",
    "ip": "92.21.8.106",
    "city": "Houston",
    "state": "Texas",
    "country": "US"
    },
    {
    "first_name": "Cicilia",
    "last_name": "Mendes",
    "email": "[email protected]",
    "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":"[email protected]",
    "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" ]
}
FieldTypeDescription
messagestringIndicates that the request has been successful
dataarrayIn case of success shows the ids of all the records saved in our database
errorsarrayIn 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 SummaryDescription
200 – OKEverything worked as expected
400 – Bad Request
The request was unacceptable, often due to missing a required parameter
401 – UnauthorizedNo valid API key provided
403 – Forbidden
The API key doesn’t have permissions to perform the request
404 – Not FoundThe requested resource doesn’t exist
500, 502, 503, 504 – Server ErrorsSomething went wrong on Nudgify’s end

Error Messages

Error MessageDescription
Expected Field Validation Error Messages
Bad RequestIn 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 requiredNo email address has been provided, please provide an email address
Email does not match the required format [email protected]Please provide an email address that follows the format [email protected]
Date is requiredNo 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 requiredNo order id has been provided, please enter and order id
Order id must be an integerThe order id you provided is not an integer, please enter an integer for the order id

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 APIREST 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.

Tags: sitekey

Nudgify social proof notification types including customer reviews low stock alerts recent purchases and free delivery nudges

Ready to Boost Your Conversion Instantly with Nudgify?

Turn your website visitors into customers with real-time Social Proof and FOMO Nudges.

Get Started NowCircle arrow call to action icon

Test-Drive for 7 days.
No credit card needed.