Skip to main content
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.
EnvironmentBase URL
Railway (example)https://your-app.up.railway.app
Custom domainhttps://crm.yourcompany.com
Local developmenthttp://localhost:3000
All paths in this section are relative to your base URL.

​
What you can do

AreaDescription
Contacts & companiesCreate, list, update, delete, and merge contacts and companies.
DealsManage deal records through pipeline stages.
TasksCreate and track tasks linked to contacts, companies, or deals.
NotesAttach notes to contacts, deals, and companies.
TagsOrganize records with tags.
Custom objectsWork with any custom CRM object your organization defines.
Automation rulesRead and manage CRM automation configurations.
Schema introspectionDiscover 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.