# HubSpot

### Overview

The Stacksync HubSpot API Proxy provides secure, centralized access to HubSpot APIs through a single HTTPS endpoint.\
You authenticate with your Stacksync service token. Stacksync manages the underlying HubSpot connection.

Use it for on‑demand operational tasks, admin actions, and low‑volume reads/writes.\
For continuous, high‑volume sync, use Stacksync Syncs instead.

Operations:

* [Get records](#get)
* [Add a custom field](#add-a-custom-field-to-a-hubspot-object)
* [Pass Through](#pass-through)

## Get

Retrieve the details of up to 100 records in a single request. The number of records returned matches the number of `ids` provided.

You can optionally specify a `fields` array to control which properties are returned for each record. If `fields` is omitted or an empty array (`"fields": []`), all available fields for each record are included in the response.

{% hint style="info" %}
Supported objects:

* Companies
* Contacts
* Deals
* Feedback submissions
* Line items
* Products
* Quotes
* Discounts
* Fees
* Taxes
* Tickets
* Goals
* Custom objects

Planned:

* Owners
* Associations
* Audit Logs
* Pipelines
* Stages
  {% endhint %}

{% tabs %}
{% tab title="cURL" %}

```url
curl -X POST https://eu.api-proxy.stacksync.com/v1/object/get/Contact \
        -H "Authorization: Bearer your_api_proxy_service_token" \
        -H "Content-Type: application/json" \
        -d '{"data": {"ids": ["227400", "264150"], "fields": ["firstname"]}}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

object_name = "Contact"

url = f"https://eu.api-proxy.stacksync.com/v1/object/get/{object_name}"

data = {
    "data": {
        "ids": ["227400", "227386"],
        "fields": ["firstname"],
    }
}

api_proxy_service_token = "your_api_proxy_service_token"

headers = {
    "Authorization": f"Bearer {api_proxy_service_token}",
    "Content-Type": "application/json",
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const objectName = "Contact";
const url = `https://eu.api-proxy.stacksync.com/v1/object/get/${objectName}`;

const data = {
  data: {
    ids: ["227386", "227400"],
    fields: ["firstname"],
  },
};

const apiProxyServiceToken = "your_api_proxy_service_token";

const headers = {
  Authorization: `Bearer ${apiProxyServiceToken}`,
  "Content-Type": "application/json",
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((json) => console.log(json))
  .catch((error) => console.error(error));

```

{% endtab %}
{% endtabs %}

Example response body:

```json
{
	"data": [
		{
			"archived": false,
			"createdAt": "2024-01-31T13:17:43.128Z",
			"id": "227400",
			"properties": {
				"createdate": "2024-01-31T13:17:43.128Z",
				"firstname": null,
				"hs_object_id": "227400",
				"lastmodifieddate": "2024-02-02T15:05:54.183Z"
			},
			"updatedAt": "2024-02-02T15:05:54.183Z"
		},
		{
			"archived": false,
			"createdAt": "2024-01-31T13:17:43.128Z",
			"id": "227386",
			"properties": {
				"createdate": "2024-01-31T13:17:43.128Z",
				"firstname": null,
				"hs_object_id": "227386",
				"lastmodifieddate": "2024-01-31T13:28:37.746Z"
			},
			"updatedAt": "2024-01-31T13:28:37.746Z"
		}
	]
}
```

### Add a custom field to a HubSpot object

Add a custom field (property) to a HubSpot object. Both standard and custom objects are supported.

Required request body parameters:

* **`name`** – Internal property name used by the API.
* **`label`** – Human‑readable label displayed in the HubSpot UI.
* **`type`** – Underlying data type of the property (for example, string, number, date).
* **`fieldType`** – How the property is rendered in HubSpot (for example, text input, dropdown).
* **`groupName`** – Property group to which the property will belong.

Each `type` supports one or more valid `fieldType` values. Using an incompatible combination will cause the request to fail. For the full list of supported types, fieldTypes, and valid combinations, refer to the HubSpot property settings [documentation](https://developers.hubspot.com/docs/api/crm/properties#property-type-and-fieldtype-values).

{% tabs %}
{% tab title="cURL" %}

```url
curl -X POST https://eu.api-proxy.stacksync.com/v1/object/add_custom_field/<object_name> \
        -H "Authorization: Bearer your_api_proxy_service_token" \
        -H "Content-Type: application/json" \
        -d '{"data": {"name": "field_name", "label": "field_label", "type": "string", "fieldType": "text", "groupName": "companyinformation"}}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {
    "Authorization": "Bearer your_api_proxy_service_token",
    "Content-Type": "application/json",
}

json_data = {
    "data": {
        "name": "field_name",
        "label": "field_label",
        "type": "string",
        "fieldType": "text",
        "groupName": "companyinformation",
    }
}

response = requests.post(
    "https://eu.api-proxy.stacksync.com/v1/object/add_custom_field/<object_name>",
    headers=headers,
    json=json_data,
)
print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
fetch("https://eu.api-proxy.stacksync.com/v1/object/add_custom_field/<object_name>", {
  method: "POST",
  headers: {
    Authorization: "Bearer your_api_proxy_service_token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data: {
      name: "field_name",
      label: "field_label",
      type: "string",
      fieldType: "text",
      groupName: "companyinformation",
    },
  }),
});
```

{% endtab %}
{% endtabs %}

Example Response Body:

```json
{
    "data": {
	"archived": false,
	"calculated": false,
	"createdAt": "2024-01-11T23:43:00.066Z",
	"createdUserId": "46192612",
	"description": "",
	"displayOrder": -1,
	"externalOptions": false,
	"fieldType": "text",
	"formField": false,
	"groupName": "companyinformation",
	"hasUniqueValue": false,
	"hidden": false,
	"label": "StacksyncID",
	"modificationMetadata": {
		"archivable": true,
		"readOnlyDefinition": false,
		"readOnlyValue": false
	},
	"name": "enumeration",
	"options": [],
	"type": "string",
	"updatedAt": "2024-01-11T23:43:00.066Z",
	"updatedUserId": "46192612"
   },
   "message": "Custom field added successfully"
}
```

Example requests for different field types for the HubSpot Company object:

{% tabs %}
{% tab title="String" %}

```
curl -X POST https://eu.api-proxy.stacksync.com/v1/object/add_custom_field/company \
        -H "Authorization: Bearer *****" \
        -H "Content-Type: application/json" \
        -d '{
                "data": {
                    "name": "custom_field",
                    "label": "Custom Field", 
                    "type": "string",  
                    "fieldType": "text",
                    "groupName": "companyinformation"
                }
            }'
