RO Writer API Overview

RO Writer is a shop management platform used by automotive repair shops. Shops rely on a range of third-party tools for scheduling, customer communication, fleet management, reporting, and other business functions.

The RO Writer Integration APIs enable you to manage customers, vehicles, appointments, and repair orders for individual stores. All requests pass through API Management (APIM), which handles subscription validation and identity injection.

How the Integration Works

Integration partners can read and write shop data for individual shop locations. Each partner receives credentials that identify their organization, and each API call targets a specific shop by its license number. These APIs support multiple shops from a single integration.

The RO Writer APIM manages partner subscriptions, enforces authentication, and routes requests to the appropriate shop. The APIs follow RESTful conventions, use JSON for all requests and responses, and return standardized error formats.

Benefits of Using the Partner Integration

  • Access to core RO Writer shop data through a single, consistent API surface.

  • One set of credentials works across all shops that have enabled your integration.

  • Standard REST patterns and JSON formatting reduce development time.

  • Paginated search endpoints make it easy to retrieve and sync large datasets.

  • Automated data flow between RO Writer and third-party tools reduces manual entry.

  • Data stays in sync across platforms.

Onboarding

When you decide to sign up for the APIM portal, you will work with someone on the RO Writer team who will configure your API integration account. When your account setup is complete, the RO Writer team member will email you your login credentials so that you can access your profile.

To Access Your Profile

Complete these steps:

  1. After the RO Writer team member has configured your profile, open the email with your login credentials.

  2. Navigate to the RO Writer API Developer Portal.

  3. Log in to the portal using the credentials provided.

  4. Open your Profile page and click Subscriptions. Your subscription keys appear on your Profile page.

Authentication

Every request requires two layers of authentication.

  1. Ocp-Apim-Subscription: This is the subscription key that validates your APIM subscription.

  2. X-Client-Id: The license number of the store you are targeting.

You must include these values with each request when calling the API from your application, Postman, or any other tool outside the developer portal. When you test an API directly in the RO Writer API Developer Portal, your subscription key is included automatically.

Access Level Permissions

During onboarding, the RO Writer team assigns permission bundles to your account. These bundles determine which APIs you have read and write access to.

Authentication Process

Authentication for each API request includes the following:

  • Subscription: Your APIM subscription key validates that you have an active account. This is your APIM subscription key (Ocp-Apim-Subscription-Key). You can find this key on your Profile page.

  • Shop Licensing: The target shop must have the relevant integration product enabled. This ensures shops control which third-party integrations connect to their data. You provide the shop license number (X-Client-Id) with each request.

  • Access Level Permissions: Your partner account is assigned permission bundles that determine which APIs you can access and whether you have read access, write access, or both.

Available APIs and Base URLs

The API Portal URL is https://developer.rowriter.com.

The full request URL pattern is https://{gateway-host}/{Resource}/v{#}/.

To Access Each Endpoint

You access each endpoint by clicking the link in the list on the main API page. The endpoint window opens, displaying all available information for that endpoint.

Endpoint Access

The RO Writer API Developer portal window displays all available APIs and their endpoints to every signed-in partner. The portal does not filter the endpoint list based on your account's permissions. You always see all available endpoints, whether you have permission to access them or not.

You can browse the documentation for any endpoint, view its request and response schemas, and use the APIM window to attempt a test request.

How Access Is Enforced

Access is enforced when you send a request, not when you view the endpoint on the portal. Each request passes through multiple authorization checks before it reaches the API. If any check fails, the request is rejected with a 401 Unauthorized response.

If you receive a 401 error on an endpoint you expect to have access to, verify that:

  • Your partner account has been assigned the correct permission bundle for that API.

  • Your permission bundle includes the correct access level (read, write, or both).

  • The target shop's license includes the integration product.

All error responses use general language and include a traceid field. Provide the traceid when reporting access issues so the request can be traced through the system.

