API Documentation | Arvelo Built CRM

Overview

The Arvelo Built CRM API provides programmatic access to your CRM data. All API endpoints return JSON responses and use standard HTTP methods and status codes.

Note: The API is currently in active development. Some endpoints may change as we continue to build out the platform. We recommend checking this documentation regularly for updates.

Authentication

All API requests require authentication using PHP session cookies. You must be logged in through the web interface to make API calls.

Session-Based Authentication

When you log in through the web interface, a session cookie is set. Include this cookie in your API requests:

// JavaScript example (with credentials)
fetch('https://arvelobuilt.com/api/leads.php', {
  credentials: 'include',  // Include cookies
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': 'your-csrf-token'
  }
})
            

CSRF Protection: All POST, PATCH, and DELETE requests require a CSRF token. Include it in the X-CSRF-Token header or in the request body as csrf_token.

Unauthorized Response

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "success": false,
  "message": "Unauthorized"
}
            

Rate Limiting

API requests are rate-limited to prevent abuse. Current limits:

100 requests per 15 minutes per user
Rate limit headers are included in responses

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait before making additional requests.

Leads API

Manage sales leads through the Leads API.

GET /api/leads.php

List all leads with optional filters and pagination.

Query Parameters

Parameter	Type	Required	Description
status	string	Optional	Filter by lead status (NEW, WORKING, QUALIFIED, etc.)
rating	string	Optional	Filter by rating (HOT, WARM, COLD)
search	string	Optional	Search in company name, contact name, email
page	integer	Optional	Page number (default: 1)
limit	integer	Optional	Results per page (default: 50, max: 100)

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "company": "Acme Corp",
      "contact_name": "John Doe",
      "email": "john@acme.com",
      "status": "WORKING",
      "rating": "WARM",
      "created_at": "2025-12-26 10:00:00"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 50
}
                    

POST /api/leads.php

Create a new lead.

Request Body

Parameter	Type	Required	Description
company	string	Required	Company name
contact_name	string	Required	Contact person name
email	string	Optional	Email address
phone	string	Optional	Phone number
status	string	Optional	Initial status (default: NEW)
rating	string	Optional	Rating (HOT, WARM, COLD)
source_id	integer	Optional	Lead source ID
csrf_token	string	Required	CSRF token

GET /api/leads.php?id={id}

Get a specific lead by ID.

PATCH /api/leads.php?id={id}

Update a lead. Include only the fields you want to update in the request body.

DELETE /api/leads.php?id={id}

Soft delete a lead (marks as deleted, doesn't permanently remove).

Opportunities API

Manage sales opportunities and pipeline stages.

GET /api/opportunities.php

List all opportunities with optional filters.

POST /api/opportunities.php

Create a new opportunity.

Request Body

Parameter	Type	Required	Description
name	string	Required	Opportunity name
lead_id	integer	Optional	Associated lead ID
stage	string	Optional	Pipeline stage (QUALIFICATION, PROPOSAL, NEGOTIATION, etc.)
amount	decimal	Optional	Deal amount
close_date	date	Optional	Expected close date (YYYY-MM-DD)

Activities API

Create and manage activities (notes, calls, emails) associated with leads and opportunities.

POST /api/activities.php

Create a new activity (note, call, email, etc.).

Request Body

Parameter	Type	Required	Description
lead_id	integer	Optional	Associated lead ID (required if opportunity_id not provided)
opportunity_id	integer	Optional	Associated opportunity ID (required if lead_id not provided)
type	string	Optional	Activity type (NOTE, CALL, EMAIL, MEETING, default: NOTE)
subject	string	Optional	Activity subject (default: "Note")
body	string	Required	Activity content/description

Error Handling

All API endpoints return standard HTTP status codes and JSON error responses.

Status Codes

200 OK - Request successful
201 Created - Resource created successfully
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": "Validation error message"
  }
}
            

Security & Multi-Tenancy

Arvelo Built CRM uses a multi-tenant architecture. All API requests automatically filter data by your tenant ID—you can only access data belonging to your organization.

Automatic Tenant Isolation: You don't need to specify tenant_id in your requests. The API automatically filters all data based on your authenticated session.

CSRF Protection

All state-changing requests (POST, PATCH, DELETE) require a CSRF token. Include it in the X-CSRF-Token header or in the request body.

// Get CSRF token from meta tag or API response
const csrfToken = document.querySelector('meta[name="csrf-token"]').content;

// Include in request
fetch('https://arvelobuilt.com/api/leads.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': csrfToken
  },
  body: JSON.stringify({ ... })
})
            

Code Examples

JavaScript/TypeScript

// Fetch leads with filters
async function getLeads(status = null, search = '') {
  const params = new URLSearchParams();
  if (status) params.append('status', status);
  if (search) params.append('search', search);
  
  const response = await fetch(
    `https://arvelobuilt.com/api/leads.php?${params}`,
    { credentials: 'include' }
  );
  
  return await response.json();
}

// Create a new lead
async function createLead(leadData) {
  const csrfToken = document.querySelector('meta[name="csrf-token"]').content;
  
  const response = await fetch('https://arvelobuilt.com/api/leads.php', {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRF-Token': csrfToken
    },
    body: JSON.stringify({
      ...leadData,
      csrf_token: csrfToken
    })
  });
  
  return await response.json();
}
            

cURL

# List leads
curl -X GET \
  'https://arvelobuilt.com/api/leads.php?status=WORKING&page=1' \
  -H 'Cookie: PHPSESSID=your-session-id'

# Create lead
curl -X POST \
  'https://arvelobuilt.com/api/leads.php' \
  -H 'Content-Type: application/json' \
  -H 'X-CSRF-Token: your-csrf-token' \
  -H 'Cookie: PHPSESSID=your-session-id' \
  -d '{
    "company": "Acme Corp",
    "contact_name": "John Doe",
    "email": "john@acme.com",
    "csrf_token": "your-csrf-token"
  }'
            

Support & Resources

Need help with the API? We're here to help.

Email: api@arvelobuilt.com
Documentation: This page will be updated as new endpoints are added
Custom Development: Need a specific endpoint? Contact our partners team to discuss custom API development

API Versioning: The API is currently in active development. We recommend implementing error handling and checking this documentation regularly for updates. Future versions may include API versioning (e.g., /api/v1/) for backward compatibility.