Hatchbuck API

https://sandbox.hatchbuck.com/api/dist/
Admin
REST API documentation for Hatchbuck, a CRM platform providing endpoints for user management,...
Tokens:12,719
Snippets:63
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### get /deals/GetDealStageHistory

Source: https://sandbox.hatchbuck.com/api/dist

Fetches the stage history for a specific deal.

```APIDOC
## GET /deals/GetDealStageHistory

### Description
Get stage history of a specific deal.

### Method
GET

### Endpoint
/deals/GetDealStageHistory

### Parameters
#### Query Parameters
- **dealId** (string) - Required - The ID of the deal.
- **SalesRepId** (string) - Optional - Sales Representative ID.
- **pageNumber** (integer) - Optional - The page number for pagination.
- **pageSize** (integer) - Optional - The number of items per page.
- **api_key** (string) - Required - Account API key.

### Response
#### Success Response (200)
- **Deal stage history successfully returned**

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### get /deals/GetDeals

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves a paginated list of deals with filtering capabilities.

```APIDOC
## GET /deals/GetDeals

### Description
Get a paginated list of deals with filtering.

### Method
GET

### Endpoint
/deals/GetDeals

### Parameters
#### Query Parameters
- **pageNumber** (integer) - Optional - The page number for pagination.
- **pageSize** (integer) - Optional - The number of items per page.
- **SalesRepId** (string) - Optional - Sales Representative ID for filtering.
- **api_key** (string) - Required - Account API key.

### Response
#### Success Response (200)
- **List of deals successfully returned**

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### get /user

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves a list of active users for the authenticated account.

```APIDOC
## GET /user

### Description
Get user list. Returns the list of active users for the authenticated account.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Account API key.

### Response
#### Success Response (200)
- **User list retrieved successfully**

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### get /settings/source

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves all configured contact sources. This endpoint returns a list of available sources, each with a name and unique ID.

```APIDOC
## get /settings/source

### Description
Retrieves all configured contact sources. This endpoint returns a list of available sources, each with a name and unique ID.

### Method
GET

### Endpoint
/settings/source

### Response
#### Success Response (200)
- **name** (string, optional) - Source name from system
- **id** (string, optional) - Unique identifier

### Response Example
```json
[
  {
    "name": "string",
    "id": "string"
  }
]
```
```

--------------------------------

### post /contact/{email_address_or_contact_ID}/campaign

Source: https://sandbox.hatchbuck.com/api/dist

Start a campaign for a specific contact. Requires the contact's email address or ID and campaign details.

```APIDOC
## POST /contact/{email_address_or_contact_ID}/campaign

### Description
Start campaign for a specific contact.

### Method
POST

### Endpoint
/contact/{email_address_or_contact_ID}/campaign

### Parameters
#### Path Parameters
- **email_address_or_contact_ID** (string) - Required - Must provide Contact ID or Email Address of contact

#### Request Body
- **body** (array) - Required - User needs to specify either Campaign ID or name of the Campaign that needs to be started for the Contact.
  - **id** (string, optional) - unique id of campaign
  - **name** (string, optional) - name of campaign

### Request Example
```json
[
  {
    "id": "string",
    "name": "string"
  }
]
```

### Response Messages
- **201** - Campaign Started
- **400** - Bad Request - Not found, invalid parameters or campaign already running for contact
- **405** - Method Not Allowed
```

--------------------------------

### get /settings/temperature

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves all configured contact temperatures. This endpoint returns a list of available temperatures, each with a name and unique ID.

```APIDOC
## get /settings/temperature

### Description
Retrieves all configured contact temperatures. This endpoint returns a list of available temperatures, each with a name and unique ID.

### Method
GET

### Endpoint
/settings/temperature

### Response
#### Success Response (200)
- **name** (string, optional) - Temperature name
- **id** (string, optional) - Unique temperature id

