CO3 logo
API docs by Redocly

CO3 Open Api (1.5.4.)

Download OpenAPI specification:Download

E-mail: tech@co3.eu Terms of Service

CO3 Open Api - documentation.

Monitoring Orders

Relates to a model of cooperation, where Vehicle's monitoring is available only during Monitoring Orders. Based on the long-time consent type between process parties - Shipper and Carrier.

createMonitoringOrder

Create a Monitoring Order for a given Vehicle.

Authorizations:
oauth2
query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

Request Body schema: application/json
required

CreateMonitoringOrderRequest

object (CompanyIdentifier)
endDate
required
integer <epoch>
externalSystemId
required
string
name
string
shipperCompanyId
required
string <uuid>
startDate
required
integer <epoch>
Array of objects (CreateMonitoringOrderStopRequest)
Array of objects (CreateMonitoringOrderVehicleRequest)

Responses

Request samples

Content type
application/json
{
  • "carrierCompany": {
    },
  • "endDate": 1638466810,
  • "externalSystemId": "ORDER-2021-12345",
  • "name": "Sample name",
  • "shipperCompanyId": "626ac215-2364-4a23-aa10-6daaef052774",
  • "startDate": 1638466810,
  • "stops": [
    ],
  • "vehicles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "626ac215-2364-4a23-aa10-6daaef052774",
  • "externalSystemId": "ORDER-2021-12345",
  • "name": "Sample name",
  • "active": true,
  • "startDate": 1717165559000,
  • "endDate": 1717165598000,
  • "shipperCompanyId": "626ac215-2364-4a23-aa10-6daaef052774",
  • "carrierDetails": {
    },
  • "vehicleDetails": [
    ],
  • "stops": [
    ],
  • "creationDate": 1638466810,
  • "statusDate": 1638466810
}

getIncomingMonitoringOrders

Get a paginated list of Incoming Monitoring Orders in the context company from the shippers.

Authorizations:
oauth2
query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company Id. Company act as carrier.

externalSystemId
string
Example: externalSystemId=ORDER-2021-12345

External system id. Providing a value will filer the result data.

shipperCompanyId
string <uuid>
Example: shipperCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Shipper company id. Proving a value will filter the result data.

page
required
integer <int32>
Example: page=0

Page index to be returned. Page Numeration starts from 0.

size
required
integer <int32>
Example: size=25

Number of returned elements per page.

sortBy
string
Enum: "startDate" "endDate" "creationDate"
Example: sortBy=startDate

Sort by parameter

sortDirection
string
Enum: "ASC" "DESC"
Example: sortDirection=ASC

Sort direction

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "size": 25,
  • "totalElements": 100,
  • "totalPages": 4,
  • "tours": [
    ]
}

getOutgoingMonitoringOrders

Get paginated list of outgoing Monitoring Orders from the context company to the carriers. Required scope: orders.tour.read

Authorizations:
oauth2
query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company Id. Company act as shipper.

carrierCompanyId
string <uuid>
Example: carrierCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Carrier company id. Providing a value will filer the result data.

externalSystemId
string
Example: externalSystemId=626ac215-2364-4a23-aa10-6daaef052774

External system id. Providing a value will filer the result data.

page
required
integer <int32>
Example: page=0

Page index to be returned. Page Numeration starts from 0.

size
required
integer <int32>
Example: size=25

Number of returned elements per page.

sortBy
string
Enum: "startDate" "endDate" "creationDate"
Example: sortBy=startDate

Sort by parameter

sortDirection
string
Enum: "ASC" "DESC"
Example: sortDirection=ASC

Sort direction

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "size": 25,
  • "totalElements": 100,
  • "totalPages": 4,
  • "tours": [
    ]
}

getMonitoringOrder

Get Monitoring Order by external system id.

Authorizations:
oauth2
path Parameters
externalSystemId
required
string
Example: ORDER-2021-12345

Monitoring Order identifier

query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id

Responses

Response samples

Content type
application/json
{
  • "id": "626ac215-2364-4a23-aa10-6daaef052774",
  • "externalSystemId": "ORDER-2021-12345",
  • "name": "Sample name",
  • "active": true,
  • "startDate": 1717165559000,
  • "endDate": 1717165598000,
  • "shipperCompanyId": "626ac215-2364-4a23-aa10-6daaef052774",
  • "carrierDetails": {
    },
  • "vehicleDetails": [
    ],
  • "stops": [
    ],
  • "creationDate": 1638466810,
  • "statusDate": 1638466810
}

