Standard API

This article covers the basics of our Standard API including a general overview, the setup steps, and some frequently asked questions.

Overview

Hatch’s standard API allows your business to send lead information into Hatch from any source that can support a POST API endpoint. 

Through our integration, leads sent to the API endpoint are instantly pulled into Hatch and placed into your Hatch campaign (if applicable) using text, email, and voicemail communication. 

Here's an example of how it could be used

In this example, the Standard API is being used to receive leads from a "contact us" form on a company's website.

  1. First, a potential customer fills out the "contact us" form, providing their name, phone number, and email.
  2. When the form is submitted on the company website, the website sends a POST request to the Hatch Standard API (this API request is detailed below).
    1. This API request contains all of the customer's contact information that was submitted through the website form.
  3. Hatch receives the customer's contact information and creates a new contact in the Hatch workspace.
  4. The contact is instantly added to a matching Hatch campaign and the first message is sent immediately to the customer.
  5. Once the customer replies to the automated message, the contact is moved to the Hatch board and the conversation can continue with a real person from the company.

How To Set Up

This setup requires that you have experience with web APIs and sending API requests. You may need assistance from your development team.

  1. Confirm with your development team that your software or website can support the specifications listed below.
  2. Speak with your Hatch Customer Success Manager or contact support to collect the following pieces of information that are required to send API requests:
    1. Your Department ID
    2. Your Hatch API Key
  3. Use the specifications below to send a POST request to the Hatch Standard API endpoint URL. Make sure to replace the placeholders for Department ID and Hatch API Key with the values you retrieved in step 2.
  4. Once configured, speak with your Hatch Customer Success Manager or contact support to configure a Hatch campaign to launch your incoming contacts.

Endpoint URL

Send a POST request to this endpoint:

https://app.usehatchapp.com/api/webhooks/{Department ID}/newlead

Request Headers

Keep your Hatch API Key secret. Do not place these request headers in your website HTML or anywhere public.

X-API-KEY: {Hatch API Key}
Content-Type: application/json

Request Body Properties

The following properties are required for every request:

Property Name Property Type Description
phoneNumber
String

The contact's phone number
Only required when "email" is not included

email
String

The contact's email
Only required when "phoneNumber" is not included

source
String The external source assigned to the Hatch contact
This should be the same for all of your requests

The following properties are optional for every request:

Property Name Property Type Description
firstName
String The contact's first name
lastName
String The contact's last name
id
String The ID from your system
contactID
String The contact's ID from your system
status
String The contact's status from your system
This can be whatever is helpful for your workflow
createdAt
Timestamp String
(see below)
The contact's creation timestamp from your system
updatedAt
Timestamp String
(see below)
The contact's updated timestamp from your system

You may also add any additional custom properties to the request body that you want  included on your Hatch contact.

Your custom properties may send any valid JSON value. Multidimensional values will be flattened upon consumption.

Here is an example request body:

{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "8048675309",
"email": "testjohndoe@test.com",
"source": "my_company_name",
"status": "my_lead_status",
"contactID": "1001123123900",
"createdAt": "2020-01-02T15:04:05-0700",
"myCustomNestedObject": {
"color": "red",
"soldOn": "2020-01-02T15:04:05-0700",
},
}

Request Body Timestamp Strings

When you send a timestamp value in your request, the value must use one of the following formats:

Go Layout Java Notation C Notation
2006-01-02 yyyy-MM-dd %F
20060102 yyyyMMdd %Y%m%d
January 02, 2006 MMMM dd, yyyy %B %d, %Y
02 January 2006 dd MMMM yyyy %d %B %Y
02-Jan-2006 dd-MMM-yyyy %d-%b-%Y
01/02/06 MM/dd/yy %D
01/02/2006 MM/dd/yyyy %m/%d/%Y
010206 MMddyy %m%d%y
Jan-02-06 MMM-dd-yy %b-%d-%y
Jan-02-2006 MMM-dd-yyyy %b-%d-%Y
06 yy %y
Mon EEE %a
Monday EEEE %A
Jan-06 MMM-yy %b-%y
2006-01-02T15:04:05 yyyy-MM-dd'T'HH:mm:ss %FT%T
2006-01-02T15:04:05-0700 yyyy-MM-dd'T'HH:mm:ssZ %FT%T%z
2 Jan 2006 15:04:05 d MMM yyyy HH:mm:ss %e %b %Y %T
2 Jan 2006 15:04 d MMM yyyy HH:mm %e %b %Y %R
Mon, 2 Jan 2006 15:04:05 MST EEE, d MMM yyyy HH:mm:ss z %a, %e %b %Y %T %Z

How To Verify

Once you have set up the connection, requests sent to the Standard API will automatically create contacts in Hatch. You can test this easily by performing the following steps:

  1. Send a request to the Standard API with some test data.
    1. For example, if you connected your webform to the Standard API, simply submit some test data using your webform.
  2. Open the contacts page in your Hatch workspace.
  3. Verify that one of the contacts in the list contains the test data that you submitted.
  4. If you have a configured campaign, verify that the contact was launched into the campaign.
    1. If you are unsure about this step, speak with your Hatch Customer Success Manager or contact support.

Frequently Asked Questions

Why is instant lead engagement important?

Instant lead engagement (also known as "Speed to Lead") is extremely important when it comes to your new leads. The first company to get to a new lead wins!

Who can use the Standard API?

The Standard API is available to all Hatch users. There is no additional fee to use the endpoint. Our team just needs to work with you to provide the necessary information to get started. 

How long does it take to get set up? 

Once your team has configured your software or website to send to the Standard API, you're ready to go! Just make sure that you talk to your Customer Success Manager about what campaign you want to put those incoming leads into.

What other lead source or Speed to Lead integrations do you offer? 

We offer lead engagement integrations with many other lead sources. Check out the app marketplace in your Hatch workspace or visit our website to see the full list.