# Developer Quick Start — API Keys & Authentication
_Developers_
Every integration starts with an API key. CRMown has two kinds: Public API keys for the partner API at /api/v1 (safe to give a third-party tool like Clay), and Internal keys that act like a signed-in user across the whole app. Send the key as a Bearer token.
## Steps
1. In CRMown go to Settings → Integrations and scroll to the Developer section → API Keys.
2. Click create, name the key, and choose the type: "Public API" (limited to contacts, companies, leads and notes — recommended for third parties) or "Internal" (full access, like a signed-in user).
3. For a Public API key, tick only the permissions the tool needs: Look up contacts (contacts:read), Create & update contacts (contacts:write), Create & update companies (companies:write), Create leads (leads:write), Add notes (notes:write).
4. Confirm the security check (creating a key asks you to verify it is you), then copy the key. It is shown only once — store it in your tool's secret settings.
5. Call the API with the header Authorization: Bearer . Base URL: https://app.crmown.io/api.
## Tips
- Keys start with ck_live_. CRMown stores only a hash, so a lost key can't be recovered — create a new one and revoke the old.
- A key acts as the person who created it. If that user is deactivated, or resets/changes their password, or uses "Log out all devices", their keys stop working immediately — create integration keys from a long-lived admin account.
- Use the right type for the right door: a Public API key used on an internal route — or an Internal key used on /api/v1 — is refused with 403 wrong_api_surface.
- Rate limits — Public API: 600 requests per minute per key (responses carry x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset; a 429 includes retry-after). Internal keys follow your plan: Starter 60/min and 10,000/day, Pro 120/min and 50,000/day, Max 300/min and 200,000/day.
- Revoke a key any time from the same list; revoking takes effect on the next request.
### Test your key
```
curl -H "Authorization: Bearer ck_live_YOUR_KEY" \
"https://app.crmown.io/api/v1/contacts/search?email=someone@example.com"
```
## Troubleshooting
- **401 unauthorized** — The key is missing, mistyped, revoked, expired, or its owner was deactivated or changed their password. Fix: Check the Authorization: Bearer header, then create a fresh key from an active admin account.
- **403 wrong_api_surface** — A Public API key was used on an internal route, or an Internal key on /api/v1. Fix: Use a Public API key for /api/v1 endpoints; use an Internal key for everything else.
- **403 insufficient_scope** — The key does not have the permission that endpoint needs (the response names it in "required"). Fix: Create a new Public API key with that permission ticked.
Source: https://docs.crmown.com/developers/developer-quick-start-api-keys-authentication
---
# Public API v1 — Contacts, Companies, Leads & Notes
_Developers_
A small, stable REST API for pushing data into CRMown from enrichment tools, forms, and your own systems. Writes are upserts matched on natural keys, so re-sending the same rows is safe. Interactive reference: https://app.crmown.io/api/v1/docs — OpenAPI JSON: https://app.crmown.io/api/v1/docs/json.
## Steps
1. GET /v1/contacts/search?email=… (contacts:read) — find a contact by email (case-insensitive). Returns id, email, firstName, lastName, phone, jobTitle, tags, leadScore and stage, or 404.
2. POST /v1/contacts/upsert (contacts:write) — create or update a contact. Fields: email, firstName, lastName, phone, title, companyDomain, tags[], custom{}, source. Needs either an email, or companyDomain + firstName + lastName. Returns { id, created, matchedBy } where matchedBy is "email", "domain_name" or null (new).
3. POST /v1/contacts/{id}/notes (notes:write) — add a note: { "body": "…" }.
4. POST /v1/companies/upsert (companies:write) — create or update a company by domain: { domain, name, industry, size, custom }.
5. POST /v1/leads (leads:write) — create/update the contact and put them on a pipeline: { email, source, score (0–100), pipeline (pipeline name; default pipeline if omitted), custom }. Returns { id, created, pipelineItemId, warning }.
## Tips
- Matching: by email first (lowercased, trimmed). With no email, the same first and last name at the same company domain matches. If several match, the oldest contact wins.
- Updates overwrite the fields you send; tags are added, never removed; an existing email is never replaced. companyDomain links to an existing company but does not create one — upsert the company first.
- Where the record came from: send an X-Source header (e.g. X-Source: clay) or a "source" field — letters, digits, dot, dash, underscore, up to 40 characters. It is set on NEW contacts only; the default is "api".
- Domains are normalised: https://www.Example.com/about becomes example.com.
- The API never sets email/SMS marketing consent — record consent in CRMown where you collected it.
- Leads are placed on the first stage of the pipeline, and skipped if the contact is already on it. A warning of no_pipeline_found or pipeline_has_no_stages tells you the contact was saved but not placed.
- Every contact upsert fires the contact.created or contact.updated webhook with source "api".
- Errors are JSON { error, code }: unauthorized (401), wrong_api_surface / insufficient_scope (403), not_found (404), missing_identity (400), rate_limited (429).
### Upsert a contact
```
curl -X POST https://app.crmown.io/api/v1/contacts/upsert \
-H "Authorization: Bearer ck_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "X-Source: clay" \
-d '{"email":"ada@example.com","firstName":"Ada","lastName":"Lovelace","title":"CTO","companyDomain":"example.com","tags":["webinar"]}'
```
### Create a lead on a pipeline
```
curl -X POST https://app.crmown.io/api/v1/leads \
-H "Authorization: Bearer ck_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.com","pipeline":"Sales","score":80,"source":"website"}'
```
Source: https://docs.crmown.com/developers/public-api-v1-contacts-companies-leads-notes
---
# Webhooks — Get Notified When Things Happen in CRMown
_Developers_
Webhooks send an HTTPS POST to your URL when something happens — a contact is created, a deal is won, a form is submitted. Each delivery is signed so you can verify it came from CRMown.
## Steps
1. Settings → Integrations → Developer → Webhooks → add an endpoint: your HTTPS URL and the events you want.
2. Copy the signing secret (starts with whsec_). Rotate it any time from the same screen.
3. Click Test to send a "ping" event, and use the delivery log to see each attempt, its status code and response.
4. In your receiver, verify the X-Webhook-Signature header against the raw request body, then return any 2xx status within 10 seconds.
## Tips
- Events — contacts: contact.created, contact.updated, contact.deleted, contact.stage_changed, contact.score_changed, contact.tag_added. Deals: deal.created, deal.updated, deal.won, deal.lost, deal.stage_changed. Messages: message.sent, message.received, conversation.created. Tasks: task.created, task.completed. Bookings: booking.created, booking.cancelled. Forms: form.submitted. CRMown AI: ai_action.created, ai_action.approved, ai_action.rejected. Tracking: tracking.email_opened, tracking.link_clicked, tracking.page_visited. Nonprofit: nonprofit.verification_recorded, nonprofit.activated.
- "source" tells you what caused the event: app, api, zapier, import, sync, automation, ai, inbound, system or partner — useful to ignore changes your own integration made.
- Headers on every delivery: X-Webhook-Signature (hex HMAC-SHA256 of the raw body, using your secret — no "sha256=" prefix), X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Id, User-Agent: CRMown-Webhooks/1.0.
- Retries: a non-2xx or timeout is retried up to 5 attempts in total — about 30 seconds, 2 minutes, 8 minutes and 32 minutes after the first try.
- X-Webhook-Id is new on every attempt, so don't use it to de-duplicate — use the event name, timestamp and the record id inside data.
- An endpoint is switched off after 10 failures in a row, or straight away if its URL points at a private/internal address. Fix the receiver, then turn it back on in the list.
- Up to 1,000 deliveries per hour per workspace. Events beyond that in the same hour are not delivered, so use the API to reconcile after very large bulk operations.
- The test ping looks like { "event": "ping", "timestamp": …, "data": { "message": "This is a test webhook from CRMown" } } and has no "source".
### Payload shape
```
{
"event": "contact.created",
"timestamp": "2026-10-10T14:03:22.115Z",
"source": "app",
"data": { "contact": { "id": "…", "firstName": "Ada", "email": "ada@example.com" } }
}
```
### Verify the signature (Node.js)
```
import crypto from 'node:crypto'
// rawBody = the exact request body string, BEFORE JSON parsing
const expected = crypto.createHmac('sha256', process.env.CRMOWN_WEBHOOK_SECRET).update(rawBody).digest('hex')
const received = req.headers['x-webhook-signature']
const ok = received && expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
```
## Troubleshooting
- **Signature never matches** — The signature is computed over the exact raw body; re-serialising parsed JSON changes spacing and key order. Fix: Verify against the raw request body bytes (e.g. express.raw() / request.text()) before parsing.
- **The endpoint shows as disabled** — It failed 10 times in a row, or its URL resolves to a private address. Fix: Check the delivery log for the error, fix the receiver or URL, then re-enable it — re-enabling resets the failure count.
Source: https://docs.crmown.com/developers/webhooks-get-notified-when-things-happen-in-crmown
---
# Website Forms — Capture Leads from Any Site
_Developers_
There are four ways to get form submissions from a website into CRMown as contacts: forms on a Web Studio site are captured automatically; CRMown Forms can be embedded anywhere or posted to; the Universal Lead Capture script drops a ready-made form on any site; and an Automation webhook trigger accepts any JSON.
## Steps
1. Web Studio site: any ordinary . Add