updateMonitoringOrder

Update existing Monitoring Order with given data. Data not provided or with null values will be not changed.

Authorizations:
oauth2
path Parameters
externalSystemId
required
string
Example: ORDER-2021-12345

External system id.

query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

Request Body schema: application/json
required

monitoringOrder

object (CompanyIdentifier)
endDate
integer <epoch>
externalSystemId
string
name
string
shipperCompanyId
string <uuid>
startDate
integer <epoch>
Array of objects (UpdateMonitoringOrderStopRequest)

If stops are not null and not empty previous stops will be replaced.

Array of objects (UpdateMonitoringOrderVehicleRequest)

Responses

Request samples

Content type
application/json
{
  • "carrierCompany": {
    },
  • "endDate": 1638466810,
  • "externalSystemId": "ORDER-2021-12345",
  • "name": "Sample name",
  • "shipperCompanyId": "626ac215-2364-4a23-aa10-6daaef052774",
  • "startDate": 1638466810,
  • "stops": [
    ],
  • "vehicles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "626ac215-2364-4a23-aa10-6daaef052774",
  • "externalSystemId": "ORDER-2021-12345",
  • "name": "Sample name",
  • "active": true,
  • "startDate": 1717165559000,
  • "endDate": 1717165598000,
  • "shipperCompanyId": "626ac215-2364-4a23-aa10-6daaef052774",
  • "carrierDetails": {
    },
  • "vehicleDetails": [
    ],
  • "stops": [
    ],
  • "creationDate": 1638466810,
  • "statusDate": 1638466810
}

deactivateMonitoringOrder

Deactivate Monitoring Order for a given external system id.

Authorizations:
oauth2
path Parameters
externalSystemId
required
string
Example: ORDER-2021-12345

External system id.

query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

Responses

Response samples

Content type
application/json
{
  • "timestamp": 1638466810,
  • "status": 400,
  • "error": "string",
  • "errorCode": "INVALID_DATA",
  • "message": "string",
  • "path": "string"
}

getCalculatedEta

Get calculated ETA value for a specific stop. Required scopes: orders.tour.read, orders.eta.read

Authorizations:
oauth2
path Parameters
externalSystemId
required
string
Example: ORDER-2021-12345

External system id.

query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

stopId
required
string <uuid>
Example: stopId=626ac215-2364-4a23-aa10-6daaef052774

Stop id for which ETA is calculated

Responses

Response samples

Content type
application/json
{
  • "calculatedEstimates": [
    ],
  • "failedEstimates": [
    ]
}

getMonitoringOrderVehiclePosition

Get list of vehicle positions of given Monitoring Orders. Required scope: orders.tour.positions.read

Authorizations:
oauth2
path Parameters
externalSystemId
required
string
Example: ORDER-2021-12345

External system id.

query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

shipperCompanyId
required
string <uuid>
Example: shipperCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Shipper company id.

exclusiveStartKey
string <uuid>
Example: exclusiveStartKey=100ac215-2364-9878-aa10-6daaef05asdf

Position identifier from which to start retrieve positions

filterBy
string
Enum: "positionTimestamp" "serverTimestamp"
Example: filterBy=positionTimestamp

Available timestamp filters.

limit
integer <int32>
Example: limit=2000

Limit of returned elements per Vehicle. Min:1, Max: 2000, Default: 2000

sortOrder
string
Enum: "ASC" "DESC"
Example: sortOrder=ASC

Specifies whether location will be fetched from the start of the end. Fetching from start by default (ASC)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getMonitoringOrderVehiclePositionWithAdvancedData

Get a list of vehicle positions with advanced data of given Monitoring Orders. Required scope: orders.positions.ads.read

Authorizations:
oauth2
path Parameters
externalSystemId
required
string
Example: ORDER-2021-12345

External system id.

query Parameters
contextCompanyId
required
string <uuid>
Example: contextCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

shipperCompanyId
required
string <uuid>
Example: shipperCompanyId=626ac215-2364-4a23-aa10-6daaef052774

Shipper company id.

