Last modified: August 22, 2025
The contracts API allows you to create, update, and delete contract data in a HubSpot account. The contract object serves as a source of truth for committed revenue between buyers and sellers. Using contracts to track revenue can allow you to report on the full lifecycle of a customer agreement, including amendments and renewals.

​
Scope requirements

Based on the endpoints you plan on using, your app will need to authorize the following scopes:
  • Read scopes: to retrieve contract data:
    • crm.objects.contracts.read
    • crm.schemas.contracts.read
  • Write scopes: to create, update, or delete contracts:
    • crm.objects.contracts.write
    • crm.schemas.contracts.read
The sections below provide a walkthrough of how to each endpoint. Note that all endpoint URLs include /0-721 in the path corresponds to the objectTypeId for the contracts object. Learn more in the Understand the CRM APIs guide.

​
Create a contract

To create a contract, make a POST request to /crm/v4/objects/0-721/ and provide any properties as a field in the request body. For example, to create a contract with the following properties:
  • Name: Sample contract
  • Currency: USD
  • Effective start date: May 5, 2025
You’d make a POST request to https://api.hubapi.com/crm/v4/objects/0-721/ with the request body below: 
{
  "properties": {
    "hs_name": "Sample Contract Via API",
    "hs_currency_code": "USD",
    "hs_contract_effective_date": "2025-05-15"
  }
}

​
Read contract data

To retrieve multiple contracts, make a GET request to /crm/v4/objects/0-721, or to retrieve a specific contract by its ID, make a GET request to /crm/v4/objects/0-721/{contractId}. If you want to filter which properties are included for each contract, provide them using the ?properties= query parameter. For example, to fetch contracts and their corresponding ID, name, and effective start date, you’d make a GET request to https://api.hubapi.com/crm/v4/objects/0-721?properties=hs_name,hs_contract_effective_date 
[
  {
    "id": 123,
    "hs_name": "Q2 standard renewal - ACNE",
    "hs_contract_effective_date": "2025-05-15"
  },
  {
    "id": 456,
    "hs_name": "Q3 early bird discount - BigBiz",
    "hs_contract_effective_date": "2025-08-15"
  }
]

​
Update a contract

You can update a contract by making a PATCH request to /crm/v4/objects/0-721 and providing the properties you want to change in the request body. For example, to change some of the address fields on a contract with an ID of 123, you’d make a PATCH request to https://api.hubapiqa.com/crm/v3/objects/0-721/123` with the request body below: 
{
  "properties": {
    "hs_billing_address_line_1": "2 Canal Park",
    "hs_billing_address_line_2": "Apt 9001",
    "hs_billing_address_city": "Cambridge",
    "hs_billing_address_state": "MA",
    "hs_billing_address_country": "US",
    "hs_billing_address_zip": "02141"
  }
}

​
Associate a contract with a line item

To associate a contract with a line item, make a PUT request to /crm/v4/objects/0-721/{contractId}/associations/line_item/{lineItemId} using the IDs of the contract and the line item in the URL path. Learn more about using the associations API.

​
Delete a contract

To delete a contract, make a DELETE request to /crm/v4/objects/0-721/{contractId} with the ID of the contract. If the request is successful, the endpoint returns a 204 No Content response.