REST API overview

The Kudos CRM REST API is how your own scripts and integrations read and write CRM data — contacts, deals, tasks, activities, and more. Authenticate with a personal access token and you have the same surface the Kudos web app uses.

info

Source of truth. The backend's config/routes.rb and the serializers in app/serializers/ are authoritative. Per-endpoint request/response schemas are being migrated into the API reference (today it covers the Ingest API; the general REST surface is on the roadmap).

Base URL & auth

Key	Value
Base URL	https://api.kudoscrm.com/api/v1
Auth	Authorization: Bearer pat_… on every request (see personal access tokens)
Content type	application/json for writes

curl https://api.kudoscrm.com/api/v1/contacts \
  -H "Authorization: Bearer pat_…"

note

https://api.kudoscrm.com is the production API base. Your environment's base URL may differ — use the one shown in your workspace's Settings → Developer.

Make your first request

1. Create a personal access token

   In Settings → Security → Personal access tokens, mint a token with the scopes you need (e.g. read:contacts). Copy the pat_… secret — it's shown once.

2. Call an endpoint

   Send the token as a bearer header. This lists your contacts:

   curl https://api.kudoscrm.com/api/v1/contacts \
     -H "Authorization: Bearer pat_…"

3. Read the envelope

   Responses are JSON:API — data in data, pagination in meta (below). Handle errors from the errors array. You're integrated.

Response envelope

Responses follow a JSON:API-style shape:

{
  "data": { "id": "…", "type": "contact", "attributes": { "…": "…" } },
  "meta": { "current_page": 1, "per_page": 25, "total_pages": 4, "total_count": 87 }
}

List responses carry pagination in meta; single-resource responses omit it.

Writes

Most POST/PATCH bodies use the JSON:API write envelope:

{ "data": { "attributes": { "first_name": "Ada", "email": "[email protected]" } } }

note

A handful of legacy/action endpoints take a flat body instead — e.g. auth/*, bulk_*, check_duplicate, move_stage, won/lost, watchers, toggle_checklist_item, notification_preferences, push_subscriptions. File uploads (contacts/:id/avatar, contact_imports, deal_imports) use multipart/form-data.

Pagination, sorting, filtering

Concern	Syntax
Pagination	?page=1&per_page=25 (25 default)
Sorting	?sort=-created_at (prefix - = descending; allowed columns are enforced server-side)
Filtering	?filter[status]=open&filter[owner_id]=4 (nested-bracket, Ransack-style)

Errors

Errors return a JSON:API error array with the appropriate HTTP status:

{
  "errors": [
    { "status": "422", "title": "Unprocessable", "detail": "Email is invalid",
      "source": { "pointer": "/data/attributes/email" } }
  ]
}

See Errors for the full status-code reference.

Resource map

Every path is rooted at /api/v1/…. Standard resources expose the REST five (GET index, GET show, POST, PATCH, DELETE); action routes are noted where they exist. routes.rb is authoritative.

Domain	Resources
Contacts	contacts, contact_imports, contacts/:id/avatar
Companies	companies
Deals	deals (+ move_stage, won, lost, watchers), deal_imports
Pipeline	pipelines, pipeline_stages
Tasks	tasks, task_types, task_comments
Activities	activities, activity_comments
Forms	forms, form_submissions
Email	email_accounts, email_messages, email_campaigns
Meetings	meetings, booking_settings, public booking/:slug
Automation	lead_routing_rules, workflows
Views & search	saved_views, search
Admin	users, notifications, notification_preferences
Integrations	api_tokens, webhook_subscriptions, event_mappings

tip

Want events pushed to you instead of polling this API? Subscribe to outbound webhooks.