```

{% endtab %}

{% tab title="Enumeration" %}
For enumeration, the options property is required. The options property is a list of objects with the following properties:

* `label` (required) The display name of the option.
* `value` (required) The value of the option which will be used internally.
* `description` (optional) A text description for the option.
* `hidden` (optional) If true, the property won't be visible and can't be used in forms.

```
data {
	...
	"type": "enumeration",
	"options": [
	    {
		"label": "Option A",
		"description": "Choice number one",
		"value": "A",
		"hidden": false
	    },
	    {
	        "label": "Option B",
		"description": "Choice number two",
		"value": "B",
		"hidden": false
	    }
	]
	...
}
```

Example of full cURL request:

```
curl -X POST 

https://eu.api-proxy.stacksync.cloud/v1/object/add_custom_field/company \
        -H "Authorization: Bearer ******" \
        -H "Content-Type: application/json" \
        -d '{
	"data": {
		"name": "custom_field",
		"label": "Custom Field",
		"type": "enumeration",
		"fieldType": "select",
		"groupName": "companyinformation",
		"options": [
			{
			    "label": "Option A",
			    "description": "Choice number one",
			    "value": "A",
			    "displayOrder": 1,
			    "hidden": false
			},
			{
			    "label": "Option B",
			    "description": "Choice number two",
			    "value": "B",
			    "displayOrder": 2,
			    "hidden": false
			}
		]
		}
	}
}'
```

{% endtab %}
{% endtabs %}

### Pass Through

Make a request to any HubSpot API which supports OAuth by providing the URL, Request Method and the Request Body.Use the Pass Through operation to invoke any HubSpot API endpoint that supports OAuth authentication by specifying the full URL, HTTP method, and optional request body.

{% hint style="info" %}
HubSpot’s developer documentation clearly indicates which endpoints are compatible with OAuth access tokens: <https://developers.hubspot.com/docs/api/overview>

<img src="/files/735KhK5LUJ6MyGDGH0WQ" alt="" data-size="original">
{% endhint %}

When you call this operation, Stacksync sends a request to the target HubSpot URL using the method and body you provide. The request body is optional and may be omitted for methods such as `GET` or `DELETE`.

```bash
curl -X [GET | POST | PUT | PATCH | DELETE] 
https://eu.api-proxy.stacksync.com/v1/proxy/INSERT_REQUEST_URL_HERE \
-H "Authorization: Bearer your_api_proxy_service_token" \
-d 'Optional'
```

Example request:

**Create a new HubSpot Contact**

{% tabs %}
{% tab title="cURL" %}

```url
curl -X POST https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/objects/contacts/batch/create \
        -H "Authorization: Bearer your_api_proxy_service_token" \
        -H "Content-Type: application/json" \
        -d '{"inputs": [{"properties":{	"email": "john@company.com"}}]}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/objects/contacts/batch/create"

