Skip to main content
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.
  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 NameProperty TypeDescription
phoneNumberStringThe contact’s phone number.
Only required when “email” is not included.
emailStringThe contact’s email.
Only required when “phoneNumber” is not included.
sourceStringThe 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 NameProperty TypeDescription
firstNameStringThe contact’s first name
lastNameStringThe contact’s last name
idStringThe ID from your system
contactIDStringThe contact’s ID from your system
statusStringThe contact’s status from your system (can be whatever is helpful for your workflow)
createdAtTimestamp String (see below)The contact’s creation timestamp from your system
updatedAtTimestamp 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": "[email protected]",  
      "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:
  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

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