Versioning

All APIs use path-based versioning. The current version is v1, included in every endpoint URL:

  • /Customers/v1

  • /Vehicles/v1

  • /Appointments/v1

  • /RepairOrders/v1

Pagination

List endpoints return paginated results. Use these query parameters to control pagination:

  • PageSize: The number of records per page. The default is 100, which is also the max value.

  • PageNumber: The page number to retrieve, starting at 1 (which is the default).

Paginated responses include a PageInfo object with totalRecords, pageSize, and currentPageNumber.

Error Response Codes

All endpoints use these standard HTTP response codes.

  • 200: Success (GET requests).

  • 201: Created (POST requests). The Location header contains the URL of the new resource.

  • 204: No Content (PUT and PATCH requests).

  • 401: Unauthorized. The request is missing required headers, or your account lacks the necessary permissions.

  • 404: Not Found. The requested resource does not exist.

  • 406: Not Acceptable. The request's Accept header specifies an unsupported media type.

  • 415: Unsupported Media Type. The request body is not application/json.

  • 422: Validation Error. The request body failed validation. The response includes field-level error details.

  • 429: Rate Limited. You have exceeded the allowed request rate.

  • 500: Internal Server Error.

Error Response Schemas

All endpoints share a common set of error response schemas.

  • ProblemDetails: RFC 7807 standard for machine-readable error responses (401, 404, 406, 500).

  • ValidationProblemDetails: Validation errors (422) that include field-level error messages.

  • Response429ProblemDetails: Rate limit errors (429).

Where to Find the Field Definitions in Each Schema

You can view the complete field definitions for any endpoint in the endpoint window. The developer portal displays every endpoint with its parameters, request body, and response structure.

When you open an endpoint:

  • The Parameters section shows headers and query parameters.

  • The Request body section shows the schema with all fields, types, and descriptions.

  • The Responses section shows the response schema and possible status codes.

Each field includes a description, data type (string, integer, UUID, date, etc.), and any constraints such as maximum length or required status.

Updates

There are two main types of changes: non-breaking and breaking changes.

Non-Breaking Changes

Non-breaking changes are updates that do not affect existing integrations. These changes may be applied to the current API version without advance notice.

Non-breaking changes include:

  • Adding new optional fields to request or response schemas.

  • Adding new endpoints to an existing API.

  • Adding new query parameters to search endpoints.

  • Updating field descriptions or documentation.

  • Improving error messages or adding detail to error responses.

  • Performance improvements or internal optimizations.

Breaking Changes

Breaking changes are updates that may require integration partners to modify their code.

Breaking changes include:

  • Removing or renaming an existing endpoint.

  • Removing or renaming fields in a request or response schema.

  • Changing the data type or format of an existing field.

  • Changing a field from optional to required.

  • Modifying authentication or authorization requirements.

  • Changing the behavior of an existing endpoint in a way that alters its output.

Breaking Changes Result in a New Version

When a breaking change is necessary, RO Writer releases a new API version (for example, v2). The previous version remains available for 30 days but is no longer recommended. Partners should begin migrating to the current version as soon as the deprecation notice is issued.

The process for introducing breaking changes is as follows:

  1. New version release: The updated API is published under a new version path (for example, /Customers/v2).

  2. Partner notification: Integration partners are notified of the new version, including a summary of changes and migration guidance.

  3. Parallel availability: Both the previous and new versions remain available during the transition period.

  4. Deprecation notice: The previous version is marked as deprecated. A message that includes the deprecation date is displayed on the RO Writer API Developer Portal window.

  5. Retirement: After the transition period, the deprecated version is retired and no longer available.

Partner Responsibilities

Integration partners are responsible for:

  • Monitoring the developer portal for API updates and announcements.

  • Testing integrations against new API versions during the transition period.

  • Completing migration before the retirement date of a deprecated version.

  • Designing integrations to handle new optional fields.