This article covers the basics of our Standard API including a general overview, the setup steps, and some frequently asked questions.
This is our legacy public API. To read about our newer public API, click here.
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.
- First, a potential customer fills out the "contact us" form, providing their name, phone number, and email.
- 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).
- This API request contains all of the customer's contact information that was submitted through the website form.
- Hatch receives the customer's contact information and creates a new contact in the Hatch workspace.
- The contact is instantly added to a matching Hatch campaign and the first message is sent immediately to the customer.
- 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.
- Confirm with your development team that your software or website can support the specifications listed below.
- Speak with your Hatch Customer Success Manager or contact support to collect the following pieces of information that are required to send API requests:
- Your Department ID
- Your Hatch API Key
- 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.
- 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 |
|
|
String |
The contact's email |
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.
All additional custom properties will have their values imported as strings. If you need these imported as another data type, speak with your Hatch Customer Success Manager or contact support.
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",
"model": "toyota",
},
}
Timestamp Strings
When you send a createdAt or updatedAt value in your request, the value must use one of the following formats:
2006-01-02T15:04:05-0700
2006-01-02T15:04:05-07:00
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:
- Send a request to the Standard API with some test data.
- For example, if you connected your webform to the Standard API, simply submit some test data using your webform.
- Open the contacts page in your Hatch workspace.
- Verify that one of the contacts in the list contains the test data that you submitted.
- If you have a configured campaign, verify that the contact was launched into the campaign.
- 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.