Introduction

The Contractors Cloud API is a REST API for managing your organization’s data on the Contractors Cloud platform. It uses resource-oriented URLs, accepts and returns JSON, and responds with conventional HTTP status codes.

Base URL

Every endpoint is served from a single base URL. Each path in this reference is relative to it.

https://api.contractorscloud.com/api/v1

The v1 segment is the API’s version. There is no version header or query parameter to send — configure the base URL once and you’re done. See Versioning and stability for the compatibility promises this carries.

Authentication

The API authenticates requests with a bearer token. Create a token from the API Access Tokens page in Contractors Cloud: log in and open Integrations → API Access Tokens. You choose the token’s name, so pick something that describes how it will be used, such as zapier, leads-form, or contact-integration.

The API Access Tokens page requires API access permissions on your user role. If you don’t see it, ask your administrator to grant you access.

Attach the token to every request in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

A request with a missing, malformed, or revoked token returns 401 Unauthorized.

API tokens are long-lived and do not expire. Store them securely and keep them out of source control. If a token is lost or compromised, revoke it from the API Access Tokens page and generate a new one.

The API also supports OAuth 2.0 for platform and AI-agent integrations that connect on behalf of another user. AI agents connect this way through MCP.

Test your connection

Two quick checks get you from zero to a working integration. First, confirm you can reach the API — no token needed:

curl "https://api.contractorscloud.com/api/v1/meta/status" \
  -H "Accept: application/json"

Then confirm your token works by fetching the user it belongs to, using me as the user id:

curl "https://api.contractorscloud.com/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

A 200 response with your user details means you’re ready to make any request in this reference. See Get API status and Get user.

Headers

Send these headers with every request so the API returns and parses JSON correctly:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json

Responses

All responses are JSON. Single-resource endpoints return the resource object directly. List endpoints return a paginated envelope with the records in a data array. Successful requests return a 2xx status code. Validation failures return 422 Unprocessable Entity with an errors object that names each invalid field.

Status codes

The API uses standard HTTP status codes. Rely on the status code to determine whether a request succeeded rather than inspecting the response body.

Code	Meaning
`200 OK`	The request succeeded.
`201 Created`	The request succeeded and a resource was created.
`204 No Content`	The request succeeded and there is no body to return.
`400 Bad Request`	The request could not be parsed. Check your payload.
`401 Unauthorized`	The request is missing a valid bearer token.
`403 Forbidden`	The token is valid but lacks access to the resource.
`404 Not Found`	No resource matches the requested URL.
`405 Method Not Allowed`	The HTTP method is not supported for this endpoint.
`422 Unprocessable Entity`	The payload is well-formed but failed validation. The response includes an `errors` object.
`429 Too Many Requests`	You exceeded the rate limit.
`500 Internal Server Error`	Something went wrong on our end.
`503 Service Unavailable`	The API is temporarily down for maintenance.

Use these docs from your AI agent

This documentation is also available as an MCP server, so coding agents like Claude Code and Cursor can search and read every page — the full API reference included — while you build your integration:

https://api.contractorscloud.com/docs/mcp

Add to Claude

Opens claude.ai with the docs connector pre-filled — click Add and it’s ready to use, no sign-in required.

The docs server is read-only, requires no authentication, and answers “how does the API work?” questions with cited pages. To let an agent act on a Contractors Cloud account instead — managing projects, tasks, and contacts in plain conversation — connect it to the Contractors Cloud MCP server.

Next steps

Filtering and sorting

Narrow and order list results with filter and sort.

Relationships

Embed related resources and computed attributes with include and append.

Pagination

Page through large list responses.

Rate limiting

Understand request limits and how to stay within them.

Versioning and stability

The compatibility contract: what never changes and how deprecations work.

Webhooks

Receive event notifications at your own endpoint when data changes.

Leads

Receive inbound leads and convert them into projects.

Connect your AI agent

Let Claude, ChatGPT, or another AI agent work with your Contractors Cloud account.

OAuth

Build integrations that connect on behalf of a user with OAuth 2.0.

Getting Started

Reference

Base URL

Authentication

Test your connection

Headers

Responses

Status codes

Use these docs from your AI agent

Add to Claude

Next steps

Filtering and sorting

Relationships

Pagination

Rate limiting

Versioning and stability

Webhooks

Leads

Connect your AI agent

OAuth

​Base URL

​Authentication

​Test your connection

​Headers

​Responses

​Status codes

​Use these docs from your AI agent

Add to Claude

​Next steps

Filtering and sorting

Relationships

Pagination

Rate limiting

Versioning and stability

Webhooks

Leads

Connect your AI agent

OAuth

Base URL

Authentication

Test your connection

Headers

Responses

Status codes

Use these docs from your AI agent

Next steps