Hatch contacts API
The contacts API from Hatch — 1 operation(s) for contacts.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hatch-contacts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Hatch Contacts API
version: '1.0'
servers:
- url: https://api.usehatchapp.com
variables: {}
security:
- authorization: []
tags:
- name: contacts
paths:
/v1/contacts:
post:
callbacks: {}
description: "We will try to create a new contact, and in case that conflicts with an existent one we will update the contact.\n\nThe primary conflict targets are the attributes `phoneNumber` and `email` (with precedence following the listing below).\n\n 1. If the contact `phoneNumber` already exists, we update the contact with the new attribute values.\n 2. If the contact `email` already exists, we update the contact with the new attribute values.\n 3. Neither the `phoneNumber` nor `email` exists we create a new contact generating a new `ID` for that contact.\n\nWe also have a special behavior on the attribute `externalID`.\n\nExternal ID is a unique record identifier from the customer's external system.\nThis value must be unique among all opportunities on a contact (if provided).\nTherefore, an opportunity will be updated if data is ingested with a matching External ID value.\n"
operationId: HatchWeb.V1.Integrations.ContactController.upsert (2)
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertContactParams'
description: Contact upsert params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertContactSuccessfulResponse'
description: Contact upsert success response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/JsonErrorResponse'
description: Unprocessable Entity
summary: Upsert a contact.
tags:
- contacts
put:
callbacks: {}
description: "We will try to create a new contact, and in case that conflicts with an existent one we will update the contact.\n\nThe primary conflict targets are the attributes `phoneNumber` and `email` (with precedence following the listing below).\n\n 1. If the contact `phoneNumber` already exists, we update the contact with the new attribute values.\n 2. If the contact `email` already exists, we update the contact with the new attribute values.\n 3. Neither the `phoneNumber` nor `email` exists we create a new contact generating a new `ID` for that contact.\n\nWe also have a special behavior on the attribute `externalID`.\n\nExternal ID is a unique record identifier from the customer's external system.\nThis value must be unique among all opportunities on a contact (if provided).\nTherefore, an opportunity will be updated if data is ingested with a matching External ID value.\n"
operationId: HatchWeb.V1.Integrations.ContactController.upsert
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertContactParams'
description: Contact upsert params
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertContactSuccessfulResponse'
description: Contact upsert success response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/JsonErrorResponse'
description: Unprocessable Entity
summary: Upsert a contact.
tags:
- contacts
components:
schemas:
UpsertContactSuccessfulResponse:
description: Response for upserting a contact with success
example:
data:
id: 4856cea1-0fdc-458b-9e76-57b9bbd4c891
properties:
data:
description: Data Representation
properties:
id:
description: Contact ID
type: string
type: object
title: UpsertContactSuccessfulResponse
type: object
JsonErrorResponse:
properties:
errors:
items:
properties:
detail:
example: null value where string expected
type: string
source:
properties:
pointer:
example: /data/attributes/petName
type: string
required:
- pointer
type: object
title:
example: Invalid value
type: string
required:
- title
- source
- detail
type: object
type: array
required:
- errors
title: JsonErrorResponse
type: object
UpsertContactParams:
description: The attributes for upserting a contact.
example:
details:
address: contact address
favoriteColor: Blue
email: firstName.lastName@host.com
externalContactID: c1dddbd0-a0d6-477c-815f-30c56312d5dc
externalCreatedAt: '2023-02-06 17:46:25Z'
externalID: 03775ccb-ffd7-48a6-b1c6-0fac96289928
externalUpdatedAt: '2023-02-06 17:46:25Z'
firstName: firstName
lastName: lastName
phoneNumber: '6364618187'
source: custom:my-awesome-source
status: sold
properties:
details:
additionalProperties: true
description: Any additional contact details you may want to include, commonly used for custom-fields.
type: object
email:
description: The contact's email
format: email
type:
- string
- 'null'
externalContactID:
description: The contact ID from your system.
type:
- string
- 'null'
externalCreatedAt:
description: The contact's creation timestamp from your system (ISO 8601). If not given Hatch defaults to the current time Hatch is processing the contact.
format: date-time
type:
- string
- 'null'
externalID:
description: The lead ID from your system.
type:
- string
- 'null'
externalUpdatedAt:
description: The contact's updated timestamp from your system (ISO 8601).
format: date-time
type:
- string
- 'null'
firstName:
description: The contact's first name.
type:
- string
- 'null'
lastName:
description: The contact's last name.
type:
- string
- 'null'
phoneNumber:
description: The contact's phone number.
type:
- string
- 'null'
source:
description: 'The source of the contact.
This is used to identify the source of the contact for building audience segments.
The source must be included in the list of the sources you have configured on Hatch platform.
'
type: string
status:
description: The contact's status from your system (This can be whatever is helpful for your workflow).
type:
- string
- 'null'
title: UpsertContactParams
type: object
securitySchemes:
authorization:
scheme: bearer
type: http