OpenAPI Specification
openapi: 3.0.1
info:
contact:
email: christo.delange@roadsync.com
description: This API allows the Roadsync clients to manage aspects of the RoadSync service via an API.
license:
name: Copyright (c) 2020, RoadSync Inc.
title: Client API v1.8 authenticated invoice API
version: 1.8.45
x-api-id: 3ea39084-d8df-11ea-ad77-0017b600647f
x-audience: external-partner
servers:
- url: https://client-api.staging.roadsync.com/{basePath}
variables:
Product:
default: ClientApi
basePath:
default: v1
security:
- api_key: []
- session_token: []
tags:
- description: Invoice operations
name: invoice
paths:
/invoice/archive/{invoiceId}:
parameters:
- explode: true
in: path
name: invoiceId
required: true
schema:
$ref: '#/components/schemas/HashedId'
style: simple
get:
description: 'Archive an invoice by Id.
Note this is same function as /invoice/{invoiceId} DELETE for clients that only support OPTIONS,GET,POST.
'
operationId: invoice_archive_get
responses:
'200':
$ref: '#/components/responses/InvoiceArchiveGetResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Archive an invoice by Id
tags:
- invoice
options:
operationId: invoice_archive_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
/invoice/create:
options:
operationId: invoice_create_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
post:
description: Create an invoice
operationId: invoice_create_post
requestBody:
$ref: '#/components/requestBodies/InvoiceCreateRequest'
responses:
'200':
$ref: '#/components/responses/InvoiceCreateResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Create an invoice
tags:
- invoice
/invoice/list:
get:
description: Retrieve a list of invoices
operationId: invoice_list_get
parameters:
- description: 'Retrieve a list of invoices per company. Note that most users will have access to only one (their own) company and typically only
SuperAdmins will be able to access invoices from multiple companies.
paidState is optional with companyId and defaults to ''NA''
'
explode: true
in: query
name: companyId
required: false
schema:
$ref: '#/components/schemas/HashedId'
style: form
- description: 'Get a list of invoices filtered by location
'
explode: true
in: query
name: locationId
required: false
schema:
$ref: '#/components/schemas/HashedId'
style: form
- description: 'companyId is required with paidState. If no companyId is provided the default is the default from UserInfo if available.
Providing paidState without a companyId will return a BadRequestError
'
explode: true
in: query
name: paidState
required: false
schema:
$ref: '#/components/schemas/PaidStateEnum'
style: form
- explode: true
in: query
name: invoiceids
required: false
schema:
items:
$ref: '#/components/schemas/HashedId'
maxItems: 20
type: array
style: form
- explode: true
in: query
name: fromcreated
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- explode: true
in: query
name: tocreated
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- explode: true
in: query
name: archived
required: false
schema:
type: boolean
style: form
- explode: true
in: query
name: departmentid
required: false
schema:
$ref: '#/components/schemas/HashedId'
style: form
- explode: true
in: query
name: excludeauthorized
required: false
schema:
type: boolean
style: form
- explode: true
in: query
name: fromauth
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- explode: true
in: query
name: fromdel
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- explode: true
in: query
name: fromsentdate
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- description: "The default DefaultPageSize is 20.\nThe original idea was this: Ignore the 'limit' and return 20 items.\nHowever, the way this is implemented in the backend is this:\nif (limit or offset or ignoreLimit) {\n if limit > 0 { // A specific value between 1 and 20 inclusive retrieves that many items\n if limit <= DefaultPageSize {\n retrieve(limit)\n } else {\n retrieve(DefaultPageSize)\n }\n } else\n if ignoreLimit == false {\n retrieve(DefaultPageSize)\n }\n} else {\n retrieve(DefaultPageSize)\n}\n\nThis makes ignoreLimit semantics basically useless in that it is only considered if limit==0 and then it is the same as limit=DefaultPageSize!\n\nRecommendation: NEVER use ignoreLimit. Only use offset and limit.\n\nIn v2 of the API ignoreLimit will be silently ignored and have no effect on results whatsoever.\n"
explode: true
in: query
name: ignoreLimit
required: false
schema:
type: boolean
style: form
- explode: true
in: query
name: includeregular
required: false
schema:
type: boolean
style: form
- explode: true
in: query
name: includevoided
required: false
schema:
type: boolean
style: form
- explode: true
in: query
name: initialinvoicetypes
required: false
schema:
items:
$ref: '#/components/schemas/InvoiceType'
maxItems: 64
type: array
style: form
- explode: true
in: query
name: invoicestatuses
required: false
schema:
items:
$ref: '#/components/schemas/InvoiceStatus'
maxItems: 16
type: array
style: form
- explode: true
in: query
name: invoicetypes
required: false
schema:
items:
$ref: '#/components/schemas/InvoiceType'
maxItems: 16
type: array
style: form
- description: 'Upper limit for number of items to return. A number >= 1 and <= 20. Default: 20'
explode: true
in: query
name: limit
required: false
schema:
$ref: '#/components/schemas/Count'
style: form
- explode: true
in: query
name: locationids
required: false
schema:
items:
$ref: '#/components/schemas/HashedId'
maxItems: 16
type: array
style: form
- description: 'The offset of the requested page of "limit" items to retrieve. If there are 50 invoices and "limit"
is not provided then items 0 through 19 will be returned by default. If "offset" is 10, then
items 11 through <limit> will be returned.
'
explode: true
in: query
name: offset
required: false
schema:
$ref: '#/components/schemas/Count'
style: form
- explode: true
in: query
name: search
required: false
schema:
maxLength: 2048
pattern: /^.*$/
type: string
style: form
- explode: true
in: query
name: shiftid
required: false
schema:
$ref: '#/components/schemas/HashedId'
style: form
- explode: true
in: query
name: toauth
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- explode: true
in: query
name: todel
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- explode: true
in: query
name: tosentdate
required: false
schema:
$ref: '#/components/schemas/DateTime'
style: form
- description: Timeout in seconds for searching for invoices that meet the criteria. If the search exceeds this limit a Continuation response will be sent and optionally (if asyncResult == true and asynchronous results are availble) an asyncronous result set token.
explode: true
in: query
name: timeout
required: false
schema:
default: 19
format: float
maximum: 29
minimum: 1
type: number
style: form
- description: Turn on/off the asynchronous result set for this request if the `timeout` time is exceeded during the execution of this search.
explode: true
in: query
name: asyncResult
required: false
schema:
default: true
type: boolean
style: form
- description: Optionally indicate on subsequent search request (typically with the same filters) where the search in the master list of invoices should be resumed.
explode: true
in: query
name: searchStart
required: false
schema:
default: 0
format: int64
minimum: 0
type: number
style: form
- description: Optionally indicate on subsequent search request (typically with the same filters) where the search in the master list of invoices should be resumed.
explode: true
in: query
name: resultToken
required: false
schema:
maxLength: 256
pattern: /^.*$/
type: string
style: form
responses:
'200':
$ref: '#/components/responses/InvoiceListResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Retrieve a list of invoices
tags:
- invoice
options:
operationId: invoice_list_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
/invoice/report:
parameters:
- description: 'The format of the report. CSV is the default. Valid values are: CSV'
explode: true
in: query
name: format
required: false
schema:
$ref: '#/components/schemas/FormatEnum'
style: form
get:
description: Retrieve an invoice report in the designated format
operationId: invoice_report_get
responses:
'200':
$ref: '#/components/responses/InvoiceReportResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Retrieve an invoice report in the designated format
tags:
- invoice
options:
operationId: invoice_report_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
/invoice/search:
options:
operationId: invoice_search_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
post:
description: "Search for invoices with search criteria and retrieve a paged list of invoices.\n\nValid filters are:\n- All valid parameters of /invoice/list\n- Filters specific to /invoice/search as detailed below. TODO\n\nPagination has the defaults as specified in its schema, but 'pagination' is an optional search request attribute!\nFilters can have three items that apply to pagination (Supported by /invoice/list and factored in for compatibility):\n- offset\n- limit\n- ignoreLimit\nThe precedence of these filter items and pagination attributes are as follows:\n- No attributes from either set provided: Pagination defaults apply\n- No Pagination and some 'pagination' filters: Pagination defaults with overrides as follows when applicable:\n PageNumber: offset / ItemsPerPage\n TotalItems: limit if ignoreLimit==false else ItemsPerPage\n TotalPages: 1\n ItemsPerPage: 20\n- Pagination provided: limit filters are completely ignored\n\nNOTE: The following pattern in the request body/shape constitutes a request for \"the default Pagination settings\"\nand will cause 'limit' filters to be IGNORED because you are providing explicit Pagination:\n{\n \"pagination\": \"\"\n}\n\nFilters:\n- Valid parameters of /invoice/list\nExamples:\n Include voided invoices:\n\n \"filters\": [\n {\n \"type\": \"boolean\",\n \"field\": \"includevoided\",\n \"value\": \"true\"\n }\n ]\n\n Multiple, specific invoices:\n\n \"filters\": [\n {\n \"type\": \"list\",\n \"field\": \"invoiceids\",\n \"value\": \"A1A1A1A1A1A1A1A1,B2B2B2B2B2B2B2B2,C3C3C3C3C3C3C3C3\"\n }\n ]\n\n Weak pagination via limit and offset:\n\n \"filters\": [\n {\n \"type\": \"integer\",\n \"field\": \"limit\",\n \"value\": \"10\"\n },\n {\n \"type\": \"integer\",\n \"field\": \"offset\",\n \"value\": \"10\"\n },\n {\n \"type\": \"boolean\",\n \"field\": \"includevoided\",\n \"value\": \"true\"\n }\n ]\n\n Better pagination:\n\n \"filters\": [\n {\n \"type\": \"boolean\",\n \"field\": \"includevoided\",\n \"value\": \"true\"\n }\n ],\n \"pagination\": {\n \"TotalItems\": 20,\n \"ItemsPerPage\": 10,\n \"PageNumber\": 2\n }\n"
operationId: invoice_search_post
requestBody:
$ref: '#/components/requestBodies/InvoiceSearchRequest'
responses:
'200':
$ref: '#/components/responses/InvoiceSearchResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Search for invoices
tags:
- invoice
/invoice/stats:
get:
description: Retrieve invoices statistics
operationId: invoice_stats_get
responses:
'200':
$ref: '#/components/responses/InvoiceStatsResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Retrieve invoices statistics
tags:
- invoice
options:
operationId: invoice_stats_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
/invoice/update:
options:
operationId: invoice_update_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
post:
description: Update an invoice
operationId: invoice_update_post
requestBody:
$ref: '#/components/requestBodies/InvoiceUpdateRequest'
responses:
'200':
$ref: '#/components/responses/InvoiceUpdateResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Update an invoice
tags:
- invoice
/invoice/{invoiceId}:
parameters:
- explode: true
in: path
name: invoiceId
required: true
schema:
$ref: '#/components/schemas/HashedId'
style: simple
delete:
description: Archive an invoice by Id
operationId: invoice_archive_delete
responses:
'200':
$ref: '#/components/responses/InvoiceDeleteResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Archive an invoice by Id
tags:
- invoice
get:
description: Retrieve an invoice by Id
operationId: invoice_get_get
responses:
'200':
$ref: '#/components/responses/InvoiceGetResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security:
- api_key: []
- session_token: []
summary: Retrieve an invoice by Id
tags:
- invoice
options:
operationId: invoice_get_options
responses:
'200':
$ref: '#/components/responses/Options200'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFound404'
'429':
$ref: '#/components/responses/TooManyRequests429'
'500':
$ref: '#/components/responses/ServiceError500'
default:
$ref: '#/components/responses/UnexpectedError'
security: []
tags:
- invoice
/:
get:
summary: Get a list of invoices
description: 'Get a list of invoices
'
tags:
- invoice
operationId: get-invoice-list
parameters:
- name: offset
in: query
schema:
type: integer
description: The starting position for result paging
- name: limit
in: query
schema:
type: integer
description: The maximum number of results to return. Maximum is 21
- name: status
in: query
schema:
type: array
description: A list of invoice statuses to filter by
items:
type: string
enum:
- unknown
- new
- processing
- completed
- failed
- waitingapproval
- pendingreview
- sent
- accepted
- rejected
- markedaspaid
- validated
- validatedandfailed
- name: invoiceNumber
in: query
schema:
type: string
description: The invoice number (RS TRANS#) of the invoice to get. If present, all other filters will be ignored.
- name: fromDeletedAt
in: query
schema:
type: string
format: date-time
description: The lower bound of the deleted date range. Only invoices deleted after this date will be included in the response. Provide the date and time in ISO 8601 format (e.g., "2023-06-15T09:30:00Z").
- name: toDeletedAt
in: query
schema:
type: string
format: date-time
description: The upper bound of the deleted date range. Only invoices deleted before this date will be included in the response. Provide the date and time in ISO 8601 format (e.g., "2023-06-15T09:30:00Z").
- name: fromAuthorizedAt
in: query
schema:
type: string
format: date-time
description: The lower bound of the authorized date range. Only invoices authorized after this date will be included in the response. Provide the date and time in ISO 8601 format (e.g., "2023-06-15T09:30:00Z").
- name: toAuthorizedAt
in: query
schema:
type: string
format: date-time
description: The upper bound of the authorized date range. Only invoices authorized before this date will be included in the response. Provide the date and time in ISO 8601 format (e.g., "2023-06-15T09:30:00Z").
- name: customField
in: query
schema:
type: string
description: Custom Field name and value (stringified object with the structure of '{name:name,value:value}') of the invoice to get.
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
data:
type: array
items:
$ref: '#/components/schemas/Invoice_2'
examples:
success:
$ref: '#/components/examples/invoiceListResponseExample'
default:
$ref: '#/components/responses/ErrorResponse'
security:
- ApiKey: []
post:
summary: Create an invoice
description: 'Create an invoice.
'
tags:
- invoice
operationId: create-invoice
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
companyId:
type: string
description: The RoadSync ID of the company creating the invoice
locationId:
type: string
description: The RoadSync ID of the location creating the invoice
lineItems:
type: array
items:
$ref: '#/components/schemas/LineItem'
name:
type: string
description: The payer's name
email:
type: string
description: The payer's email address. Either email or phone is required.
phone:
type: string
description: The payer's phone number. Either phone or email is required.
description:
type: string
description: Optional description of the invoice
comments:
type: string
description: Optional comments that will be added to the invoice and receipt.
customFields:
type: object
description: Values for fields configured for the current location. These can be configured to be required.
shiftId:
type: string
description: The employee shift when the invoice is being created. Required if the location has at least one shift configured.
storeCardOnFile:
type: boolean
description: Option to save the card for future invoice payments
required:
- companyId
- locationId
- lineItems
- name
example:
locationId: O8MqwQ1X3L5Ryax4OanNK2lGxerYA8
companyId: 2POMkDK9LZNw3BP0GBGoExejWylYq0
lineItems:
- productId: 8Gdahuy5Nw3BI86BNgtdylYq0
description: Service charge
amount: 200
isTaxable: true
phone: '4041231234'
email: testuser@roadsync.com
name: John Doe
customFields:
mileage: '1000'
shiftId: kNbRqo6QJjLnxa75yBPzpDZ193MlmA
comments: These are the comments
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Invoice_2'
examples:
success:
$ref: '#/components/examples/invoiceResponseExample'
default:
$ref: '#/components/responses/ErrorResponse'
security:
- ApiKey: []
/{id}:
parameters:
- name: id
in: path
schema:
type: string
required: true
description: The id of the invoice.
get:
summary: Get an invoice
description: 'Get an invoice.
'
tags:
- invoice
operationId: get-invoice
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Invoice_2'
examples:
success:
$ref: '#/components/examples/invoiceResponseExample'
default:
$ref: '#/components/responses/ErrorResponse'
security:
- ApiKey: []
patch:
summary: Update invoice fields
description: 'Update invoice fields. Only the passed in fields will be updated on the invoice.
'
tags:
- invoice
operationId: patch-invoice
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
lineItems:
type: array
items:
$ref: '#/components/schemas/LineItem'
name:
type: string
description: The payer's name
email:
type: string
description: The payer's email address
phone:
type: string
description: The payer's phone number
description:
type: string
description: Optional description of the invoice
comments:
type: string
description: Optional comments that will be added to the invoice and receipt.
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
$r
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roadsync/refs/heads/main/openapi/roadsync-invoice-api-openapi.yml