Skip to content
ZServed Documentation

ZServed API Documentation

ZServed API Documentation

Complete API reference for integrating with ZServed’s legal technology platform, including authentication, data management, AI services, and professional compliance features.

API Overview

ZServed’s REST API provides comprehensive access to legal technology platform capabilities while maintaining professional compliance and security standards. The API is built on Cloudflare’s edge infrastructure for global performance and reliability.

API Base URLs

Production Environment:

  • API Base URL: https://zserved.cozyartz-media-group.workers.dev/api/v1
  • Frontend Base: https://zserved.com
  • Documentation: https://docs.zserved.com

Authentication Endpoints:

  • Login: POST /api/v1/auth/login
  • OAuth: GET /api/v1/auth/oauth/{provider}
  • Token Refresh: POST /api/v1/auth/refresh

Authentication and Authorization

1. JWT Authentication

Authentication Flow:

// Login with email and password
const loginResponse = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@lawfirm.com',
    password: 'securePassword',
    tenantId: 'lawfirm-slug'
  })
});


const { token, refreshToken, user } = await loginResponse.json();


// Use JWT token for subsequent requests
const apiResponse = await fetch('/api/v1/users', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

JWT Token Structure:

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "userId": "user_123",
    "email": "user@lawfirm.com",
    "role": "lawyer",
    "tenantId": "lawfirm-slug",
    "permissions": ["read:documents", "write:documents", "manage:clients"],
    "iat": 1640995200,
    "exp": 1641081600
  }
}

2. Role-Based Access Control

User Roles and Permissions:

Admin Role:

{
  "role": "admin",
  "permissions": [
    "manage:users",
    "manage:settings",
    "view:analytics",
    "manage:billing",
    "access:admin_panel"
  ]
}

Lawyer Role:

{
  "role": "lawyer",
  "permissions": [
    "read:documents",
    "write:documents",
    "manage:clients",
    "create:jobs",
    "view:reports",
    "access:ai_services"
  ]
}

Process Server Role:

{
  "role": "process_server",
  "permissions": [
    "view:assigned_jobs",
    "update:job_status",
    "upload:proof_documents",
    "access:mobile_app"
  ]
}

Client Role:

{
  "role": "client",
  "permissions": [
    "view:own_documents",
    "view:case_status",
    "communicate:lawyer",
    "access:client_portal"
  ]
}

Core API Endpoints

1. User Management

Get Current User:

GET /api/v1/users/me
Authorization: Bearer {token}

Response:

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "user@lawfirm.com",
    "name": "John Attorney",
    "role": "lawyer",
    "tenantId": "lawfirm-slug",
    "settings": {
      "timezone": "America/New_York",
      "notifications": true
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "lastLoginAt": "2024-01-20T09:15:00Z"
  }
}

Update User Profile:

PATCH /api/v1/users/me
Authorization: Bearer {token}
Content-Type: application/json


{
  "name": "John Q. Attorney",
  "settings": {
    "timezone": "America/Chicago",
    "notifications": false
  }
}

List Users (Admin Only):

GET /api/v1/users?page=1&limit=25&role=lawyer
Authorization: Bearer {token}

2. Document Management

Upload Document:

POST /api/v1/documents/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data


{
  "file": [binary data],
  "name": "Contract Draft v2.pdf",
  "type": "contract",
  "clientId": "client_456",
  "metadata": {
    "category": "contracts",
    "confidential": true
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "doc_789",
    "name": "Contract Draft v2.pdf",
    "type": "contract",
    "size": 2048576,
    "uploadedBy": "user_123",
    "clientId": "client_456",
    "r2Key": "tenants/lawfirm-slug/documents/doc_789.pdf",
    "downloadUrl": "/api/v1/documents/doc_789/download",
    "metadata": {
      "category": "contracts",
      "confidential": true
    },
    "createdAt": "2024-01-20T14:30:00Z"
  }
}

Get Document:

GET /api/v1/documents/{documentId}
Authorization: Bearer {token}

Download Document:

GET /api/v1/documents/{documentId}/download
Authorization: Bearer {token}

List Documents:

GET /api/v1/documents?clientId=client_456&type=contract&page=1&limit=10
Authorization: Bearer {token}

3. Job Management

Create Job:

POST /api/v1/jobs
Authorization: Bearer {token}
Content-Type: application/json


