Skip to main content
If you are just looking for an API endpoint reference, check out our Swagger documentation.

​
API basics

Hatch’s public API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Our API uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

​
Creating and managing API keys

Before using the API, you will need to create an API key. You can create and manage your API keys in the API Keys tab of the App Marketplace. The key itself is hidden by default. To view a previously-created API key, click the Show button. You can also click the Copy button to copy the API key to your clipboard.

​
How to create a new API key

Follow these steps to create a new API key:
  1. Click the Create API Key button
  2. Enter a label for your API key
  3. Click the Create API Key button

​
How to delete an existing API key

Follow these steps to delete an existing API key:
You will no longer be able to send API requests with an API key once it is deleted
  1. Locate the API key in the list
  2. Click the API key’s delete button
  3. When the confirmation appears, click Yes, delete

​
Authenticating requests

Authentication to the API is performed via Bearer Authentication. You must send an API token in the Authorization header when making requests: 
    Authorization: Bearer `<token>`
So, as an example: 
    Authorization: Bearer af13791e-1fa9-3bae-c42f-c3e123ae7a22

​
Sending contact data

When you send contact data into Hatch, you are required to provide a valid source**** value in the body of the request. You can view and manage your custom sources in the App Marketplace custom sources tab. Once you have created a custom source, you can use its API Source Name as the source value in your request.
Once a custom source is deleted, you will no longer be able to use its API Source Name when sending data through the API
Click here to learn more about custom sources.

​
Errors

Hatch uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a record was not found, a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with Hatch’s servers (these are rare).

​
Endpoints

This is an embedded version of our Swagger endpoint documentation which contains an example of the expected data schema.
Tip: The fields provided in the “details” object are simply examples of fields you can send. The details fields are fully customizable so you may omit or send fields at your discretion.

​
FAQ

Yes— the rate limit is 100 requests per 10 seconds.