Self-hosted CRM API

The Self-hosted CRM API is the HTTP interface to the CRM built into every BasicsOS server deployment. Use it to manage contacts, companies, deals, tasks, notes, and custom objects from any language or tool that speaks HTTP.

This is not the Basics Gateway API. The gateway (api.basicsos.com) handles chat, embeddings, audio, and email. These CRM endpoints run on your server — the same origin where the BasicsOS web app is hosted (e.g. https://your-app.up.railway.app). For AI and voice features, see the Basics Gateway API docs. Your server communicates with the gateway internally using the configured BASICSOS_API_URL.

Base URL

The base URL is your deployment’s origin. There is no shared cloud endpoint for CRM data.

Environment	Base URL
Railway (example)	`https://your-app.up.railway.app`
Custom domain	`https://crm.yourcompany.com`
Local development	`http://localhost:3000`

All paths in this section are relative to your base URL.

What you can do

Area	Description
Contacts & companies	Create, list, update, delete, and merge contacts and companies.
Deals	Manage deal records through pipeline stages.
Tasks	Create and track tasks linked to contacts, companies, or deals.
Notes	Attach notes to contacts, deals, and companies.
Tags	Organize records with tags.
Custom objects	Work with any custom CRM object your organization defines.
Automation rules	Read and manage CRM automation configurations.
Schema introspection	Discover fields, types, and object definitions at runtime.

Quick example

# List the first 25 contacts
curl https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer bos_crm_your_token_here"

# Create a new contact
curl -X POST https://your-app.up.railway.app/api/contacts \
  -H "Authorization: Bearer bos_crm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  }'

Next steps

Authentication

Session cookies, Bearer tokens, and Personal CRM API tokens.

CRM REST API

Full CRUD reference for every resource type.

Related APIs

Schema introspection, views, custom fields, and more.

Errors & CORS

Status codes, error shapes, and cross-origin setup.

Overview

API reference

Base URL

What you can do

Quick example

Next steps

Authentication

CRM REST API

Related APIs

Errors & CORS

​Base URL

​What you can do

​Quick example

​Next steps

Authentication

CRM REST API

Related APIs

Errors & CORS

Base URL

What you can do

Quick example

Next steps