{
  "title": "Serve Summons - Smith vs. Jones",
  "description": "Serve summons and complaint to defendant",
  "clientId": "client_456",
  "recipientInfo": {
    "name": "Jane Defendant",
    "address": "123 Main St, City, State 12345",
    "phone": "+1-555-123-4567"
  },
  "documents": ["doc_789"],
  "deadline": "2024-01-25T17:00:00Z",
  "priority": "high"
}

Response:

{
  "success": true,
  "data": {
    "id": "job_101",
    "title": "Serve Summons - Smith vs. Jones",
    "status": "pending",
    "clientId": "client_456",
    "assignedTo": null,
    "createdBy": "user_123",
    "recipientInfo": {
      "name": "Jane Defendant",
      "address": "123 Main St, City, State 12345",
      "phone": "+1-555-123-4567"
    },
    "documents": ["doc_789"],
    "deadline": "2024-01-25T17:00:00Z",
    "priority": "high",
    "createdAt": "2024-01-20T15:00:00Z"
  }
}

Update Job Status:

PATCH /api/v1/jobs/{jobId}
Authorization: Bearer {token}
Content-Type: application/json


{
  "status": "in_progress",
  "notes": "En route to serve defendant"
}

Assign Job:

POST /api/v1/jobs/{jobId}/assign
Authorization: Bearer {token}
Content-Type: application/json


{
  "processServerId": "user_789",
  "estimatedCompletion": "2024-01-24T10:00:00Z"
}

4. AI Services

AI Chat/Assistance:

POST /api/v1/ai/chat
Authorization: Bearer {token}
Content-Type: application/json


{
  "message": "Help me draft a motion to dismiss",
  "context": {
    "caseType": "civil",
    "jurisdiction": "federal",
    "documents": ["doc_789"]
  },
  "assistantType": "gavel"
}

Response:

{
  "success": true,
  "data": {
    "response": "I'll help you draft a motion to dismiss. Based on the case documents, here's a structured approach...",
    "suggestions": [
      "Review standing requirements",
      "Check statute of limitations",
      "Analyze personal jurisdiction"
    ],
    "relatedDocuments": ["template_mtd_federal.pdf"],
    "confidence": 0.92,
    "tokensUsed": 1250
  }
}

Document Summarization:

POST /api/v1/ai/summarize
Authorization: Bearer {token}
Content-Type: application/json


{
  "documentId": "doc_789",
  "summaryType": "executive",
  "maxLength": 500
}

Response:

{
  "success": true,
  "data": {
    "summary": "This contract establishes a service agreement between...",
    "keyPoints": [
      "Service term: 24 months",
      "Monthly fee: $5,000",
      "Termination clause: 30-day notice"
    ],
    "risks": [
      "Broad indemnification clause",
      "Automatic renewal provision"
    ],
    "confidence": 0.89,
    "tokensUsed": 875
  }
}

Extract Legal Clauses:

POST /api/v1/ai/extract-clauses
Authorization: Bearer {token}
Content-Type: application/json


{
  "documentId": "doc_789",
  "clauseTypes": ["termination", "payment", "liability"]
}

Tenant and Multi-Tenancy

1. Tenant Management

Get Tenant Information:

GET /api/v1/tenant
Authorization: Bearer {token}

Response:

{
  "success": true,
  "data": {
    "id": "lawfirm-slug",
    "name": "Smith & Associates Law Firm",
    "domain": "smithlaw.zserved.com",
    "settings": {
      "timezone": "America/New_York",
      "businessHours": "9:00-17:00",
      "allowClientPortal": true
    },
    "subscription": {
      "plan": "professional",
      "status": "active",
      "usersIncluded": 10,
      "usersActive": 7
    },
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Update Tenant Settings:

PATCH /api/v1/tenant/settings
Authorization: Bearer {token}
Content-Type: application/json


{
  "settings": {
    "businessHours": "8:30-18:00",
    "allowClientPortal": true,
    "enableAIFeatures": true
  }
}

2. Tenant Isolation

All API endpoints automatically enforce tenant isolation based on the authenticated user’s tenant context. Users can only access data within their own tenant boundary.

Tenant Context Headers:

X-Tenant-ID: lawfirm-slug
X-User-Role: lawyer
X-User-Permissions: read:documents,write:documents,manage:clients

Rate Limiting and Quotas

1. Rate Limiting

Default Rate Limits:

  • Standard Users: 1000 requests per hour
  • Premium Users: 5000 requests per hour
  • Admin Users: 10000 requests per hour
  • AI Services: 100 requests per hour (with token limits)

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640998800
X-RateLimit-Retry-After: 3600

2. Usage Quotas

Professional Tier Quotas:

{
  "documents": {
    "monthly": 1000,
    "used": 234,
    "remaining": 766
  },
  "aiTokens": {
    "monthly": 100000,
    "used": 15420,
    "remaining": 84580
  },
  "storage": {
    "limit": "10GB",
    "used": "2.3GB",
    "remaining": "7.7GB"
  }
}

Error Handling

1. Error Response Format

Standard Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email",
      "requirement": "Valid email address required"
    },
    "timestamp": "2024-01-20T15:30:00Z",
    "requestId": "req_abc123"
  }
}

2. Common Error Codes

Authentication Errors:

  • AUTH_REQUIRED: Authentication required
  • AUTH_INVALID: Invalid authentication credentials
  • AUTH_EXPIRED: Authentication token expired
  • AUTH_INSUFFICIENT: Insufficient permissions

Validation Errors:

  • VALIDATION_ERROR: Request validation failed
  • MISSING_REQUIRED: Required field missing
  • INVALID_FORMAT: Invalid data format
  • CONSTRAINT_VIOLATION: Data constraint violation

Business Logic Errors:

  • RESOURCE_NOT_FOUND: Requested resource not found
  • DUPLICATE_RESOURCE: Resource already exists
  • QUOTA_EXCEEDED: Usage quota exceeded
  • OPERATION_NOT_ALLOWED: Operation not permitted

System Errors:

  • INTERNAL_ERROR: Internal server error
  • SERVICE_UNAVAILABLE: Service temporarily unavailable
  • RATE_LIMIT_EXCEEDED: Rate limit exceeded

Webhooks and Real-Time Updates

1. Webhook Configuration

Register Webhook:

POST /api/v1/webhooks
Authorization: Bearer {token}
Content-Type: application/json


{
  "url": "https://your-app.com/webhooks/zserved",
  "events": [
    "job.status_changed",
    "document.uploaded",
    "user.created"
  ],
  "secret": "webhook_secret_key"
}

2. Webhook Events

Job Status Changed:

{
  "event": "job.status_changed",
  "timestamp": "2024-01-20T16:00:00Z",
  "tenantId": "lawfirm-slug",
  "data": {
    "jobId": "job_101",
    "oldStatus": "pending",
    "newStatus": "in_progress",
    "assignedTo": "user_789",
    "updatedBy": "user_789"
  }
}

Document Uploaded:

{
  "event": "document.uploaded",
  "timestamp": "2024-01-20T16:15:00Z",
  "tenantId": "lawfirm-slug",
  "data": {
    "documentId": "doc_890",
    "name": "Signed Contract.pdf",
    "uploadedBy": "user_123",
    "clientId": "client_456",
    "size": 1024768
  }
}

SDK and Integration Examples

1. JavaScript/TypeScript SDK

Installation:

Terminal window
npm install @zserved/api-client

Usage:

import { ZServedClient } from '@zserved/api-client';


const client = new ZServedClient({
  baseUrl: 'https://zserved.cozyartz-media-group.workers.dev/api/v1',
  token: 'your_jwt_token'
});


// Upload document
const document = await client.documents.upload({
  file: fileBuffer,
  name: 'Contract.pdf',
  type: 'contract',
  clientId: 'client_123'
});


// Create job
const job = await client.jobs.create({
  title: 'Serve Summons',
  clientId: 'client_123',
  documents: [document.id]
});


// Get AI assistance
const response = await client.ai.chat({
  message: 'Help me review this contract',
  context: { documents: [document.id] }
});

2. Python SDK

Installation:

Terminal window
pip install zserved-api-client

Usage:

from zserved import ZServedClient


client = ZServedClient(
    base_url='https://zserved.cozyartz-media-group.workers.dev/api/v1',
    token='your_jwt_token'
)


# Upload document
with open('contract.pdf', 'rb') as file:
    document = client.documents.upload(
        file=file,
        name='Contract.pdf',
        type='contract',
        client_id='client_123'
    )


# Create job
job = client.jobs.create(
    title='Serve Summons',
    client_id='client_123',
    documents=[document.id]
)


# Get AI assistance
response = client.ai.chat(
    message='Help me review this contract',
    context={'documents': [document.id]}
)

This API Documentation provides comprehensive guidance for integrating with ZServed’s legal technology platform while maintaining professional compliance and security standards.

API Documentation: [Technical Documentation Team]
Security Review: [API Security and Compliance Team]
Professional Standards: [Legal Professional Advisory Board]
SDK Development: [Developer Relations Team]

For complete API reference and examples, see the full API documentation (35+ pages).