exclusiveStartKey
string <uuid>
Example: exclusiveStartKey=100ac215-2364-9878-aa10-6daaef05asdf

Position identifier from which to start retrieve positions

filterBy
string
Enum: "positionTimestamp" "serverTimestamp"
Example: filterBy=positionTimestamp

Available timestamp filters.

limit
integer <int32>
Example: limit=2000

Limit of returned elements per Vehicle. Min:1, Max: 2000, Default: 2000

sortOrder
string
Enum: "ASC" "DESC"
Example: sortOrder=ASC

Specifies whether location will be fetched from the start of the end. Fetching from start by default (ASC)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getAvailableVehicles

Authorizations:
oauth2
path Parameters
companyId
required
string <uuid>
Example: 626ac215-2364-4a23-aa10-6daaef052774

Get Available Vehicle for Companies

query Parameters
licensePlate
string
Example: licensePlate=WZ746N

Vehicle licence plate number

licensePlateCountryCode
string <ISO code>
Example: licensePlateCountryCode=PL

Vehicle licence plate country code

Responses

Response samples

Content type
application/json
{
  • "companiesWithVehicles": [
    ]
}

isAvailableVehicle

Verifies if given vehicle can be used fot Monitoring creation. May return more than entry if a vehicle is used by more than one company (eg. when a Vehicle is shared between them). Returns empty list if the Vehicle is not accessible.

Authorizations:
oauth2
path Parameters
companyId
required
string <uuid>
Example: 626ac215-2364-4a23-aa10-6daaef052774

Get Available Vehicle for Companies

query Parameters
licensePlate
required
string
Example: licensePlate=WZ746N

Vehicle licence plate number

licensePlateCountryCode
required
string <ISO code>
Example: licensePlateCountryCode=PL

Vehicle licence plate country code

Responses

Response samples

Content type
application/json
{
  • "companiesWithVehicles": [
    ]
}

Permanent Vehicle Monitoring

Relates to a model of cooperation, where Vehicles are monitored permanently, regardless to Monitoring Orders. Based on the permanent consent type between the Vehicle owner and companies which receives a permission (share) for the vehicle.

getVehiclesForPermanentMonitoring

Returns a list of Vehicles which can be monitored in a permanent mode.

Authorizations:
oauth2
path Parameters
companyId
required
string <uuid>
Example: f70b5598-0b7c-46fe-bb18-b69693d1313f
query Parameters
licencePlateNumber
string
Example: licencePlateNumber=DW12345

Vehicle licence plate number

licencePlateCountryCode
string <ISO code>
Example: licencePlateCountryCode=PL

Vehicle licence plate country code

taxNumber
string
Example: taxNumber=123456789

Vehicle owner tax number

taxNumberCountryCode
string <ISO code>
Example: taxNumberCountryCode=PL

Vehicle owner tax number country code

page
integer
Example: page=1
size
integer
Example: size=25

Responses

Response samples

Content type
application/json
{
  • "page": 1,
  • "size": 25,
  • "totalVehicles": 100,
  • "vehicles": [
    ]
}

getLastTraceData

Returns a vehicle last trace data.

Authorizations:
oauth2
path Parameters
licencePlateNumber
required
string
Example: DW12345
licencePlateCountryCode
required
string
Example: PL
query Parameters
companyId
required
string <uuid>
Example: companyId=626ac215-2364-4a23-aa10-6daaef052774

Company id.

Responses

Response samples

Content type
application/json
{
  • "traces": [
    ]
}

getAdvancedLastTraceData

Returns a vehicle last trace advanced data.

Authorizations:
oauth2
path Parameters
licensePlateNumber
required
string
Example: DW12345
licensePlateCountryCode
required
string
Example: PL
query Parameters
companyId
required
string <uuid>
Example: companyId=626ac215-2364-4a23-aa10-6daaef052774

Company id.

Responses

Response samples

Content type
application/json
{
  • "traces": [
    ]
}

getHistoricalPositionsData

Returns all Vehicle's positions data.

Authorizations:
oauth2
path Parameters
licencePlateNumber
required
string
Example: DW12345
licencePlateCountryCode
required
string
Example: PL
query Parameters
companyId
required
string <uuid>
Example: companyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

limit
number
Default: 2000

Indicates the maximum number of requested positions per Vehicle. Must be in range [1, 2000].

