New Leads API

Overview

This API is created to solve the use case of creating soft users for Hotwire. A soft user is a user whose entry is added to the customer database but he hasn't yet signed in through the Hotwire website. This user will start receiving Hotwire marketing emails. These users are accepted through an external process in which they have agreed to receive Hotwire emails. New Leads API accepts new customer data as POST request and adds it to the Hotwire database. This API is used to create new leads for Hotwire and subscribe them to Hotwire marketing emails. The POST request should contain the fields mentioned below:-

  • First Name
  • Last Name
  • Email
  • Source Name
  • Gender
  • Age

Use Case

We want to ingest customer account information from qualified Rokt leads so that we can add these users to our active email database and start engaging them through our marketing emails.

Interface Contract

Payload Element / Heading Name

Data Type

Required

Description

Example Input

Notes
firstName String Yes First Name of the customer John
lastName String Yes Last Name of the customer Smith
email String Yes Email will be used to uniquely identify the customer John.Smith@mail.com  
source String
Source where customer registered and accepted to get notification from Rokt partner(Hotwire) e.g. eBay
gender String
valid values M/F F  
age Integer

20

Endpoint and Payload details

Request type: POST

Prod endpoint: https://api.hotwire.com/api/leads?apikey=<place-your-api-key-here>&sig=<place-your-md5-signature>

QA Endpoint: https://api.qa.hotwire.com/api/leads?apikey=<place-your-api-key-here>&sig=<place-your-md5-signature-here>

Request:
The request will be an array of JSON objects containing basic information about the new leads as shown below.
[{
"firstName" : "First",
"lastName" : "Last",
"email" : "test1@email.com",
"source" : "source name",
"gender" : "M",
"age" : 21
},
{
"firstName" : "First",
"lastName" : "Last",
"email" : "test2@email.com",
"source" : "source name",
"gender" : "M",
"age" : 21
}]
Response:

We get the following response once the request is processed. In case of success, it will also send an array containing details of each email that was sent in POST request, whether it was added to the database or not.

200 OK - When user is created successfully
400 Bad Request - User creation fails in case any issue is encountered or response is empty.

Along with the response codes, it also sends a detailed log of each and every user in an array as shown below. In the case of duplicates it the user will not be created and the response returned will be 200 OK:-

 

[
    {
        "email": "test1@email.com",
        "responseCodes": "USER_NOT_CREATED"
    },
    {
        "email": "test2@email.com",
        "responseCodes": "USER_CREATED"
    }
]

MD5 hash:- The MD5 message-digest algorithm is a widely used hash function producing a 128-bit hash value. We use the API key along with the secret key and Unix timestamp to create this signature. This signature is valid for few minutes post which a new signature needs to be created.

Every request should contain the API Key and signature send to the above-mentioned endpoints.

version 44 as of 6 months ago by Abhishek Chawla