Hatch contacts API
The contacts API from Hatch — 1 operation(s) for contacts.
OpenAPI Specification
openapi: 3.0.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:
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
nullable: true
type: string
externalContactID:
description: The contact ID from your system.
nullable: true
type: string
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
nullable: true
type: string
externalID:
description: The lead ID from your system.
nullable: true
type: string
externalUpdatedAt:
description: The contact's updated timestamp from your system (ISO 8601).
format: date-time
nullable: true
type: string
firstName:
description: The contact's first name.
nullable: true
type: string
lastName:
description: The contact's last name.
nullable: true
type: string
phoneNumber:
description: The contact's phone number.
nullable: true
type: string
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).
nullable: true
type: string
title: UpsertContactParams
type: object
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
securitySchemes:
authorization:
scheme: bearer
type: http