Contracts API - HubSpot docs

Scope requirements

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.

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

{
  "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.

{
  "inputs": [
    { "id": "398334119041" },
    { "id": "399027563070" }
  ],
  "properties": ["hs_name", "hs_contract_effective_date"]
}

The response will include a results array with each requested contract:

{
  "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. 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:

{
  "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, 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 and all versions of the API.

​Retrieve contracts

​Batch retrieve contracts

​Merge contracts

Retrieve contracts

Batch retrieve contracts

Merge contracts