> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.contracthero.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Public REST API: drive ContractHero from your own systems

# Public REST API: drive ContractHero from your own systems

The **ContractHero Public REST API** lets you wire ContractHero into your own systems and workflows. You can reach organisations, contracts, contacts and tasks — reading, creating and updating — which is what you need to build your own integrations, migrations or reporting pipelines.

## What's in it for you

Where webhooks **push** ContractHero events out to your systems, the REST API works the other way round: you **pull** data or trigger actions. Typical use cases:

* **Bulk import** of existing contracts out of a legacy system.
* **Reverse sync** from your CRM or ERP back into ContractHero.
* **Reporting and BI**: mirror contract data into BigQuery, Snowflake or Looker.
* **Your own front end**: create contracts from inside your internal application.

Instead of CSV exports and manual uploads, everything runs over standard REST calls.

## Prerequisites

* The REST API is available from the **Professional** plan upwards (Professional, Enterprise).
* Activation runs through your Customer Experience team.
* **Developer capacity on your side**: REST, JSON, HTTP headers, ideally some experience with OpenAPI specifications.

## How it works

**1. Open the documentation**

The full API documentation lives at:

```
https://api.contracthero.com/docs
```

Format: **OpenAPI 3.0.0**, version **v1.0.0**. Use **“Download OpenAPI Document”** to grab the spec and import it into Postman, Insomnia or your code generator.

**2. Get API access enabled**

Contact us through the ContractHero web chat or by email at support@contracthero.com. Have this ready:

* Your use case, in one sentence.
* Who the technical contact for the integration is.
* Whether you need read or write access.

We set the access up with you and hand the credentials directly to your technical contact.

**3. First request: list organisations**

Once access is live, fetch every organisation you can reach:

```
GET /public/organizations
```

The response carries the `organizationId` and `teamId` you'll need for the other endpoints.

**4. Create a contract (example)**

```
POST /public/organizations/{organizationId}/teams/{teamId}/contracts
Content-Type: application/json
```

Body (abbreviated):

```json
{
  "categoryId": "…",
  "propertyName": { … },
  "partnerCompany": { "$create": { "name": "New counterparty" } }
}
```

A successful call returns **HTTP 201** with the created contract object (id, category, status, createdAt, updatedAt, partnerCompany).

## Available endpoint groups

| Area | Key endpoints |
| ---- |
| **Organizations** | GET all organizations, GET organization, GET teams, GET categories, GET datapoints, GET contact datapoints, GET contact types |
| **Contracts** | GET all contracts, POST create contract, PATCH update contract, GET single contract, GET signers, POST add document, GET documents, POST start signature process, GET document |
| **Contacts** | GET, POST, PATCH — contacts and their datapoints |
| **Tasks** | GET, POST, PATCH — task management |
| **Models** | The API's sub-schemas (data models such as ContractDTO, AmountDatapointDTO) |

The complete list, with path parameters, request bodies, response schemas and examples, is in the live documentation.

## Common questions

**Which plans include the REST API?**
**Professional** and above (Professional, Enterprise).

**How do I get access?**
Through the **Customer Experience team**. Write to support@contracthero.com and we'll set it up after a short conversation about your use case.

**Is the API REST or GraphQL?**
**REST.** Resource-oriented URLs, JSON bodies, standard HTTP verbs (GET, POST, PATCH) and standard HTTP status codes.

**Which sub-resources are available?**
Contracts, including **document upload**, **starting a signature process**, **querying signers** and **reading contract documents**. Contacts including their datapoints. Tasks.

**How does the API handle permissions?**
Access operates within the organisation and team permissions assigned to it. If only read access was granted, write endpoints are rejected with **HTTP 403**.

**Are there rate limits?**
Yes, to protect the platform. If you're planning production load — bulk operations or an initial migration — talk to us beforehand and we can adjust the limits.

**Can I use the API for the initial data migration?**
Yes — for structured migrations the API is the preferred route. For very large volumes (more than 10,000 contracts) we recommend a short conversation with our team first, so rate limits and data types are prepared properly.

**How will I hear about API changes?**
We aim to communicate breaking changes with reasonable notice. Leave a contact for API notifications when you set access up.

**How do the REST API and webhooks relate?**
They complement each other. The **REST API** is pull-based: you fetch data or trigger actions. **Webhooks** are push-based: ContractHero tells you when something happened. Many integrations use both — webhooks for the trigger, the API for the follow-up action.

## Good to know

* **Load the OpenAPI spec straight into Postman.** “Download OpenAPI Document” in the live docs gives you a machine-readable spec. Import it into Postman or Insomnia and every endpoint is there with example bodies.
* **Test read-only first.** Before you create contracts in production, use GET endpoints to confirm your access, organisation ID and team ID are right. It saves cleanup later.
* **Handle idempotency on your side.** If your integration POSTs the same contract twice — after a retry, say — you get a duplicate. Store source IDs and check before every create.
* **API plus webhooks is the full picture.** Webhooks trigger your workflow, the API then fetches the complete data and carries out the follow-up. Combining both is how robust, near-real-time integrations get built.
* **We help with the setup.** If you're unsure about endpoint design or a migration, book a discovery call with the ContractHero team — an hour often saves weeks.

## Contact

For questions, access requests or help with a migration, reach us through the ContractHero web chat or by email at support@contracthero.com.

## Related articles

* [How can task automations be set up and managed?](https://support.contracthero.com/en-us/article/how-can-task-automations-be-set-up-and-managed-129a18q/)
* [Invite users and manage permissions](https://support.contracthero.com/en-us/article/invite-users-and-manage-permissions-1yk66eu/)