CRM & Website Integration API Reference

The Valethon CRM API enables external websites, marketing platforms, and third-party tools to integrate with the CRM module. It provides lead capture, contact management, opportunity tracking, and embeddable chat widgets for MSP customer websites.

Base URL: https://{tenant}.valethon.com/admin/api/v1/crm

Authentication

The CRM API uses API keys for authentication. Keys are managed in Settings → CRM → API Keys.

API Key Types

Authentication Header

X-API-Key: crm_a1b2c3d4e5f6...

Public keys (pk_live_, pk_test_) are used client-side in the chat widget embed and only grant access to widget endpoints.

Secret keys (crm_*) are used server-side and grant access to all CRM API endpoints. Never expose secret keys in client-side code.

Key Management

Keys are stored securely using password_hash() with only the prefix visible in the admin UI. Each key has:

• Name — descriptive label
• Permissions — scoped access (e.g., leads:write, contacts:read)
• Rate limits — per-key configurable limits
• Status — active, suspended, or revoked

Rate Limiting

The API enforces rate limits using a sliding window algorithm (60-second window).

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1710350400

When exceeded, a 429 Too Many Requests response is returned with a Retry-After header.

Response Format

All responses return JSON with consistent structure:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": "Description of the error",
  "code": "VALIDATION_ERROR"
}

Paginated:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

Error Codes

Chat Widget

POST /widget/init

Initialize a chat widget session. Used by the embeddable widget on MSP customer websites.

Authentication: Public key (pk_live_ or pk_test_)

Request:

{
  "visitor_id": "v_abc123",
  "page_url": "https://customer-site.com/support",
  "referrer": "https://google.com"
}

Response (200):

{
  "success": true,
  "session_id": "ws_98765",
  "greeting": "Hello! How can we help you today?",
  "branding": {
    "company_name": "Acme IT Solutions",
    "primary_color": "#1FB6FF",
    "logo_url": "https://cdn.valethon.com/logos/acme.png"
  }
}

POST /widget/message

Send a message from the widget visitor.

Request:

{
  "session_id": "ws_98765",
  "message": "I need help with my email"
}

Response (200):

{
  "success": true,
  "response": {
    "message": "I can help with email issues. Could you describe the problem?",
    "suggested_actions": ["Create ticket", "Check service status"]
  }
}

POST /widget/end

End a widget chat session.

GET /widget/status

Get service status for the widget display.

Leads

GET /leads

List leads with filtering and pagination.

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "lead_id": 42,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+1-555-0123",
      "company_name": "Acme Corp",
      "status": "new",
      "source": "website_form",
      "score": 75,
      "assigned_to": null,
      "created_at": "2026-03-10T14:30:00Z",
      "updated_at": "2026-03-10T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 150, "total_pages": 6 }
}

POST /leads

Create a new lead.

Request:

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@company.com",
  "phone": "+1-555-9876",
  "company_name": "Globex Corp",
  "source": "website_form",
  "form_type": "contact_us",
  "raw_payload": {
    "role": "IT Director",
    "technicianCount": "11-25",
    "industry": "MSP",
    "message": "Looking for a PSA solution"
  }
}

Response (201):

{
  "success": true,
  "data": {
    "lead_id": 43,
    "status": "new",
    "created_at": "2026-03-13T10:00:00Z"
  }
}

GET /leads/{id}

Get lead details including activity history and linked entities.

PUT /leads/{id}

Update lead fields (status, assignment, score, custom fields).

DELETE /leads/{id}

Delete a lead.

POST /leads/{id}/convert

Convert a lead to a contact, prospect account, and optionally an opportunity.

Request:

{
  "create_contact": true,
  "create_prospect": true,
  "create_opportunity": true,
  "opportunity_name": "Acme Corp - Managed IT Services",
  "opportunity_value": 50000
}

Response (200):

{
  "success": true,
  "data": {
    "contact_id": 201,
    "prospect_id": 55,
    "opportunity_id": 78,
    "lead_status": "converted"
  }
}

POST /leads/{id}/activities

Log an activity against a lead.

GET /leads/{id}/activities

Get activity history for a lead.

Opportunities

GET /opportunities

List opportunities with filtering.

Query Parameters:

