> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 25cfd2ad-2b57-42bd-9e05-847a698157a9
---
# Contracts API
> Retrieve contract data from your HubSpot account
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Contracts represent the committed revenue agreements between buyers and sellers, detailing products, billing, and payment terms. The contracts API allows you to retrieve contract data from your HubSpot account. For more information on using contracts in HubSpot, see [create and manage contracts](https://knowledge.hubspot.com/contracts/create-contracts).
## Retrieve contracts
You can retrieve all contracts or individual contracts by ID as needed.
* To retrieve all contracts, make a `GET` request to `/crm/objects/2026-03/contracts`
* To retrieve a specific contract, make a `GET` request to `/crm/objects/2026-03/contracts/{contractId}`
The response will include a few default properties, including the create date and last modified date. To return additional properties, specify the properties by name using the `?properties=` query parameter.
For example, to fetch contracts and their corresponding ID, name, and effective start date, make a `GET` request to `/crm/objects/2026-03/contracts?properties=hs_name,hs_contract_effective_date`
```json theme={null}
{
"results": [
{
"id": "398334119041",
"properties": {
"hs_contract_effective_date": "2025-11-17",
"hs_createdate": "2025-11-17T11:32:10.699Z",
"hs_lastmodifieddate": "2025-11-17T11:32:12.651Z",
"hs_name": "HubBean | Machine servicing | 2025",
"hs_object_id": "398334119041"
},
"createdAt": "2025-11-17T11:32:10.699Z",
"updatedAt": "2025-11-17T11:32:12.651Z",
"archived": false,
"url": "https://app.hubspot.com/contacts/123456/record/0-721/398334119041"
},
{
"id": "399027563070",
"properties": {
"hs_contract_effective_date": "2025-11-27",
"hs_createdate": "2025-11-27T11:26:47.649Z",
"hs_lastmodifieddate": "2025-11-27T11:26:49.449Z",
"hs_name": "HubBean coffee | Machine servicing | 2025",
"hs_object_id": "399027563070"
},
"createdAt": "2025-11-27T11:26:47.649Z",
"updatedAt": "2025-11-27T11:26:49.449Z",
"archived": false,
"url": "https://app.hubspot.com/contacts/123456/record/contracts/399027563070"
}
]
}
```
## Batch retrieve contracts
To retrieve multiple contracts in a single request, make a `POST` request to `/crm/objects/2026-03/contracts/batch/read`. In the request body, include an `inputs` array with the IDs of the contracts you want to retrieve. You can also include a `properties` array to specify which properties to return.
```json theme={null}
{
"inputs": [
{ "id": "398334119041" },
{ "id": "399027563070" }
],
"properties": ["hs_name", "hs_contract_effective_date"]
}
```
The response will include a `results` array with each requested contract:
```json theme={null}
{
"status": "COMPLETE",
"results": [
{
"id": "398334119041",
"properties": {
"hs_contract_effective_date": "2025-11-17",
"hs_createdate": "2025-11-17T11:32:10.699Z",
"hs_lastmodifieddate": "2025-11-17T11:32:12.651Z",
"hs_name": "HubBean | Machine servicing | 2025",
"hs_object_id": "398334119041"
},
"createdAt": "2025-11-17T11:32:10.699Z",
"updatedAt": "2025-11-17T11:32:12.651Z",
"archived": false
},
{
"id": "399027563070",
"properties": {
"hs_contract_effective_date": "2025-11-27",
"hs_createdate": "2025-11-27T11:26:47.649Z",
"hs_lastmodifieddate": "2025-11-27T11:26:49.449Z",
"hs_name": "HubBean coffee | Machine servicing | 2025",
"hs_object_id": "399027563070"
},
"createdAt": "2025-11-27T11:26:47.649Z",
"updatedAt": "2025-11-27T11:26:49.449Z",
"archived": false
}
],
"startedAt": "2025-11-28T09:00:00.000Z",
"completedAt": "2025-11-28T09:00:00.010Z"
}
```
## Merge contracts
To merge two contract records, make a `POST` request to `/crm/objects/2026-03/contracts/merge`. The remaining record combines activities, associations, and most property values from both records. For example, merge duplicate contracts to preserve historical context and consolidate their activity timelines. Learn more about [what happens when you merge HubSpot records](https://knowledge.hubspot.com/records/merge-records#what-happens-when-i-merge-records).
Include the following in your request body:
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `objectIdToMerge` | The record ID to merge with the primary record. |
| `primaryObjectId` | The record ID of the primary record, which is the record that will remain after the merge. |
For example, to merge the record `45678` into the record `12345`, your request would look like:
```json theme={null}
{
"objectIdToMerge": "45678",
"primaryObjectId": "12345"
}
```
In a successful merge response, the `id` is the record ID of the merged record.
**Please note:** if an account is enrolled in the [*Primary ID Preservation for Merged Records* public beta](https://app.hubspot.com/l/product-updates/?rollout=318895), the primary (i.e., the remaining record after a merge) record's Record ID value (`primaryObjectId`) is preserved instead of generating a new one. Once enrolled, this behavior applies to all merges, including [in HubSpot](https://knowledge.hubspot.com/records/merge-records) and all versions of the API.