Skip to main content
All endpoints require a valid Bearer token. State-mutating requests must include a csrf_token field — obtain one from GET /api/security/csrf-token.

​
Contractors

​
List contractors

GET /api/contractors/list?action=list Returns active contractors available for job assignment. You can filter by name, trade, and coverage radius. Required permission: api.contractors.list.manage
​
action
string
required
Must be list.
​
search
string
Filter by contractor name.
​
trade_id
integer
Filter by trade category ID. Retrieve trade IDs from GET /api/contractors/trades.
​
postcode
string
Filter by coverage area. Use with GET /api/contractors/list-with-coverage to include isochrone coverage data.
​
limit
integer
default:"50"
Maximum records to return (max 200).
​
offset
integer
default:"0"
Number of records to skip.
curl -X GET "https://propops.yourcompany.com/api/contractors/list?action=list&trade_id=1&limit=20" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": [
    {
      "ID": 20,
      "uuid": "770e8400-e29b-41d4-a716-446655440001",
      "first_name": "Contractor_001",
      "last_name": "Surname_001",
      "email": "contractor001@example.com",
      "phone": "07700000002",
      "trades": ["Gas & Heating", "Plumbing"],
      "is_active": true
    }
  ],
  "count": 30,
  "message": "Operation completed successfully"
}

​
List contractors with coverage

GET /api/contractors/list-with-coverage Returns contractors enriched with their geographic coverage data for the Mapbox coverage map. Required permission: api.contractors.list-with-coverage.view 
curl -X GET "https://propops.yourcompany.com/api/contractors/list-with-coverage" \
  -H "Authorization: Bearer <token>"

​
List trades

GET /api/contractors/trades Returns all contractor trade categories. Use these IDs when filtering contractors or creating jobs. Required permission: api.contractors.trades.manage 
curl -X GET "https://propops.yourcompany.com/api/contractors/trades" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": [
    { "trade_id": 1, "name": "Gas & Heating" },
    { "trade_id": 2, "name": "Plumbing" },
    { "trade_id": 3, "name": "Electrical" },
    { "trade_id": 4, "name": "Roofing" },
    { "trade_id": 5, "name": "General Maintenance" }
  ],
  "message": "Operation completed successfully"
}

​
Certifications

Certifications track a contractor’s compliance documents (e.g. Gas Safe registration, NICEIC membership). Overdue certificates trigger automated reminder emails.

​
View certification document

GET /api/contractors/certification Serves a contractor certification file (PDF, JPEG, PNG, DOC, or DOCX) as a binary download. Staff can view any contractor’s files; contractors can only access their own. Required permission: api.contractors.certification.manage
​
file
string
required
Filename of the certification document. Must match the pattern cert_{id}_{id}_{id}.{ext}.
curl -X GET "https://propops.yourcompany.com/api/contractors/certification?file=cert_20_5_1704873600.pdf" \
  -H "Authorization: Bearer <token>" \
  --output certificate.pdf

​
Agents

Agents represent property management companies or individual property managers. Each agent can be assigned to one or more branches.

​
List agents

GET /api/agents/list?action=list Returns active agents available for job assignment. Required permission: api.agents.list.manage
​
action
string
required
Must be list.
​
search
string
Filter by agent name.
​
branch_id
integer
Filter agents assigned to a specific branch.
​
limit
integer
default:"50"
Maximum records to return (max 200).
​
offset
integer
default:"0"
Number of records to skip.
curl -X GET "https://propops.yourcompany.com/api/agents/list?action=list&branch_id=1" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": [
    {
      "ID": 10,
      "uuid": "880e8400-e29b-41d4-a716-446655440001",
      "first_name": "Agent_001",
      "last_name": "Surname_001",
      "email": "agent001@example.com",
      "branch_id": 1,
      "branch_name": "Branch_001",
      "is_active": true
    }
  ],
  "count": 15,
  "message": "Operation completed successfully"
}

​
List agent branches

GET /api/agents/branches Returns branch assignments for an agent or all agents. Required permission: api.agents.branches.manage
​
agent_uuid
string
Filter results to a specific agent. Omit to return all branch assignments.
curl -X GET "https://propops.yourcompany.com/api/agents/branches?agent_uuid=880e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>"

​
Configure branch sharing

Branch sharing rules control which branches an agent can view and operate on.
POST /api/agents/sharingRequired permission: api.agents.branches.manage
​
action
string
required
Must be assign.
​
agent_uuid
string
required
UUID of the agent.
​
branch_id
integer
required
ID of the branch to assign.
​
csrf_token
string
required
CSRF token.
curl -X POST "https://propops.yourcompany.com/api/agents/branches" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action":"assign","agent_uuid":"880e8400-e29b-41d4-a716-446655440001","branch_id":2,"csrf_token":"<csrf-token>"}'

​
Agent SLA configuration

GET /api/agents/sla Returns SLA configuration for an agent’s branches, including target completion times by job type and priority. Required permission: api.agents.list.manage 
curl -X GET "https://propops.yourcompany.com/api/agents/sla?agent_uuid=880e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "agent_uuid": "880e8400-e29b-41d4-a716-446655440001",
    "branch_name": "Branch_001",
    "sla_rules": [
      { "priority_name": "Emergency", "target_hours": 4 },
      { "priority_name": "High", "target_hours": 24 },
      { "priority_name": "Medium", "target_hours": 72 },
      { "priority_name": "Low", "target_hours": 168 }
    ]
  },
  "message": "Operation completed successfully"
}

​
Agent performance metrics

GET /api/agents/performance Returns performance KPIs for agents, including job completion rates, average resolution times, and recall counts. Required permission: api.agents.list.manage 
curl -X GET "https://propops.yourcompany.com/api/agents/performance?agent_uuid=880e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": {
    "agent_uuid": "880e8400-e29b-41d4-a716-446655440001",
    "agent_name": "Agent_001 Surname_001",
    "total_jobs": 150,
    "completed_jobs": 138,
    "completion_rate": 92.0,
    "avg_completion_days": 4.2,
    "recall_count": 5,
    "recall_rate": 3.3,
    "open_jobs": 12
  },
  "message": "Operation completed successfully"
}

​
Branch Management

Branch management endpoints are available to staff administrators for creating and configuring branches.
MethodEndpointDescription
GET/api/admin/branchesList all branches
POST/api/admin/branchesCreate a new branch
PUT/api/admin/branchesUpdate branch details and SLA configuration
DELETE/api/admin/branchesRemove a branch
Required permission: api.admin.branches.manage For SLA configuration options and branch sharing rules, see the Branches configuration guide.