POST /opportunities

Create a new opportunity.

Request:

{
  "name": "Acme Corp - Managed Services",
  "prospect_id": 55,
  "stage": "discovery",
  "value": 50000,
  "expected_close_date": "2026-06-30",
  "probability": 30,
  "assigned_to": 5
}

GET /opportunities/{id}

Get opportunity details with activities, notes, and linked entities.

PUT /opportunities/{id}

Update opportunity fields.

DELETE /opportunities/{id}

Delete an opportunity.

POST /opportunities/{id}/advance-stage

Advance to the next pipeline stage.

People (Contacts)

GET /people

List CRM contacts.

Query Parameters:

POST /people

Create a new contact.

GET /people/{id}

Get contact details.

PUT /people/{id}

Update contact fields.

DELETE /people/{id}

Delete a contact.

Prospect Accounts

GET /prospects

List prospect accounts.

Query Parameters:

POST /prospects

Create a new prospect account.

GET /prospects/{id}

Get prospect details with linked contacts, opportunities, and activities.

PUT /prospects/{id}

Update prospect fields.

DELETE /prospects/{id}

Delete a prospect account.

POST /prospects/{id}/convert

Convert a prospect to a full customer (creates a company record).

Activities

GET /activities

List activities across all CRM entities.

Query Parameters:

POST /activities

Create an activity.

Request:

{
  "type": "call",
  "subject": "Discovery call with Acme Corp",
  "description": "Discuss current IT infrastructure and pain points",
  "entity_type": "opportunity",
  "entity_id": 78,
  "assigned_to": 5,
  "due_date": "2026-03-15T14:00:00Z",
  "duration_minutes": 30
}

GET /activities/{id}

Get activity details.

PUT /activities/{id}

Update activity (mark complete, reschedule, reassign).

DELETE /activities/{id}

Delete an activity.

Notes

POST /notes

Add a note to any CRM entity.

Request:

{
  "entity_type": "lead",
  "entity_id": 42,
  "content": "Spoke with John. Interested in managed services for 50 endpoints.",
  "is_pinned": false
}

GET /notes

List notes for an entity.

Query Parameters:

PUT /notes/{id}

Update a note.

DELETE /notes/{id}

Delete a note.

Events & Webhooks

The CRM API can send webhook notifications when events occur.

GET /webhooks

List configured webhooks.

POST /webhooks

Register a new webhook.

Request:

{
  "url": "https://your-app.com/webhooks/crm",
  "events": ["lead.created", "lead.converted", "opportunity.won"],
  "secret": "your_webhook_secret"
}

DELETE /webhooks/{id}

Remove a webhook registration.

Event Types

Webhook Payload:

{
  "event": "lead.created",
  "timestamp": "2026-03-13T10:00:00Z",
  "data": {
    "lead_id": 43,
    "email": "jane@company.com",
    "source": "website_form"
  },
  "signature": "sha256=a1b2c3..."
}

Verify webhook signatures using HMAC-SHA256 with your webhook secret.

Custom Fields

GET /custom-fields

List custom field definitions for a CRM entity type.

Query Parameters:

POST /custom-fields

Create a new custom field definition.

PUT /custom-fields/{id}

Update a custom field definition.

DELETE /custom-fields/{id}

Remove a custom field definition.

Search

GET /search

Search across all CRM entities.

Query Parameters:

Response (200):

{
  "success": true,
  "data": {
    "results": [
      {
        "type": "lead",
        "id": 42,
        "title": "John Doe",
        "subtitle": "Acme Corp",
        "score": 0.95,
        "url": "/crm/leads/42"
      }
    ],
    "total": 1
  }
}

Chat Widget Embed

To embed the CRM chat widget on an MSP customer website:

<script>
  window.ValethonWidget = {
    publicKey: 'pk_live_xxxxxxxxxxxx',
    position: 'bottom-right',
    primaryColor: '#1FB6FF',
    greeting: 'Need IT help? Chat with us!'
  };
</script>
<script src="https://{tenant}.valethon.com/widget/chat.js" async></script>

Configuration Options

Permissions Reference

For the Helpdesk API, see Helpdesk API Reference.

For the ServiceOS admin API, see ServiceOS API Reference.