External API Overview

CleanEstimatePro includes a public REST API at https://app.cleanestimate.pro/api/v1/ for server-to-server integrations. Use it for Zapier, Make, custom CRMs, web forms, internal middleware, and partner apps.

The current public v1 API is intentionally scoped to the core workflow plus outbound webhook management:

• Leads
• Clients
• Estimates
• Jobs
• Invoices
• Outbound webhooks
• OpenAPI at /api/v1/openapi.json

Every request is isolated to the organization that owns the API key. The API never accepts a client-supplied org_id, and wrong-org records return 404.

What v1 Is For

Use the external API when you need to:

• Create leads from a partner form or marketing source
• Sync clients into another system
• Write internal CRM notes onto client, lead, and job records from your own middleware or automation layer
• Generate estimates from an approved upstream workflow
• Patch existing estimate customer details, assignment, draft/sent status, or expiration without recreating the quote
• Read jobs or invoices into reporting tools
• Trigger downstream automations from outbound webhooks

For the current public v1 surface, note fields are available on clients, leads, and jobs. See the Examples page for copy-paste POST and PATCH requests.

Residential estimate creation through POST /api/v1/estimates now lands on the same shared quote-core persistence layer as the in-app residential wizard. That keeps API-created residential estimates aligned with canonical quote snapshots and canonical line items while the broader wizard migration is still in progress.

Residential estimate updates through PATCH /api/v1/estimates/{id} now use that same shared residential quote-core save path too. The endpoint still stays intentionally narrow, but supported residential updates now preserve canonical quote snapshots, canonical line-item sync, delivery-state metadata, and quote events instead of bypassing the shared persistence layer with a raw row update.

What v1 Does Not Cover Yet

The public API still does not expose every internal CE Pro surface. Proposal-family endpoints, report snapshots, team and schedule snapshots, service catalog reads, pricing reads, customer-sign actions, and PDF/duplicate helper routes remain internal for now.

The old Phase 2 proposal/reporting docs described a broader future surface that is not part of the current public contract. Use /api/v1/openapi.json as the source of truth for what is live today.

Base URL And Contract

• Base URL: https://app.cleanestimate.pro/api/v1
• Auth: Authorization: Bearer ce_live_... or Authorization: Bearer ce_test_...
• Writes: POST and PATCH require Idempotency-Key, including PATCH /api/v1/estimates/{id}
• Correlation: every response includes X-Request-ID
• Rate limits: every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset
• Browser safety: this API is for server-to-server use only. Never expose secret API keys in frontend code.
• Schema: /api/v1/openapi.json

Shipped Resource Groups

• Core workflow: leads, clients, estimates, jobs, invoices
• Webhook management: webhooks

Response Shape

Single-record responses use:

{
  "data": {
    "id": "..."
  }
}

List responses use:

{
  "data": [],
  "meta": {
    "next_cursor": "opaque-cursor",
    "has_more": true,
    "limit": 25
  }
}

Errors use:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": []
  }
}

Common error codes:

• 401 invalid_api_key
• 403 insufficient_scope
• 403 unsupported_in_test_mode
• 409 idempotency_conflict
• 409 idempotency_in_progress
• 409 invalid_state
• 422 validation_error
• 429 rate_limited
• 503 rate_limit_unavailable

Live And Test Keys

CleanEstimatePro supports separate live and test keys:

• ce_live_... keys can use the full current public v1 surface.
• ce_test_... keys are for sandbox integrations.

In v1, test-key writes are intentionally limited to leads, clients, and estimates. Test-key writes are stored separately from live records and do not trigger normal outbound side effects.

Webhook management is live-only in the current public API. Test keys cannot call:

• /api/v1/webhooks

Related Inbound Channels

Not every integration starts with REST:

• Email intake: use the live forwarding address shown in Settings -> Integrations -> Lead Connectors after inbound email routing is configured
• Booking widget: /api/portal/[orgSlug]/book
• Automation webhook intake: POST /api/automations/webhooks/inbound
• Outbound events: register webhook destinations through /api/v1/webhooks

Automation webhook intake uses the same scoped API key model and shared rate limiting as the public API. Send either Authorization: Bearer ce_live_... or X-API-Key: ce_live_..., and make sure the key includes webhooks:write.

If you need a machine-readable contract, start with /api/v1/openapi.json. If you need operational guidance, continue with the pages in this Developers section.