# OnePageCRM Developers

> Developer documentation for OnePageCRM, an action-focused CRM. Covers the REST API, OAuth 2.1 authentication, webhooks, OQL (a JSON query language over CRM data), and an MCP server for AI agents.

## Instructions

- The REST API base URL is https://app.onepagecrm.com/api/v3. Prefer OAuth 2.1 Bearer tokens for user-facing apps; use HTTP Basic auth (user_id:api_key) for personal scripts and quick tests.
- For code generation, use the raw OpenAPI 3 spec at https://raw.githubusercontent.com/OnePageCRM/swagger/master/swagger.yaml instead of scraping the HTML API reference.
- Every documentation and hub page is available as raw markdown: append `.md` to its path (e.g. /oauth/overview/ → https://developer.onepagecrm.com/oauth/overview.md; the homepage is at https://developer.onepagecrm.com/index.md). This includes every API reference page — e.g. https://developer.onepagecrm.com/api/reference/contacts/get-contacts.md for a single operation, or /api/reference/contacts/index.md for a resource. Blog posts are HTML only.
- The full documentation corpus in a single file: https://developer.onepagecrm.com/llms-full.txt
- For live CRM access from AI agents (query, create, update via OQL), use the MCP server: https://developer.onepagecrm.com/mcp/overview/
- An agent capability manifest indexing these surfaces (and the MCP server) is at https://developer.onepagecrm.com/.well-known/agents.json
- Availability: the REST API, webhooks, the MCP server, OQL (via MCP), External ID, and quick-create URLs are live today. OAuth 2.1 app registration is reviewed by the OnePageCRM team — request access. Custom Buttons are in beta (ask support to enable).

## Getting started

- [Quickstart](https://developer.onepagecrm.com/getting-started/quickstart/): Get credentials and make your first authenticated API call.
- [The data model](https://developer.onepagecrm.com/getting-started/data-model/): The seven core entities, their relationships, the Action Stream, and how each entity maps to REST, webhooks, OQL, and MCP. Read this first to understand the domain.
- [Build with AI](https://developer.onepagecrm.com/build-with-ai/): Pointing an AI coding assistant or agent at OnePageCRM — this llms.txt, the .md mirrors, the OpenAPI spec, and the live MCP server.

## API reference

- [API reference](https://developer.onepagecrm.com/api/reference/): Every endpoint, with request and response fields and copy-ready curl. One page per operation, one per resource — each also fetchable as `.md` (append `.md` to any reference path).
- [OpenAPI 3 spec](https://github.com/OnePageCRM/swagger): Canonical machine-readable definition (~101 paths).
- [Authentication](https://developer.onepagecrm.com/api/authentication/): HTTP Basic with user_id:api_key, or OAuth 2.1 Bearer tokens (scopes).
- [Errors](https://developer.onepagecrm.com/api/errors/): Response envelope, error_name catalog, HTTP status map, fixes.
- [Rate limits](https://developer.onepagecrm.com/api/rate-limits/): Concurrency and throughput limits, 429 handling, backoff.
- [Pagination](https://developer.onepagecrm.com/api/pagination/): page/per_page params and list metadata.
- [Sorting & time filters](https://developer.onepagecrm.com/api/sorting/): sort_by/order, and since/until/modified_since time filters.
- [Partial updates](https://developer.onepagecrm.com/api/partial-updates/): partial=true on PUT to change only the fields you send.
- [Undo deletion](https://developer.onepagecrm.com/api/undo-deletion/): reverse a DELETE by repeating it with undo=true.

## Tutorials

- [Make your first API call](https://developer.onepagecrm.com/tutorials/first-api-call/): Authenticate, list contacts, parse the response.
- [Subscribe to webhook events](https://developer.onepagecrm.com/tutorials/webhooks/): React to CRM changes in real time. Payload structure, sample data, reasons, testing tools.
- [Query CRM data with OQL](https://developer.onepagecrm.com/tutorials/oql/): Filters, aggregates, date helpers.

## OAuth

- [OAuth 2.1 overview](https://developer.onepagecrm.com/oauth/overview/): When to use OAuth, how it works, PKCE, scopes, client types.
- [OAuth quickstart](https://developer.onepagecrm.com/oauth/quickstart/): The full Authorization Code + PKCE flow with code in five languages.
- [Client registration](https://developer.onepagecrm.com/oauth/registration/): How to get client credentials while OAuth is in closed beta, and the redirect URI rules.
- [OAuth reference](https://developer.onepagecrm.com/oauth/reference/): Every endpoint, parameter, error code, troubleshooting, and security detail.

## Webhooks

- [Webhooks overview](https://developer.onepagecrm.com/webhooks/overview/): Real-time POSTs on CRM changes; activation and the five-key payload.
- [Events](https://developer.onepagecrm.com/webhooks/events/): Full entity × reason matrix, dynamic deal-status events, what triggers delivery.
- [Payloads](https://developer.onepagecrm.com/webhooks/payloads/): Envelope, sample payloads, deleted-event shape.
- [Delivery](https://developer.onepagecrm.com/webhooks/delivery/): Timing, at-most-once semantics, idempotency and reconciliation patterns.
- [Security](https://developer.onepagecrm.com/webhooks/security/): Secret-key verification with constant-time comparison.
- [Manage webhooks](https://developer.onepagecrm.com/webhooks/manage/): Setting up webhook configs in the Apps page.

## OQL — query language

- [OQL overview](https://developer.onepagecrm.com/oql/overview/): JSON query language over CRM data.
- [Concepts](https://developer.onepagecrm.com/oql/concepts/): Query shape, schema-as-allowlist, AND-only filters, sorting, limits, lookups (related fields), aggregates, group_by.
- [Operators](https://developer.onepagecrm.com/oql/operators/): `=`, `!=`, `<`, `>`, `in`, `between`, `like`, null checks; type compatibility matrix.
- [Functions](https://developer.onepagecrm.com/oql/functions/): `ME()`, `TODAY()`, `LAST_QUARTER()`, `DAYS_AGO`, date bucketing for `group_by`.
- [Limits and errors](https://developer.onepagecrm.com/oql/limits-and-errors/): Timeout, row cap, error categories.
- [Recipes](https://developer.onepagecrm.com/oql/recipes/): Copy-paste queries organized by the question (sales pipeline, action stream, contact management, activity reporting).
- Entities: [contacts](https://developer.onepagecrm.com/oql/entities/contacts/), [companies](https://developer.onepagecrm.com/oql/entities/companies/), [deals](https://developer.onepagecrm.com/oql/entities/deals/), [actions](https://developer.onepagecrm.com/oql/entities/actions/), [notes](https://developer.onepagecrm.com/oql/entities/notes/), [calls](https://developer.onepagecrm.com/oql/entities/calls/), [meetings](https://developer.onepagecrm.com/oql/entities/meetings/).

## MCP — AI agents

- [MCP server overview](https://developer.onepagecrm.com/mcp/overview/): Endpoint, OAuth flow, supported AI clients (ChatGPT, Claude, Mistral), scopes.
- Tools: [describe](https://developer.onepagecrm.com/mcp/tools/describe/), [context](https://developer.onepagecrm.com/mcp/tools/context/), [query](https://developer.onepagecrm.com/mcp/tools/query/), [create](https://developer.onepagecrm.com/mcp/tools/create/), [update](https://developer.onepagecrm.com/mcp/tools/update/).


## Extension points

- [Extension points overview](https://developer.onepagecrm.com/integrations/overview/): The platform APIs, plus lightweight ways to connect without a full integration.
- [External ID](https://developer.onepagecrm.com/integrations/external-id/): Map OnePageCRM records to records in your own system.
- [Custom Button](https://developer.onepagecrm.com/integrations/custom-button/): Add a contextual action button on Contact, Company, or Deal views.
- [Quick-create URL params](https://developer.onepagecrm.com/integrations/quick-create-contact-url/): Pre-fill the Add Contact form from a URL.

## Blog

- [Developer blog](https://developer.onepagecrm.com/blog/): Release notes, deep dives, and integration patterns.

Anchor posts:

- [Upload files via the OnePageCRM API](https://developer.onepagecrm.com/blog/upload-files-via-onepagecrm-api/): Three-step S3 upload tutorial.
- [We've got Swagger](https://developer.onepagecrm.com/blog/weve-got-swagger/): OpenAPI 3 spec announcement.
- [Quick-create URL params](https://developer.onepagecrm.com/blog/quick-create-url-params/): URL-prefill technique.
- [AWS webhooks](https://developer.onepagecrm.com/blog/aws-webhooks/): Architecture for receiving webhooks on AWS.
- [Connecting Gmail — the elusive refresh token](https://developer.onepagecrm.com/blog/connecting-gmail-elusive-refresh-token/): Gmail OAuth refresh-token mechanics.

## Optional

- [llms-full.txt](https://developer.onepagecrm.com/llms-full.txt): Every docs page plus the API reference overview and per-resource summaries, as one markdown file. For full per-endpoint schemas use the OpenAPI spec; any single operation is also at its `.md` path.
- [Blog RSS](https://developer.onepagecrm.com/rssfeed.xml)
- [Support](https://developer.onepagecrm.com/support/): How to reach a human — support@onepagecrm.com.
- [System status](https://developer.onepagecrm.com/status/)
- [Sitemap](https://developer.onepagecrm.com/sitemap-index.xml)
- [Main product site](https://www.onepagecrm.com)
- [GitHub organization](https://github.com/OnePageCRM)