### Response Example
```json
[
  {
    "name": "string",
    "id": "string"
  }
]
```
```

--------------------------------

### PurchaseOrder Model Example

Source: https://sandbox.hatchbuck.com/api/dist

This JSON object represents the structure of a PurchaseOrder. Required fields include marketingOptInInd, email, status, and at least one orderLineItem. Phones are required when creating a new user.

```json
{
  "marketingOptInInd": "string",
  "firstName": "string",
  "externalOrderId": 0,
  "email": "string",
  "lastName": "string",
  "orderLineItem": [
    {
      "quantity": 0,
      "pricePerUnit": 0,
      "productName": "string",
      "categoryName": "string"
    }
  ],
  "phones": [
    {
      "id": "string",
      "number": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "status": {
    "name": "string",
    "id": "string"
  }
}
```

--------------------------------

### get /EmailPerformance/GetEmailPerformance

Source: https://sandbox.hatchbuck.com/api/dist

Fetches email performance metrics for a specified date range.

```APIDOC
## GET /EmailPerformance/GetEmailPerformance

### Description
Get email performance metrics for a date range.

### Method
GET

### Endpoint
/EmailPerformance/GetEmailPerformance

### Parameters
#### Query Parameters
- **SalesRepId** (string) - Optional - Sales Representative ID.
- **FromDate** (date) - Optional - Start date for the performance metrics.
- **ToDate** (date) - Optional - End date for the performance metrics.
- **pageNumber** (integer) - Optional - The page number for pagination.
- **pageSize** (integer) - Optional - The number of items per page.
- **api_key** (string) - Required - Account API key.

### Response
#### Success Response (200)
- **Email performance data successfully returned**

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### get /settings/contactStatus

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves all configured contact statuses. This endpoint returns a list of available statuses, each with a name and unique ID.

```APIDOC
## get /settings/contactStatus

### Description
Retrieves all configured contact statuses. This endpoint returns a list of available statuses, each with a name and unique ID.

### Method
GET

### Endpoint
/settings/contactStatus

### Response
#### Success Response (200)
- **name** (string, optional) - Given name for status
- **id** (string, optional) - Unique id for status

### Response Example
```json
[
  {
    "name": "string",
    "id": "string"
  }
]
```
```

--------------------------------

### get /user/{userId}

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves user data by their encrypted ID.

```APIDOC
## GET /user/{userId}

### Description
Get user by ID (encrypted). Returns the user data whose encrypted ID is provided in the path.

### Method
GET

### Endpoint
/user/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - Encrypted user ID.
#### Query Parameters
- **api_key** (string) - Required - Account API key (passed via query string).

### Response
#### Success Response (200)
- **User found.**

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Contact Search Criteria Example

Source: https://sandbox.hatchbuck.com/api/dist

This JSON object defines the criteria for searching contacts. It can include contact ID, first name, last name, and email addresses.

```json
{
  "contactId": "string",
  "firstName": "string",
  "lastName": "string",
  "emails": [
    {
      "address": "string"
    }
  ]
}
```

--------------------------------

### get /contact/{email_address_or_contact_ID}/campaign

Source: https://sandbox.hatchbuck.com/api/dist

Retrieve all campaigns associated with a specific contact. Requires the contact's email address or ID.

```APIDOC
## GET /contact/{email_address_or_contact_ID}/campaign

### Description
Retrieve all campaigns associated with a specific contact.

### Method
GET

### Endpoint
/contact/{email_address_or_contact_ID}/campaign

### Parameters
#### Path Parameters
- **email_address_or_contact_ID** (string) - Required - Must provide Contact ID or Email Address of contact

### Response
#### Success Response (200)
- **id** (string, optional) - unique id of campaign
- **name** (string, optional) - name of campaign
- **step** (number, optional) - campaign step the contact is currently on

### Response Example
```json
[
  {
    "id": "string",
    "name": "string",
    "step": 0
  }
]
```
```

--------------------------------

### Get Contact Statuses

Source: https://sandbox.hatchbuck.com/api/dist

Retrieves all configured contact statuses. The response is an array of status objects, each containing a name and an ID.

```json
[
  {
    "name": "string",
    "id": "string"
  }
]
```

--------------------------------

### get /contact/{email_address_or_contact_ID}/tags

Source: https://sandbox.hatchbuck.com/api/dist

Retrieve all tags associated with a specific contact. Requires the contact's email address or ID.

```APIDOC
## GET /contact/{email_address_or_contact_ID}/tags

### Description
Retrieve all tags associated with a specific contact.

### Method
GET

### Endpoint
/contact/{email_address_or_contact_ID}/tags

### Parameters
#### Path Parameters
- **email_address_or_contact_ID** (string) - Required - Must provide Contact ID or Email Address of contact

### Response
#### Success Response (200)
Array of 1 or more contacts (Tag)

#### Response Example
[
  null
]
```

--------------------------------

### post /contact

Source: https://sandbox.hatchbuck.com/api/dist

Creates a new contact in the system.

```APIDOC
## POST /contact

### Description
Creates a new contact in the system.

### Method
POST

### Endpoint
/contact

### Parameters
#### Request Body
- **contact search criteria** (object) - Required - Body of the request containing contact details.
  - **contactId** (string, optional): Unique identifier for contacts.
  - **firstName** (string, optional): contact's first name.
  - **lastName** (string, optional): contact's last name.
  - **emails** (Array[object], optional): Any email addresses you're searching for.
    - **address** (string, optional): email address

### Request Example
```json
{
  "contactId": "string",
  "firstName": "string",
  "lastName": "string",
  "emails": [
    {
      "address": "string"
    }
  ]
}
```

### Response
#### Success Response (200)
- **contact** (object) - Description of the created contact.

#### Error Response
- **400** - Contact not found
- **401** - Security error
- **500** - Unspecified error
```

--------------------------------

### post /contact/order

Source: https://sandbox.hatchbuck.com/api/dist

Create a new purchase order for a new or existing contact.

```APIDOC
## POST /contact/order

### Description
Create a new purchase order for a new or existing contact.

### Method
POST

### Endpoint
/contact/order

### Response
#### Success Response (200)
- **message** (string, optional)

### Response Example
```json
{
  "message": "string"
}
```
```

--------------------------------

### Create Purchase Order Response Model

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure for the response when creating a purchase order, which may contain an error message.

```json
{
  "message": "string"
}
```

--------------------------------

### Create Purchase Order

Source: https://sandbox.hatchbuck.com/api/dist

Allows the creation of a new purchase order. It requires specific contact information and order details. Phones are mandatory when creating a new contact.

```APIDOC
## POST /purchase-orders

### Description
Creates a new purchase order. Requires contact details like email, marketing opt-in status, order type, and status. Phone numbers are mandatory if a new contact is being created.

### Method
POST

### Endpoint
/purchase-orders

### Parameters
#### Request Body
- **marketingOptInInd** (string, optional): Must be 'true' or 'false'.
- **firstName** (string, optional): Used if the contact does not exist.
- **externalOrderId** (number, optional): Correlates to the order ID in your source system.
- **email** (string, optional): Used to find or create the contact.
- **lastName** (string, optional): Used if the contact does not exist.
- **orderLineItem** (Array[OrderLineItem], optional): At least one item is required. All fields within OrderLineItem are required.
- **phones** (Array[Phone], optional): Number and type are required if included. Only used when creating a contact.
- **status** (ContactStatus, optional): Must be a valid contact status.

### Request Example
```json
{
  "marketingOptInInd": "string",
  "firstName": "string",
  "externalOrderId": 0,
  "email": "string",
  "lastName": "string",
  "orderLineItem": [
    {
      "quantity": 0,
      "pricePerUnit": 0,
      "productName": "string",
      "categoryName": "string"
    }
  ],
  "phones": [
    {
      "id": "string",
      "number": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "status": {
    "name": "string",
    "id": "string"
  }
}
```

### Response
#### Success Response (200)
- **purchaseOrder** (PurchaseOrder): The created purchase order details.

#### Response Example
```json
{
  "marketingOptInInd": "string",
  "firstName": "string",
  "externalOrderId": 0,
  "email": "string",
  "lastName": "string",
  "orderLineItem": [
    {
      "quantity": 0,
      "pricePerUnit": 0,
      "productName": "string",
      "categoryName": "string"
    }
  ],
  "phones": [
    {
      "id": "string",
      "number": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "status": {
    "name": "string",
    "id": "string"
  }
}
```

#### Error Handling
- **400 Bad Request**: Not found or invalid parameters.
- **405 Method Not Allowed**: The HTTP method used is not allowed for this endpoint.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

--------------------------------

### Create Contact Note

Source: https://sandbox.hatchbuck.com/api/dist

Creates a new note on a contact record. Requires a JSON body with note details such as subject and body. Optional fields include creation date, sales rep information, and flags to copy to company or update last contacted date.

```json
{
  "subject": "string",
  "body": "string",
  "createdDateTime": "string",
  "salesRep": {
    "username": "string",
    "id": "string"
  },
  "copyToCompany": true,
  "updateLastContactedDate": true
}
```

--------------------------------

### post /contact/{email_address_or_contact_ID}/notes

Source: https://sandbox.hatchbuck.com/api/dist

Creates a new note on a contact record. This operation allows for adding notes with a subject, body, and optional fields like sales rep, copy to company, and update last contacted date.

```APIDOC
## post /contact/{email_address_or_contact_ID}/notes

### Description
Creates a new note on a contact record. This operation allows for adding notes with a subject, body, and optional fields like sales rep, copy to company, and update last contacted date.

### Method
POST

### Endpoint
/contact/{email_address_or_contact_ID}/notes

### Parameters
#### Path Parameters
- **email_address_or_contact_ID** (string) - The email address or contact ID of the contact to add a note to.

#### Request Body
- **subject** (string, optional) - Subject line for the note.
- **body** (string, optional) - Body of the note.
- **createdDateTime** (string, optional) - Date/time of the note in ISO-8601 format (e.g., 2018-11-21T18:37:00-06:00).
- **salesRep** (object, optional) - Information about the sales representative.
  - **username** (string, optional) - Username of the sales rep.
  - **id** (string, optional) - Unique ID of the sales rep.
- **copyToCompany** (boolean, optional) - Copy this note to the contact's associated company record.
- **updateLastContactedDate** (boolean, optional) - Update the 'last contacted date' value on the contact record.

### Request Example
```json
{
  "subject": "string",
  "body": "string",
  "createdDateTime": "string",
  "salesRep": {
    "username": "string",
    "id": "string"
  },
  "copyToCompany": true,
  "updateLastContactedDate": true
}
```

### Response
#### Success Response (200)
Success

### Response Example
```json
{
  "subject": "string",
  "body": "string",
  "createdDateTime": "string",
  "salesRep": {
    "username": "string",
    "id": "string"
  },
  "copyToCompany": true,
  "updateLastContactedDate": true
}
```
```

--------------------------------

### InstantMessaging Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for an InstantMessaging object, used within the Contact object.

```APIDOC
## InstantMessaging Object

### Description
Represents an instant messaging address for a contact.

### Fields
- **id** (string, optional): unique identifier for contact's IM address
- **address** (string, optional): contact's IM address
- **type** (string, optional): type of IM address
- **typeId** (string, optional): unique id of this type from your configuration
```

--------------------------------

### Campaign Response Model for Contact

Source: https://sandbox.hatchbuck.com/api/dist

Represents the structure for campaigns associated with a contact, including ID, name, and current step.

```json
[
  {
    "id": "string",
    "name": "string",
    "step": 0
  }
]
```

--------------------------------

### Campaign Request Model

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure for campaign requests, specifying either campaign ID or name.

```json
[
  {
    "id": "string",
    "name": "string"
  }
]
```

--------------------------------

### InstantMessaging Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of an InstantMessaging object, used within the Contact object to store IM details.

```APIDOC
## InstantMessaging Object

### Description
Represents an instant messaging address for a contact.

### Fields
- **id** (string, optional): Unique identifier for the contact's IM address.
- **address** (string, optional): The contact's IM address.
- **type** (string, optional): The type of IM address.
- **typeId** (string, optional): The unique ID of this type from your configuration.
```

--------------------------------

### Website Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for a Website object, used within the Contact object.

```APIDOC
## Website Object

### Description
Represents a website associated with a contact.

### Fields
- **id** (string, optional): unique id for this website
- **websiteUrl** (string, optional): url
```

--------------------------------

### post /contact/{email_address_or_contact_ID}/tags

Source: https://sandbox.hatchbuck.com/api/dist

Add tags to a specific contact. Requires the contact's email address or ID and the tag(s) to be added.

```APIDOC
## POST /contact/{email_address_or_contact_ID}/tags

### Description
Add tags to a specific contact.

### Method
POST

### Endpoint
/contact/{email_address_or_contact_ID}/tags

### Parameters
#### Path Parameters
- **email_address_or_contact_ID** (string) - Required - Must provide Contact ID or Email Address of contact

#### Request Body
- **body** (Array[TagRequest]) - Required - User needs to specify either id or name of the Tag that needs to be added to the Contact.

### Response
#### Success Response (201)
Tag(s) added

#### Error Response (400)
Bad Request - Not found or invalid parameters
```

--------------------------------

### Website Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of a Website object, used within the Contact object to store website URLs.

```APIDOC
## Website Object

### Description
Represents a website associated with a contact.

### Fields
- **id** (string, optional): Unique identifier for this website.
- **websiteUrl** (string, optional): The URL of the website.
```

--------------------------------

### post /contact/search

Source: https://sandbox.hatchbuck.com/api/dist

Searches for contacts based on provided criteria. If a contactId is specified, only that parameter is used; otherwise, AND criteria are applied to other supplied parameters.

```APIDOC
## POST /contact/search

### Description
Contact search. Used to search for contacts, if contactId is specified then it will only use that parameter, otherwise it will use AND criteria for other supplied parameters.

### Method
POST

### Endpoint
/contact/search

### Parameters
#### Request Body
- **contactId** (string) - Optional - The ID of the contact to search for.
- Other search parameters (type and data type depend on specific criteria, not detailed in source).

### Request Example
{
  "example": "{\"contactId\": \"some_id\"}"
}

### Response
#### Success Response (200)
- **Contact search results returned.**

### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Contact Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

This snippet details the structure of a Contact object, which is returned as an array of one or more contacts. It includes fields for contact identification, personal information, associated entities like emails, phones, tags, campaigns, and more.

```APIDOC
## Contact Object

### Description
Represents a contact within the system. This is typically returned as an array of Contact objects.

### Model
Inline Model [
  Inline Model 1
]

Inline Model 1 {
  contactId (string, optional): unique identifier for contact
  firstName (string, optional): contact's first name
  lastName (string, optional): contact's last name
  title (string, optional): contact's title at their place of business
  company (string, optional): company name
  emails (Array[Email], optional): emails
  phones (Array[Phone], optional): phones
  tags (Array[Tag], optional): tags
  campaigns (Array[Campaign], optional): current and past campaigns
  status (ContactStatus, optional)
  temperature (ContactTemperature, optional)
  salesRep (ContactSalesRep, optional)
  addresses (Array[StreetAddress], optional): street addresses
  subscribed (boolean, optional): email marketing opt-in
  timezone (string, optional): timezone
  socialNetworks (Array[SocialNetwork], optional): social network links for contact
  instantMessaging (Array[InstantMessaging], optional): instant messaging ids
  website (Array[Website], optional): websites for this contact
  source (object, optional): source for this contact
  referredBy (string, optional): optional contact name who may have referred this contact
  customFields (Array[CustomField], optional): custom fields for this contact
}

### Associated Models

#### Email
{
  id (string, optional): unique email id
  address (string, optional): email address
  type (string, optional): work/home/other
  typeId (string, optional): system id of the email type
}

#### Phone
{
  id (string, optional): unique phone id
  number (string, optional): phone number
  type (string, optional): work/home/other
  typeId (string, optional): system id of the phone type
}

#### Tag
{}

#### Campaign
{
  id (string, optional): unique id of campaign
  name (string, optional): name of campaign
  step (number, optional): campaign step the contact is currently on
}

#### ContactStatus
{
  name (string, optional): given name for status
  id (string, optional): unique id for status
}

#### ContactTemperature
{
  name (string, optional): temperature name
  id (string, optional): unique temperature id
}

#### ContactSalesRep
{
  username (string, optional): username of sales rep
  id (string, optional): unique id of sales rep
}

#### StreetAddress
{
  id (string, optional): unique street address id
  street (string, optional): street address
  city (string, optional): city
  state (string, optional): state
  zip (string, optional): zip code
  country (string, optional): country, must match Hatchbuck's country list
  type (string, optional): work, home, etc...
  typeId (string, optional): unique id of this address type
}

#### SocialNetwork
{
  id (string, optional): unique id for contact's social network
  address (string, optional): URL for social network
  type (string, optional): type of social network such as facebook or twitter
  typeId (string, optional): unique id for this social network type
}

#### InstantMessaging
{
  id (string, optional): unique identifier for contact's IM address
  address (string, optional): contact's IM address
  type (string, optional): type of IM address
  typeId (string, optional): unique id of this type from your configuration
}

#### Website
{
  id (string, optional): unique id for this website
  websiteUrl (string, optional): url
}

#### CustomField
{
  name (string, optional): unique custom field name for this contact
  type (string, optional): can be Text, Dropdown, MText, Number or Date
  value (string, optional): value of custom field. regardless of datatype specified it will always return as a string value in this field
}
```

--------------------------------

### Contact Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields available for a Contact object, including personal information, communication details, and associated metadata.

```APIDOC
## Contact Object

### Description
Represents a contact within the system, storing their personal details, communication channels, and other relevant information.

### Fields
- **contactId** (string, optional): unique identifier for contact
- **firstName** (string, optional): contact's first name
- **lastName** (string, optional): contact's last name
- **title** (string, optional): contact's title at their place of business
- **company** (string, optional): company name
- **emails** (Array[Email], optional): list of email addresses associated with the contact
- **phones** (Array[Phone], optional): list of phone numbers associated with the contact
- **tags** (Array[Tag], optional): list of tags applied to the contact
- **campaigns** (Array[Campaign], optional): list of current and past campaigns the contact is involved in
- **status** (ContactStatus, optional): the current status of the contact
- **temperature** (ContactTemperature, optional): the temperature of the contact (e.g., hot, cold)
- **salesRep** (ContactSalesRep, optional): the sales representative assigned to the contact
- **addresses** (Array[StreetAddress], optional): list of street addresses for the contact
- **subscribed** (boolean, optional): indicates if the contact is subscribed to email marketing
- **timezone** (string, optional): the contact's timezone
- **socialNetworks** (Array[SocialNetwork], optional): list of social network links for the contact
- **instantMessaging** (Array[InstantMessaging], optional): list of instant messaging IDs for the contact
- **website** (Array[Website], optional): list of websites associated with the contact
- **source** (object, optional): information about the source of the contact
- **referredBy** (string, optional): the name of the contact who may have referred this contact
- **customFields** (Array[CustomField], optional): a list of custom fields associated with the contact
```

--------------------------------

### Contact Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of a Contact object, including its fields, data types, and optionality. This is used for creating or updating contacts.

```APIDOC
## Contact Object

### Description
Represents a contact within the Hatchbuck system. This object is used in requests to create or update contact details.

### Parameters
#### Request Body
- **contactId** (string, optional): unique identifier for contact
- **firstName** (string, optional): contact's first name
- **lastName** (string, optional): contact's last name
- **title** (string, optional): contact's title at their place of business
- **company** (string, optional): company name
- **emails** (Array[Email], optional): emails
- **phones** (Array[Phone], optional): phones
- **campaigns** (Array[Campaign], optional): current and past campaigns
- **status** (ContactStatus, optional)
- **temperature** (ContactTemperature, optional)
- **salesRep** (ContactSalesRep, optional)
- **addresses** (Array[StreetAddress], optional): street addresses
- **subscribed** (boolean, optional): email marketing opt-in
- **timezone** (string, optional): timezone
- **socialNetworks** (Array[SocialNetwork], optional): social network links for contact
- **instantMessaging** (Array[InstantMessaging], optional): instant messaging ids
- **website** (Array[Website], optional): websites for this contact
- **source** (object, optional): source for this contact
- **referredBy** (string, optional): optional contact name who may have referred this contact
- **customFields** (Array[CustomField], optional): custom fields for this contact

### Nested Objects
#### Email
- **id** (string, optional): unique email id
- **address** (string, optional): email address
- **type** (string, optional): work/home/other
- **typeId** (string, optional): system id of the email type

#### Phone
- **id** (string, optional): unique phone id
- **number** (string, optional): phone number
- **type** (string, optional): work/home/other
- **typeId** (string, optional): system id of the phone type

#### Campaign
- **id** (string, optional): unique id of campaign
- **name** (string, optional): name of campaign
- **step** (number, optional): campaign step the contact is currently on

#### ContactStatus
- **name** (string, optional): given name for status
- **id** (string, optional): unique id for status

#### ContactTemperature
- **name** (string, optional): temperature name
- **id** (string, optional): unique temperature id

#### ContactSalesRep
- **username** (string, optional): username of sales rep
- **id** (string, optional): unique id of sales rep

#### StreetAddress
- **id** (string, optional): unique street address id
- **street** (string, optional): street address
- **city** (string, optional): city
- **state** (string, optional): state
- **zip** (string, optional): zip code
- **country** (string, optional): country, must match Hatchbuck's country list
- **type** (string, optional): work, home, etc...
- **typeId** (string, optional): unique id of this address type

#### SocialNetwork
- **id** (string, optional): unique id for contact's social network
- **address** (string, optional): URL for social network
- **type** (string, optional): type of social network such as facebook or twitter
- **typeId** (string, optional): unique id for this social network type

#### InstantMessaging
- **id** (string, optional): unique identifier for contact's IM address
- **address** (string, optional): contact's IM address
- **type** (string, optional): type of IM address
- **typeId** (string, optional): unique id of this type from your configuration

#### Website
- **id** (string, optional): unique id for this website
- **websiteUrl** (string, optional): url

#### CustomField
- **name** (string, optional): unique custom field name for this contact
- **type** (string, optional): can be Text, Dropdown, MText, Number or Date
- **value** (string, optional): value of custom field. regardless of datatype specified it will always return as a string value in this field

### Request Example
```json
{
  "contactId": "string",
  "firstName": "string",
  "lastName": "string",
  "title": "string",
  "company": "string",
  "emails": [
    {
      "id": "string",
      "address": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "phones": [
    {
      "id": "string",
      "number": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "campaigns": [
    {
      "id": "string",
      "name": "string",
      "step": 0
    }
  ],
  "status": {
    "name": "string",
    "id": "string"
  },
  "temperature": {
    "name": "string",
    "id": "string"
  },
  "salesRep": {
    "username": "string",
    "id": "string"
  },
  "addresses": [
    {
      "id": "string",
      "street": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "subscribed": true,
  "timezone": "string",
  "socialNetworks": [
    {
      "id": "string",
      "address": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "instantMessaging": [
    {
      "id": "string",
      "address": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "website": [
    {
      "id": "string",
      "websiteUrl": "string"
    }
  ],
  "source": {},
  "referredBy": "string",
  "customFields": [
    {
      "name": "string",
      "type": "string",
      "value": "string"
    }
  ]
}
```
```

--------------------------------

### put /contact

Source: https://sandbox.hatchbuck.com/api/dist

Updates an existing contact in the system. This endpoint allows for modification of contact details.

```APIDOC
## PUT /contact

### Description
Updates an existing contact in the system. This endpoint allows for modification of contact details.

### Method
PUT

### Endpoint
/contact

### Parameters
#### Request Body
- **contact** (object) - Required - The contact object containing the fields to be updated.

### Response
#### Success Response (200)
- **contact** (object) - Description of the updated contact object.

#### Error Response
- **400** - Bad request - Missing or invalid parameters or email address already exists.
```

--------------------------------

### Contact Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

This JSON structure represents a contact object. It includes fields for personal information, emails, phone numbers, campaign details, status, sales representative, addresses, social networks, instant messaging, websites, source, and custom fields. Use this as a reference when creating or updating contacts.

```json
{
  "contactId": "string",
  "firstName": "string",
  "lastName": "string",
  "title": "string",
  "company": "string",
  "emails": [
    {
      "id": "string",
      "address": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "phones": [
    {
      "id": "string",
      "number": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "campaigns": [
    {
      "id": "string",
      "name": "string",
      "step": 0
    }
  ],
  "status": {
    "name": "string",
    "id": "string"
  },
  "temperature": {
    "name": "string",
    "id": "string"
  },
  "salesRep": {
    "username": "string",
    "id": "string"
  },
  "addresses": [
    {
      "id": "string",
      "street": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "country": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "subscribed": true,
  "timezone": "string",
  "socialNetworks": [
    {
      "id": "string",
      "address": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "instantMessaging": [
    {
      "id": "string",
      "address": "string",
      "type": "string",
      "typeId": "string"
    }
  ],
  "website": [
    {
      "id": "string",
      "websiteUrl": "string"
    }
  ],
  "source": {},
  "referredBy": "string",
  "customFields": [
    {
      "name": "string",
      "type": "string",
      "value": "string"
    }
  ]
}
```

--------------------------------

### Email Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for an Email object, used within the Contact object.

```APIDOC
## Email Object

### Description
Represents an email address associated with a contact.

### Fields
- **id** (string, optional): unique email id
- **address** (string, optional): email address
- **type** (string, optional): type of email (e.g., work, home, other)
- **typeId** (string, optional): system id of the email type
```

--------------------------------

### ContactSalesRep Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for a ContactSalesRep object, used within the Contact object.

```APIDOC
## ContactSalesRep Object

### Description
Represents the sales representative assigned to a contact.

### Fields
- **username** (string, optional): username of sales rep
- **id** (string, optional): unique id of sales rep
```

--------------------------------

### patch /contact/contactinfo

Source: https://sandbox.hatchbuck.com/api/dist

Deletes contact phones, street addresses, and emails by their respective IDs. This operation allows for the selective removal of contact information.

```APIDOC
## patch /contact/contactinfo

### Description
Deletes contact phones, street addresses, and emails by their respective IDs. This operation allows for the selective removal of contact information.

### Method
PATCH

### Endpoint
/contact/contactinfo

### Parameters
#### Request Body
- **contactId** (string, optional) - Unique identifier for contacts.
- **emails** (Array[string], optional) - Set of emails ids.
- **phones** (Array[string], optional) - Set of phones ids.
- **addresses** (Array[string], optional) - Set of street addresses ids.

### Request Example
```json
{
  "contactId": "string",
  "emails": [
    "string"
  ],
  "phones": [
    "string"
  ],
  "addresses": [
    "string"
  ]
}
```

### Response
#### Success Response (204)
No Content

#### Error Response (400)
Bad request - Missing or invalid parameters
```

--------------------------------

### Contact Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of a Contact object, including its unique identifier, personal details, email addresses, phone numbers, tags, campaigns, status, sales representative information, addresses, subscription status, social networks, instant messaging details, websites, source information, referral details, and custom fields.

```APIDOC
## Contact Object

### Description
Represents a contact within the system, storing comprehensive details about an individual.

### Fields
- **contactId** (string, optional): Unique identifier for the contact.
- **firstName** (string, optional): The contact's first name.
- **lastName** (string, optional): The contact's last name.
- **title** (string, optional): The contact's title at their place of business.
- **company** (string, optional): The name of the company the contact is associated with.
- **emails** (Array[Email], optional): A list of email addresses associated with the contact.
- **phones** (Array[Phone], optional): A list of phone numbers associated with the contact.
- **tags** (Array[Tag], optional): A list of tags assigned to the contact.
- **campaigns** (Array[Campaign], optional): Information about current and past campaigns the contact is involved in.
- **status** (ContactStatus, optional): The current status of the contact.
- **temperature** (ContactTemperature, optional): The temperature (e.g., hot, cold) of the contact.
- **salesRep** (ContactSalesRep, optional): Information about the sales representative assigned to the contact.
- **addresses** (Array[StreetAddress], optional): A list of street addresses for the contact.
- **subscribed** (boolean, optional): Indicates whether the contact is subscribed to email marketing.
- **timezone** (string, optional): The timezone of the contact.
- **socialNetworks** (Array[SocialNetwork], optional): Links to the contact's social network profiles.
- **instantMessaging** (Array[InstantMessaging], optional): The contact's instant messaging identifiers.
- **website** (Array[Website], optional): Websites associated with the contact.
- **source** (object, optional): Information about the source of the contact.
- **referredBy** (string, optional): The name of the contact who may have referred this contact.
- **customFields** (Array[CustomField], optional): Any custom fields associated with the contact.
```

--------------------------------

### Phone Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for a Phone object, used within the Contact object.

```APIDOC
## Phone Object

### Description
Represents a phone number associated with a contact.

### Fields
- **id** (string, optional): unique phone id
- **number** (string, optional): phone number
- **type** (string, optional): type of phone number (e.g., work, home, other)
- **typeId** (string, optional): system id of the phone type
```

--------------------------------

### Campaign Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for a Campaign object, used within the Contact object.

```APIDOC
## Campaign Object

### Description
Represents a campaign associated with a contact.

### Fields
- **id** (string, optional): unique id of campaign
- **name** (string, optional): name of campaign
- **step** (number, optional): campaign step the contact is currently on
```

--------------------------------

### ContactTemperature Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of a ContactTemperature object, representing the temperature of a contact.

```APIDOC
## ContactTemperature Object

### Description
Represents the temperature of a contact.

### Fields
- **name** (string, optional): The name of the temperature.
- **id** (string, optional): The unique ID for the temperature.
```

--------------------------------

### ContactTemperature Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the fields for a ContactTemperature object, used within the Contact object.

```APIDOC
## ContactTemperature Object

### Description
Represents the temperature classification of a contact.

### Fields
- **name** (string, optional): temperature name
- **id** (string, optional): unique temperature id
```

--------------------------------

### Hatchbuck API Response Class (Status 200)

Source: https://sandbox.hatchbuck.com/api/dist

This JSON structure represents a successful response from the Hatchbuck API, detailing website information and custom fields.

```json
[
  {
    "id": "string",
    "websiteUrl": "string"
  }
],
"website": [
  {
    "id": "string",
    "websiteUrl": "string"
  }
],
"source": {},
"referredBy": "string",
"customFields": [
  {
    "name": "string",
    "type": "string",
    "value": "string"
  }
]
}
```

--------------------------------

### Email Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of an Email object, used within the Contact object to store email addresses.

```APIDOC
## Email Object

### Description
Represents an email address associated with a contact.

### Fields
- **id** (string, optional): Unique identifier for the email.
- **address** (string, optional): The email address.
- **type** (string, optional): The type of email (e.g., work, home, other).
- **typeId** (string, optional): The system ID for the email type.
```

--------------------------------

### ContactSalesRep Object Structure

Source: https://sandbox.hatchbuck.com/api/dist

Defines the structure of a ContactSalesRep object, representing the sales representative assigned to a contact.

```APIDOC
## ContactSalesRep Object

### Description
Represents the sales representative assigned to a contact.

### Fields
- **username** (string, optional): The username of the sales representative.
- **id** (string, optional): The unique ID of the sales representative.
```

--------------------------------

### delete /contact/{email_address_or_contact_ID}/campaign

Source: https://sandbox.hatchbuck.com/api/dist

Stop campaign for a specific contact. Requires the contact's email address or ID.

```APIDOC
## DELETE /contact/{email_address_or_contact_ID}/campaign

### Description
Stop campaign for a specific contact.

### Method
DELETE

### Endpoint
/contact/{email_address_or_contact_ID}/campaign

### Parameters
#### Path Parameters
- **email_address_or_contact_ID** (string) - Required - Must provide Contact ID or Email Address of contact
```
Tokens:
Raw