api_proxy_service_token = "your_api_proxy_service_token"

data = {
    "inputs": [
        {
            "properties": {
                "email": "john@company.com"
            }
        }
    ]
}

headers = {
    "Authorization": f"Bearer {api_proxy_service_token}",
    "Content-Type": "application/json",
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const url =
  "https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/objects/contacts/batch/create";

const apiProxyServiceToken = "your_api_proxy_service_token";

const data = {
  inputs: [
    {
      properties: {
        email: "john@company.com",
      },
    },
  ],
};

const headers = {
  Authorization: `Bearer ${apiProxyServiceToken}`,
  "Content-Type": "application/json",
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((json) => console.log(json))
  .catch((error) => console.error(error));

```

{% endtab %}
{% endtabs %}

Example response:

```json
{
	"completedAt": "2024-02-12T02:18:24.961Z",
	"results": [
		{
			"archived": false,
			"createdAt": "2024-02-12T02:18:24.748Z",
			"id": "441751",
			"properties": {
				"createdate": "2024-02-12T02:18:24.748Z",
				"email": "john@company.com",
				"hs_all_contact_vids": "441751",
				"hs_email_domain": "company.com",
				"hs_is_contact": "true",
				"hs_is_unworked": "true",
				"hs_lifecyclestage_lead_date": "2024-02-12T02:18:24.748Z",
				"hs_marketable_status": "false",
				"hs_marketable_until_renewal": "false",
				"hs_object_id": "441751",
				"hs_object_source": "INTEGRATION",
				"hs_object_source_id": "1749998",
				"hs_object_source_label": "INTEGRATION",
				"hs_pipeline": "contacts-lifecycle-pipeline",
				"lastmodifieddate": "2024-02-12T02:18:24.748Z",
				"lifecyclestage": "lead"
			},
			"updatedAt": "2024-02-12T02:18:24.748Z"
		}
	],
	"startedAt": "2024-02-12T02:18:24.720Z",
	"status": "COMPLETE"
}
```

#### Get the schema / columns of a standard HubSpot object

{% tabs %}
{% tab title="cURL" %}

```
curl -X GET 
https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/properties/<object_name> \
-H "Authorization: Bearer your_api_proxy_service_token" \
```

{% endtab %}

{% tab title="Python" %}

```
import requests

# Parameters
url = "https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/properties/<object_name>"
headers = {
    "Authorization": "Bearer your_api_proxy_service_token"
}

# Send GET request
response = requests.get(url, headers=headers)

```

{% endtab %}

{% tab title="Javascript" %}

```
// Parameters
const url =
  "https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/properties/<object_name>";
const headers = {
    "Authorization": "Bearer your_api_proxy_service_token"
};

// Send GET request
fetch(url, { method: 'GET', headers: headers })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

```

{% endtab %}
{% endtabs %}

#### Get the schema / columns of custom Hubspot objects

{% tabs %}
{% tab title="cURL" %}

```
curl -X GET 
https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/schemas \
-H "Authorization: Bearer your_api_proxy_service_token"
```

{% endtab %}

{% tab title="Python" %}

```
import requests

# Set up the URL and headers
url = "https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/schemas"
headers = {
    "Authorization": "Bearer your_api_proxy_service_token"
}

# Execute the GET request
response = requests.get(url, headers=headers)

```

{% endtab %}

{% tab title="Javascript" %}

```
// Define the URL and headers
const url =
  "https://eu.api-proxy.stacksync.com/v1/proxy/https://api.hubapi.com/crm/v3/schemas";
const headers = {
    "Authorization": "Bearer your_api_proxy_service_token"
};

// Perform the GET request
fetch(url, { method: 'GET', headers: headers })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacksync.com/api-proxy/hubspot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.