exclusiveStartKey
string <uuid>
Example: exclusiveStartKey=626ac215-2364-4a23-aa10-6daaef052774

Indicates the position identifier (UUID format) that should be considered as a start for the given request.

dateFrom
number <Epoch in seconds>

Date from (Unix Timestamp in seconds). Default value dateTo - 24h

dateTo
number <Epoch in seconds>

Date to (Unix Timestamp in seconds). Default value CURRENT_TIME

Responses

Response samples

Content type
application/json
{
  • "traces": [
    ]
}

getAdvancedHistoricalPositionsData

Returns all Vehicle's positions advanced data.

Authorizations:
oauth2
path Parameters
licensePlateNumber
required
string
Example: DW12345
licensePlateCountryCode
required
string
Example: PL
query Parameters
companyId
required
string <uuid>
Example: companyId=626ac215-2364-4a23-aa10-6daaef052774

Context company id.

limit
number
Default: 2000

Indicates the maximum number of requested positions per Vehicle. Must be in range [1, 2000].

exclusiveStartKey
string <uuid>
Example: exclusiveStartKey=626ac215-2364-4a23-aa10-6daaef052774

Indicates the position identifier (UUID format) that should be considered as a start for the given request.

dateFrom
number <Epoch in seconds>

Date from (Unix Timestamp in seconds). Default value dateTo - 24h

dateTo
number <Epoch in seconds>

Date to (Unix Timestamp in seconds). Default value CURRENT_TIME

Responses

Response samples

Content type
application/json
{
  • "traces": [
    ]
}

checkCompanyExistence

At least 1 input parameter is required. Vat number is checked first. If not found, the company name value is used for search.

Authorizations:
oauth2
query Parameters
vatNumber
string
Example: vatNumber=PL8961583248
companyName
string
Example: companyName=CO3

Responses

Response samples

Content type
application/json
{
  • "companyExists": true,
  • "companyData": {
    }
}

checkVehicleExistence

Check Vehicle's existence in the CO3 platform

Authorizations:
oauth2
path Parameters
licencePlateNumber
required
string
Example: WA12345

License plate number

Responses

Response samples

Content type
application/json
{
  • "vehicleExists": true
}

findVehiclesInRadius

Check Vehicle's presence for the given radius, based on theirs last location received from Telematic Providers. Requires scope vehicles.traces.last.read Important note: if a requester has no consent for tracking vehicles from a Vehicle Owner, the owner's and vehicle's sensitive data will be anonimized.

Authorizations:
oauth2
query Parameters
latitude
required
number
Example: latitude=22.12345

Latitude

longitude
required
number
Example: longitude=22.12345

Longitude

radius
required
number
Example: radius=1000

Radius in meters. Max value 100000

Responses

Response samples

Content type
application/json
{
  • "vehicles": [
    ]
}

Pushing trace positions

Operations for integrating Telematic Data Providers, who prefer to send trace position data for Assets in the Push mode.

pushTracePositions

Enable sending trace position to the CO3 platform for a given device

Authorizations:
basic_for_push
Request Body schema: application/json
required

PushTraceDataRequest

Array of objects (PushTraceDataPosition)

Responses

Request samples

Content type
application/json
{
  • "tracePositions": [
    ]
}

Response samples

Content type
application/json
{
  • "statusCode": 200
}

Identification

Operations used within resolving authorization to resources step

getPersonRelatedCompanies

Returns a list of companies for which a person has a relation and can use companyId as contextCompanyId. Required for Authorization Code flow.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "person": {
    },
  • "relatedCompanies": [
    ]
}

Utilities

Operations not strictly related to any of main processes.

getCarrierOnboardingStages

Enables to get carriers onboarding stage status, invited by the Invitation Link form.

Authorizations:
oauth2
path Parameters
companyId
required
string <uuid>
Example: f70b5598-0b7c-46fe-bb18-b69693d1313f
query Parameters
page
required
integer <int32>
Example: page=0

Page index to be returned. Page Numeration starts from 0.

size
required
integer <int32>
Example: size=25

Number of returned elements per page. Allowed values 1-200

Responses

Response samples

Content type
application/json
{
  • "page": 0,
  • "size": 1,
  • "totalPages": 1,
  • "totalElements": 1,
  • "onboardingStages": [
    ]
}