Autovu Public API Documentation

Base URL: https://api.autovusolutions.com

 

The Autovu Public API provides secure, high-performance access to core CRM entities, including diaries, jobs, sites, and site products. The API adheres to RESTful principles, using standard HTTP verbs and semantic status codes.

---

1. Authentication & Security

The API utilises a strict, triple-header authentication mechanism. All requests must include the following HTTP headers. Failure to provide valid headers will result in a 401 Unauthorized response.

 

Header	Description
api-key	Your primary integration token (URL-encoded base64 encrypted string).
scopecode	A Base64-encoded Secure Scope Token. This token cryptographically restricts your API Key to specific functional scopes (e.g., Diary endpoints only). You must pass the exact string provided in your CRM API settings panel.
api-password	The global API password assigned to the company tenant.

 

Available Endpoint Scopes:

• DiaryEndpoints
• JobEndpoints
• SiteEndpoints
• SiteProductEndpoints

---

2. Rate Limiting

To ensure system stability, the API enforces strict enterprise-grade rate limits. Limits are evaluated atomically per api-key.

• Per Minute Limit: 60 requests
• Per Day Limit: 5,000 requests

 

Rate Limit Headers

Every successful response includes headers detailing your current quota:

• X-RateLimit-Minute-Remaining
• X-RateLimit-Daily-Remaining

 

If you exceed these limits, the API will reject the request with a 429 Too Many Requests status code and include the following headers to help you manage backoff:

• Retry-After: Time in seconds until you can make another request.
• X-RateLimit-Minute-Limit: 60
• X-RateLimit-Daily-Limit: 5000

Architectural Advice: Implement robust exponential backoff strategies in your client applications to handle 429 responses gracefully. Do not aggressively poll the endpoints.

---

3. Standardised Pagination

Endpoints that return collections (e.g., Diary Overview, Site Jobs) wrap the response in a standardised JSON payload containing both Metadata and Data.

 

Sample Paginated Response:

{
  "Metadata": {
    "TotalRecords": 150,
    "CurrentPage": 1,
    "PageSize": 50,
    "TotalPages": 3,
    "HasNextPage": true,
    "HasPreviousPage": false
  },
  "Data": [
    // ... Array of objects ...
  ]
}

---

4. Endpoints Directory

Diary & Search

Get Diary Overview

Retrieves a chronological list of scheduled visits. Supports single-day or date-range lookups (maximum span of 31 days).

• Endpoint: GET /diary/{startDate}
• Required Scope: DiaryEndpoints
• URL Parameters:
  • startDate (Required): ISO 8601 format (YYYY-MM-DD).
• Query Parameters:
  • endDate (Optional): ISO 8601 format. Must not be chronologically before the start date.
  • pageNumber (Optional): Default 1.
  • pageSize (Optional): Min 1, Max 100. Default 50.
• Returns: Paginated wrapper containing an array of DiaryDto.

Search Sites

Performs a full-text search against site/customer records by address, name, or postcode.

• Endpoint: GET /diary/search/sites
• Required Scope: DiaryEndpoints
• Query Parameters:
  • q (Required): Search string (minimum 2 characters).
  • includeArchive (Optional): Boolean (Default false).
• Returns: Unpaginated array of up to 50 matching SearchSiteDto records.

Search Jobs by Order Number

Strict lookup for jobs matching a Customer Order Number, PO, or Contract Reference.

• Endpoint: GET /diary/search/jobs
• Required Scope: DiaryEndpoints
• Query Parameters:
  • orderno (Required): Order number string (minimum 2 characters).
  • includeArchive (Optional): Boolean (Default false).
• Returns: Unpaginated array of up to 50 matching SearchJobDto records.

---

Jobs

Get Single Job Details

Retrieves a comprehensive payload for a single job, natively embedding its array of visits and hierarchical checklist items.

• Endpoint: GET /jobs/{jobId}
• Required Scope: JobEndpoints
• URL Parameters:
  • jobId (Required): Integer ID of the job.
• Returns: A JobDetailDto object containing core details, a Visits array, and a ChecklistGroups array.
• Responses: Returns 404 Not Found if the job does not exist or access is restricted.

---

Sites (Locations)

Get Site Overview

Retrieves core geographic, contact, and account details for a top-level Site (Client).

• Endpoint: GET /site/{clientID}
• Required Scope: SiteEndpoints
• URL Parameters:
  • clientID (Required): Integer ID of the site.
• Returns: A SiteDetailDto object. Returns 404 Not Found if invalid.

---

Site Products (Equipment/Assets)

Get Site Product Overview

Retrieves granular details about a specific product/asset assigned to a site, including make, model, serial numbers, and warranty/contract dates.

• Endpoint: GET /siteproduct/{productRef}
• Required Scope: SiteProductEndpoints
• URL Parameters:
  • productRef (Required): Integer ID of the product.
• Returns: A SiteProductDto object. Returns 404 Not Found if invalid.

 

Get Site Product Jobs

Retrieves a paginated history of all service jobs executed against a specific site product.

• Endpoint: GET /siteproduct/{productRef}/jobs
• Required Scope: SiteProductEndpoints
• URL Parameters:
  • productRef (Required): Integer ID of the product.
• Query Parameters:
  • pageNumber (Optional): Default 1.
  • pageSize (Optional): Min 1, Max 100. Default 50.
• Returns: Paginated wrapper containing an array of SiteProductJobsDto.

---

5. Error Handling & Status Codes

The API employs a global exception filter that maps application states to semantic HTTP status codes.

Code	Description	Resolution
200	OK	The request succeeded.
400	Bad Request	Invalid parameters (e.g., malformed date string, date span > 31 days). Check the response body for the exact validation failure.
401	Unauthorized	Missing, malformed, or invalid authentication headers. Verify api-key, scopecode, and api-password.
404	Not Found	The requested resource does not exist, or your API key lacks tenant/record-level permission to view it.
429	Too Many Requests	Rate limit exceeded. Observe the Retry-After header.
500	Internal Server Error	An unexpected fault occurred. The engineering team is automatically notified via high-priority alerts with full trace data.