Multi-tenant contact management CRM with Google Contacts integration, group management, SMS messaging, and Hub synchronization.

Overview

Authentication

curl -H "X-API-Key: your-api-key" https://api.example.com/api/humans

Humans (Contacts)

GET /api/humans

Parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	20	Items per page (max 100)
sort	string	created_at	Sort: created_at, updated_at, first_name, last_name, display_name
order	string	DESC	ASC or DESC
q / search	string	-	Search in names
company_id	int	-	Filter by company
source	string	-	Filter: manual, google, hub
is_favorite	bool	-	Filter favorites
group_id	int	-	Filter by group

Response

{
  "success": true,
  "data": [{
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "John Doe",
    "job_title": "Manager",
    "company_name": "Acme Corp",
    "is_favorite": true,
    "phone_numbers": [{"phone_type": "mobile", "phone_number": "+33612345678", "is_primary": true}],
    "emails": [{"email_type": "work", "email": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.", "is_primary": true}],
    "groups": [{"id": 1, "name": "VIP", "color": "#FF5733"}]
  }],
  "pagination": {"page": 1, "per_page": 20, "total": 100, "total_pages": 5}
}

POST /api/humans

Request Body

{
  "first_name": "Jane",
  "last_name": "Smith",
  "display_name": "Jane Smith",
  "nickname": "JS",
  "job_title": "Developer",
  "department": "Engineering",
  "company_id": 2,
  "birthday": "1995-05-20",
  "notes": "Important contact",
  "photo_url": "https://example.com/photo.jpg",
  "source": "manual",
  "is_favorite": false,
  "metadata": {"custom_field": "value"},
  "phone_numbers": [{"number": "+33612345678", "type": "mobile", "is_primary": true}],
  "emails": [{"address": "Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.", "type": "work", "is_primary": true}],
  "group_ids": [1, 2]
}

GET /api/humans/{id}

Returns full human object with all phone numbers, emails, and groups.

PUT /api/humans/{id}

Same fields as create, all optional.

DELETE /api/humans/{id}

Soft deletes the human contact.

GET /api/humans/search

Query: q (min 2 chars), limit (default 50, max 100)

POST /api/humans/{id}/favorite

Toggles favorite status. Returns new is_favorite value.

GET /api/humans/stats

Companies

POST /api/humans/companies

Groups

GET /api/humans/groups

Returns groups with member_count.

POST /api/humans/groups

GET /api/humans/groups/{id}

Returns group details with full member list.

POST /api/humans/groups/{id}/members

Returns: added, requested, valid counts.

DELETE /api/humans/groups/{id}/members

Export

GET /api/export

CSV includes: id, names, job_title, company, birthday, primary_phone, primary_email, etc.

Parameters

Parameter	Type	Description
format	string	json, csv, or vcard (default: json)
ids	string	Comma-separated human IDs
group_id	int	Export group members
company_id	int	Export by company

GET /api/export/unified

Returns complete export with all entities and stats.

Google Contacts Integration

GET /api/google/auth-url

Query: state (optional OAuth state parameter)

POST /api/google/callback

Exchanges code for tokens and stores credentials.

GET /api/google/accounts

Returns connected Google accounts with sync status.

POST /api/google/import

Returns stats: created, updated, skipped.

DELETE /api/google/accounts/{id}

Revokes Google account connection.

Hub Synchronization

GET /api/hub/config

Returns Hub sync configuration (URL, direction, intervals, etc.).

POST /api/hub/config

POST /api/hub/import

Imports contacts from external Hub. Returns stats.

POST /api/hub/export

POST /api/hub/sync

Runs full bidirectional sync. Returns import and export results.

GET /api/hub/history

Query: limit (default 20, max 100). Returns sync job history.

SMS Messaging

POST /api/sms/send

Supports variable substitution from linked human.

POST /api/sms/send-bulk

GET /api/sms

Query: status, human_id, direction, q, pagination params.

GET /api/sms/stats

Query: period (7d, 30d, 90d, all). Returns totals and by_status breakdown.

Admin Endpoints

Requires admin role.

Error Handling

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden / Tenant Not Found
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

{"success": true, "data": {...}, "message": "Operation successful"}