REST API

v1.0 • Laravel Sanctum Authentication

Pivor provides a RESTful API for programmatic access to clients, contacts, and communications. Build integrations, automate workflows, and extend functionality.

Quick Navigation

Authentication

Token creation & usage

Endpoints

Available API routes

Query Parameters

Filter, sort & paginate

Examples

Code samples

Authentication

The API uses token-based authentication via Laravel Sanctum. Follow these steps to authenticate your requests.

1

Create a Token

Send your credentials to receive an API token:

POST /api/tokens/create
Request 
curl -X POST https://your-domain.com/api/tokens/create \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "yourpassword"
  }'
Response 200 OK 
{
  "token": "1|abc123def456...",
  "user": {
    "id": 1,
    "name": "User Name",
    "email": "user@example.com",
    "role": "admin"
  }
}
2

Use the Token

Include the token in the Authorization header for all API requests:

GET /api/clients 
curl https://your-domain.com/api/clients \
  -H "Authorization: Bearer 1|abc123def456..." \
  -H "Accept: application/json"

Always include Accept: application/json header to ensure JSON responses.

3

Revoke Token (Optional)

Invalidate a token when no longer needed:

DELETE /api/tokens/revoke 
curl -X DELETE https://your-domain.com/api/tokens/revoke \
  -H "Authorization: Bearer 1|abc123def456..."

Endpoints

Clients

/api/clients
Method Endpoint Description
GET /api/clients List all clients
POST /api/clients Create a new client
GET /api/clients/{'{'}id{'}'} Get a specific client
PUT /api/clients/{'{'}id{'}'} Update a client
DELETE /api/clients/{'{'}id{'}'} Delete a client

Client Fields

name Company name *
trading_name Trading name
type company | individual
status active | inactive | prospect | archived
email Primary email
phone Phone number
website Website URL
industry Industry sector
assigned_to User ID to assign
notes Additional notes

Contacts

/api/contacts
Method Endpoint Description
GET /api/contacts List all contacts
POST /api/contacts Create a new contact
GET /api/contacts/{'{'}id{'}'} Get a specific contact
PUT /api/contacts/{'{'}id{'}'} Update a contact
DELETE /api/contacts/{'{'}id{'}'} Delete a contact

Contact Fields

first_name First name *
last_name Last name *
email Email address
phone Phone number
mobile Mobile number
job_title Job title
client_id Associated client ID
is_primary_contact Boolean, primary contact
status active | inactive
assigned_to User ID to assign

Communications

/api/communications
Method Endpoint Description
GET /api/communications List all communications
POST /api/communications Create a new communication
GET /api/communications/{'{'}id{'}'} Get a specific communication
PUT /api/communications/{'{'}id{'}'} Update a communication
DELETE /api/communications/{'{'}id{'}'} Delete a communication

Communication Fields

type email | phone | meeting | note | task *
subject Subject/title *
direction inbound | outbound | internal
content Body/notes
client_id Associated client ID
contact_id Associated contact ID
priority low | medium | high | urgent
status pending | in_progress | completed | cancelled
due_at Due date (for tasks)
assigned_to User ID to assign

Query Parameters

Pagination

Control results per page

?per_page=25

Default: 15 • Max: 100

Sorting

Sort by any field

?sort=-created_at

Prefix with - for descending

Filtering

Filter by field values

?filter[status]=active

Combine multiple filters

Available Filters by Resource

Clients

search status type

Contacts

search status client_id

Communications

search type status priority direction client_id contact_id

Response Format

Single Resource

GET /api/clients/1 
{
  "data": {
    "id": 1,
    "uuid": "9b1c...",
    "name": "Acme Corp",
    "status": "active",
    ...
  }
}

Collection (Paginated)

GET /api/clients 
{
  "data": [...],
  "links": {
    "first": "...?page=1",
    "next": "...?page=2"
  },
  "meta": {
    "current_page": 1,
    "total": 72
  }
}

Error Response

422 Validation Error 
{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Access Control

API access respects user roles and permissions. Each role has different data visibility:

Admin

Full access to all records in the system

Manager

Access to all records, team management

User

Access only to personally assigned records

Code Examples

POST Create a Client
/api/clients 
curl -X POST https://your-domain.com/api/clients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "type": "company",
    "status": "active",
    "email": "contact@acme.com",
    "phone": "+1 555-0100"
  }'
GET List Communications with Filters
/api/communications 
curl "https://your-domain.com/api/communications?filter[type]=task&filter[status]=pending&sort=-priority" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
PUT Update a Contact
/api/contacts/{'{'}id{'}'} 
curl -X PUT https://your-domain.com/api/contacts/5 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_title": "Senior Developer",
    "department": "Engineering"
  }'
DELETE Delete a Client
/api/clients/{'{'}id{'}'} 
curl -X DELETE https://your-domain.com/api/clients/3 \
  -H "Authorization: Bearer YOUR_TOKEN"

Rate Limiting

The API implements rate limiting to ensure fair usage. If you exceed the limit, you'll receive a 429 Too Many Requests response. Rate limit headers are included in every response:

X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset