Partner API Documentation

Complete reference for all Partner API endpoints

Base URL: https://myservicelog.ie/api/v1/partner

Quick Start

  1. Obtain your API key from the Partner API management page
  2. Exchange your API key for an access token via POST /auth/token
  3. Use the access token in the Authorization: Bearer <token> header
  4. Make API calls to lookup vehicles, check usage, etc.
  5. Tokens expire after 1 hour - refresh using POST /auth/refresh

Endpoints

Health Check

GET /health No Auth Required

Check if the API is running and get the current API version. Use this endpoint to verify connectivity before making authenticated requests.

Example Request
curl https://myservicelog.ie/api/v1/partner/health
Example Response
{
    "success": true,
    "status": "healthy",
    "api_version": "v1"
}

Authentication

POST /auth/token API Key Required

Exchange your API key for a JWT access token. The token is valid for 1 hour and must be included in the Authorization header for all subsequent requests.

Headers
Header Type Description
X-API-Key string Your Partner API key (required)
Example Request
curl -X POST https://myservicelog.ie/api/v1/partner/auth/token \
  -H "X-API-Key: your_api_key_here"
Example Response
{
    "success": true,
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Vehicle Lookup

GET /vehicle/lookup Token Required

Full vehicle lookup including service history, garage notes, and usage metrics. This is the primary endpoint for comprehensive vehicle data.

Query Parameters
Parameter Type Description
vin string Vehicle Identification Number (17 characters)
reg string Registration number
country string Country code for registration (default: IE)

Note: Provide either vin or reg, not both.

Example Request
curl https://myservicelog.ie/api/v1/partner/vehicle/lookup?reg=191D12345 \
  -H "Authorization: Bearer your_access_token_here"
Example Response
{
    "success": true,
    "vehicle": {
        "vin": "WVWZZZ1KZCW123456",
        "registration": "191D12345",
        "make": "Volkswagen",
        "model": "Golf",
        "year": 2019,
        "colour": "Blue",
        "fuel_type": "Petrol",
        "engine_size": "1.4 TSI",
        "transmission": "Manual",
        "mileage": {
            "current": 45230,
            "last_updated": "2025-01-15",
            "clocking_flag": false
        },
        "nct": {
            "status": "valid",
            "expiry_date": "2025-06-30"
        },
        "service_history": [
            {
                "date": "2025-01-10",
                "type": "Full Service",
                "mileage": 45000,
                "garage": "ABC Motors",
                "verified": true
            }
        ],
        "garage_notes": [
            {
                "date": "2025-01-10",
                "note": "Timing belt due at 60,000km",
                "garage": "ABC Motors"
            }
        ]
    }
}

Vehicle Lookup (Minimal)

GET /vehicle/lookup/minimal Token Required

Quick vehicle lookup with basic data only. Useful for verification without fetching the full service history. Consumes the same credits as the full lookup.

Query Parameters
Parameter Type Description
vin string Vehicle Identification Number (17 characters)
reg string Registration number
country string Country code for registration (default: IE)
Example Request
curl https://myservicelog.ie/api/v1/partner/vehicle/lookup/minimal?vin=WVWZZZ1KZCW123456 \
  -H "Authorization: Bearer your_access_token_here"
Example Response
{
    "success": true,
    "vehicle": {
        "vin": "WVWZZZ1KZCW123456",
        "registration": "191D12345",
        "make": "Volkswagen",
        "model": "Golf",
        "year": 2019,
        "colour": "Blue",
        "mileage": 45230
    }
}

Client Information

GET /client/info Token Required

Get your account details including billing type, rate limits, and current billing period information.

Example Request
curl https://myservicelog.ie/api/v1/partner/client/info \
  -H "Authorization: Bearer your_access_token_here"
Example Response
{
    "success": true,
    "client": {
        "client_id": 123,
        "client_name": "John Smith",
        "client_type": "insurance",
        "company_name": "ABC Insurance Ltd",
        "billing_type": "subscription",
        "subscription_status": "active",
        "rate_limits": {
            "per_minute": 60,
            "per_day": 1000
        },
        "current_period": {
            "start": "2025-01-01T00:00:00",
            "end": "2025-01-31T23:59:59",
            "included_lookups": 25
        }
    }
}

Usage Statistics

GET /usage Token Required

Get your current usage statistics for the billing period, including lookups used, remaining allowance, and any overage charges.

Example Request
curl https://myservicelog.ie/api/v1/partner/usage \
  -H "Authorization: Bearer your_access_token_here"
Example Response
{
    "success": true,
    "usage": {
        "billing_period": {
            "start": "2025-01-01",
            "end": "2025-01-31"
        },
        "current_usage": 18,
        "included_lookups": 25,
        "remaining": 7,
        "overage_lookups": 0,
        "today_usage": 3
    }
}

Usage History

GET /usage/history Token Required

Get a paginated list of your lookup history. Useful for auditing and reconciliation.

Query Parameters
Parameter Type Description
limit integer Maximum records to return (default: 50, max: 100)
offset integer Offset for pagination (default: 0)
start_date string Filter start date (ISO format: 2025-01-01)
end_date string Filter end date (ISO format: 2025-01-31)
Example Request
curl "https://myservicelog.ie/api/v1/partner/usage/history?limit=10&offset=0" \
  -H "Authorization: Bearer your_access_token_here"
Example Response
{
    "success": true,
    "lookups": [
        {
            "lookup_id": 45678,
            "vin": "WVWZZZ1KZCW123456",
            "registration": "191D12345",
            "endpoint": "vehicle/lookup",
            "timestamp": "2025-01-15T14:30:00Z",
            "billable": true
        }
    ],
    "pagination": {
        "total": 127,
        "limit": 10,
        "offset": 0,
        "has_more": true
    }
}

Credits Balance

GET /credits/balance Token Required

Get your current credits balance. For pay-per-use clients, this shows prepaid credit balance. Subscription clients will receive subscription information instead.

Example Request
curl https://myservicelog.ie/api/v1/partner/credits/balance \
  -H "Authorization: Bearer your_access_token_here"
Example Response (Pay-per-use)
{
    "success": true,
    "credits": {
        "balance": 45,
        "billing_type": "pay_per_use",
        "price_per_credit_eur": 10.00
    }
}
Example Response (Subscription)
{
    "success": true,
    "credits": {
        "balance": null,
        "billing_type": "subscription",
        "message": "Subscription clients use monthly included lookups"
    }
}

Billing Invoices

GET /billing/invoices Token Required

Get your invoice history. Primarily for subscription clients but available to all.

Query Parameters
Parameter Type Description
limit integer Maximum invoices to return (default: 10, max: 50)
Example Request
curl https://myservicelog.ie/api/v1/partner/billing/invoices?limit=5 \
  -H "Authorization: Bearer your_access_token_here"
Example Response
{
    "success": true,
    "invoices": [
        {
            "invoice_id": "INV-2025-001",
            "date": "2025-01-01",
            "amount_eur": 50.00,
            "status": "paid",
            "description": "Monthly Subscription - January 2025",
            "pdf_url": "https://..."
        }
    ]
}

Error Responses

All API errors return a consistent JSON format with a success: false flag and descriptive error information.

Error Response Format
{
    "success": false,
    "error": "Error type",
    "message": "Human-readable error description"
}
Common HTTP Status Codes
Code Meaning Description
400 Bad Request Invalid parameters or missing required fields
401 Unauthorized Invalid or missing API key/token
403 Forbidden Account inactive or insufficient credits
404 Not Found Vehicle not found in database
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error - contact support

Rate Limits

API requests are rate-limited to ensure fair usage. Default limits are:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. The response headers include:

Contact support if you need higher rate limits for your use case.