Helm CONNECT API Documentation
Overview & Policies
Please read all Overview and Policies sections carefully prior to using Helm CONNECT APIs. We reserve the right to revoke access to our APIs if we observe inappropriate behavior.
Notices
Notice: In 1.24 endpoints that return a “Next” link got changed. Please read notice here
API Authorization
All API HTTP requests must have the following headers attached
API-Key: <key>,
Content-Type: application/json
The key comes from the API key management section of the Users App.
User Defined Fields
Purpose
- Allow users to update existing user defined fields to track information.
Data Model
-
A JSON object contains a list of user defined fields. Each user defined field contains a name and value(s).
-
Example Usage:
"UserDefined": { "Height": 123, "Name": "Helm Operation", .... }
User Defined Field Types
-
Text
-
DataType:
<string>
-
Example Usage:
"MMSI": "MIDxxxxxx"
-
-
Number
-
DataType:
<decimal>
-
Example Usage:
"Gross Tonnage": 134
-
-
Bool
-
DataType:
<bool>
-
Example Usage:
"Overdue": true
- Note: If a bool field is defined, but has never had its value set, Helm CONNECT will consider this as
false
.
-
-
Date
-
DataType:
<date>
-
Example Usage:
"HireDate": "2082-01-16T00:00:00-00:00"
- Note: The time does get saved as provided but will be not visible in Helm CONNECT.
-
-
Date and time
-
DataType:
<date>
-
Example Usage:
"ArriveDateTime": "2017-08-18T00:05:00-07:00"
-
-
Select Box
-
DataType:
<GUID>
or<String>
-
Example Usage:
"Direction": "West"
-
-
Multi Selectbox
-
DataType:
<GUID>
or<String>
-
Example Usage:
"OperatingAreas": "4E0D8981-7FA8-6155-54E5-54E5662F795E,4F60597D-68D2-7D66-4F60-62CD62CD624B"
- Note: values are separated by comma(,)
-
Account Type
URI
api/v2/public/accounttypes
Supported Verbs
GET
- Find Account Types.
Data Models
Account Type Model
{
"Id": <GUID>,
"Name": <string>,
"IsCustomer": <boolean>,
"IsAgent": <boolean>,
"IsCompetitor": <boolean>
}
Account Type Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify an account type.
-
-
Name
-
DataType: string [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of an account type.
-
-
IsCustomer
-
DataType: Boolean
-
Required: false
-
Purpose: when true, accounts will be shown in the Customer list on an order.
-
-
IsAgent
-
DataType: Boolean
-
Required: false
-
Purpose: when true, accounts will be shown in the Agent list on an order.
-
-
IsCompetitor
-
DataType: Boolean
-
Required: false
-
Purpose: when true, accounts will be shown in the Awarded To list on an order with the accounts that belong to your own companies.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Account Types
URI
GET api/v2/public/accounttypes
Example Usage
GET api/v2/public/accounttypes
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/accounttypes?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Account Types with Name equal to "Agent" GET api/v2/public/accounttypes?$filter=Name eq 'Agent'
-
Return Value
Action Accepted
Returns an array containing the requested Account Types in the format of the Account Types Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Account Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
Either one of:
- Setup > Jobs > Sales > Read
- Setup > Jobs > Sales > Edit
Activities
Create/Update Activity
URI
api/v1/core/activities/CreateOrUpdateActivity
Supported Verbs
- POST: insert or update an Activity.
Required Parameters
-
Activity Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Activity Model to be created.
-
Data Model
Activity Model
{
"Id": <Guid>,
"VesselId": <GUID>,
"ActivityTypeId": <GUID>,
"FromLocationId": <Guid>,
"ToLocationId": <Guid>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"StartDate": <date>,
"EndDate": <date>,
"RecordedByPersonId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Activity Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: Update the uniquely matching Activity
-
-
VesselId
-
DataType: Guid for the Activity’s vessel.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Activity’s vessel.
-
-
ActivityTypeId
-
DataType: Guid for the Activity type.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Activity type.
-
-
FromLocationId
-
DataType: Guid for the Activity’s Location From.
-
Required: false
-
Purpose: Sets the Activity’s Location From.
-
-
ToLocationId
-
DataType: Guid for the Activity’s Location To.
-
Required: false
-
Purpose: Sets the Activity’s Location To.
-
-
PlannedStartDate
-
DataType: date
-
Required: Either PlannedStartDate or StartDate is required when creating new data
-
Purpose: Sets the Activity’s planned Start Date. Only one of PlannedStartDate and StartDate may be set.
-
-
PlannedEndDate
-
DataType: date
-
Required: Either PlannedEndDate or EndDate is required when creating new data
-
Purpose: Sets the Activity’s planned End Date. Only one of PlannedEndDate and EndDate may be set.
-
-
StartDate
-
DataType: date
-
Required: Either PlannedStartDate or StartDate is required when creating new data
-
Purpose: Sets the Activity’s actual Start Date. Only one of PlannedStartDate and StartDate may be set.
-
-
EndDate
-
DataType: date
-
Required: Either PlannedEndDate or EndDate is required when creating new data
-
Purpose: Sets the Activity’s actual End Date. Only one of PlannedEndDate and EndDate may be set.
-
-
RecordedByPersonId
-
DataType: Guid for the Activity Recorded By Person.
-
Required: false
-
Purpose: Sets who recorded the Activity.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Activity. Will be set to null if not specified.
-
Return Value
Action Accepted
{
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
Id: Guid for the new Activity.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
-
Details Additional information about the error.
Action Rejected
"Data": <Array>
- Data: Error Message
Find Activities
URI
api/v1/core/activities/FindActivities
Supported Verbs
- GET: return a filtered list of Activities. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/core/activities/FindActivities?page=1
-
Optional Parameters
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Activity with the given Id
-
Example Usage:
api/v1/core/activities/FindActivities?page=1&Id=d21d73fb-bb69-11e8-8102-00155d040945
-
-
VesselId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Activities with the given VesselId
-
Example Usage:
api/v1/core/activities/FindActivities?page=1&VesselId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ChangedSince:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return activities that have been modified or created since the datetime.
-
Example Usage
api/v1/core/activities/FindActivities?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
ActivityTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Activities with the given ActivityTypeId
-
Example Usage:
api/v1/core/activities/FindActivities?page=1&ActivityTypeId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
FromDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trips where the EndDate >= FromDate
-
Example Usage
api/v1/core/activities/FindActivities?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trips where the StartDate <= ToDate.
-
Example Usage
api/v1/core/activities/FindActivities?page=1&ToDate=2016-03-10T14:23:00-08:00
-
-
FromLocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Activity with the given FromLocationId
-
Example Usage:
api/v1/core/activities/FindActivities?page=1&FromLocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ToLocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Activity with the given ToLocationId
-
Example Usage:
api/v1/core/activities/FindActivities?page=1&ToLocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
RecordedByPersonId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Activity with the given RecordedByPersonId
-
Example Usage:
api/v1/core/activities/FindActivities?page=1&RecordedByPersonId=d21d73fb-bb69-11e8-8102-00155d040945
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <Guid>,
"VesselId": <GUID>,
"ActivityTypeId": <GUID>,
"FromLocationId": <Guid>,
"ToLocationId": <Guid>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"StartDate": <date>,
"EndDate": <date>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
...
]
}
}
Archive Activity
URI
api/v1/core/activities/ArchiveActivity
Supported Verbs
- POST: Archive an activity.
Required Parameters
-
Archive Activity Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Activity Id to be archived.
-
Data Model
Archive Activity Model
{
"Id": <Guid>
}
Archive Activity Object Fields
-
Id
-
DataType: Guid
-
Required: true
-
Purpose: Archives the uniquely matching Activity
-
Return Value
Action Accepted
{
"ActionType": "Archive",
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>
"Message": <string>
},
...
]
}
-
ActionType: Will always be ‘Archive’.
-
Id: Guid for the Activity.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Create/Update Job Activity
URI
api/v1/jobs/activities/CreateOrUpdateJobActivity
Supported Verbs
- POST: insert or update a job activity.
Required Parameters
-
Job Activity Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Job Activity Model to be created.
-
Data Model
Job Activity Model
{
"Id": <Guid>,
"JobId": <GUID>,
"ActivityTypeId": <GUID>,
"FromLocationId": <Guid>,
"ToLocationId": <Guid>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"StartDate": <date>,
"EndDate": <date>,
"IsStartDateAutomatic": <boolean>,
"IsEndDateAutomatic": <boolean>,
"RecordedByPersonId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Job Activity Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: Update the uniquely matching Job Activity
-
-
JobId
-
DataType: Guid for the Activity’s job.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Activity’s job.
-
-
ActivityTypeId
-
DataType: Guid for the Activity type.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Activity type.
-
-
FromLocationId
-
DataType: Guid for the Activity’s Location From.
-
Required: false
-
Purpose: Sets the Activity’s Location From. If there are pre-existing job activities, the From Location must match the To Location of the last pre-existing activity. You can only change the From Location of the first job activity.
-
-
ToLocationId
-
DataType: Guid for the Activity’s Location To.
-
Required: false
-
Purpose: Sets the Activity’s Location To. You can only change the To Location of the last job activity.
-
-
PlannedStartDate
-
DataType: date
-
Required: Either PlannedStartDate or StartDate is required when creating new data; false when updating existing data
-
Purpose: Sets the Activity’s planned Start Date. Only one of PlannedStartDate and StartDate may be set. If there are pre-existing job activities, the Start Date must match the End Date of the last pre-existing job activity.
-
-
PlannedEndDate
-
DataType: date
-
Required: Either PlannedEndDate or EndDate is required when creating new data; false when updating existing data
-
Purpose: Sets the Activity’s planned End Date. Only one of PlannedEndDate and EndDate may be set.
-
-
StartDate
-
DataType: date
-
Required: Either PlannedStartDate or StartDate is required when creating new data; false when updating existing data
-
Purpose: Sets the Activity’s actual Start Date. Only one of PlannedStartDate and StartDate may be set. If there are pre-existing job activities, the Start Date must match the End Date of the last pre-existing job activity. You can only change the Start Date of the first job activity.
-
-
EndDate
-
DataType: date
-
Required: Either PlannedEndDate or EndDate is required when creating new data; false when updating existing data
-
Purpose: Sets the Activity’s actual End Date. Only of one PlannedEndDate and EndDate may be set. You can only change the End Date of the last job activity.
-
-
IsStartDateAutomatic
-
DataType: boolean
-
Required: false
-
Purpose: Sets the Activity’s IsEndDateAutomatic
-
-
IsEndDateAutomatic
-
DataType: boolean
-
Required: false
-
Purpose: Sets the Activity’s IsEndDateAutomatic
-
-
RecordedByPersonId
-
DataType: Guid for the Recorded By Person
-
Required: false
-
Purpose: Sets the Activity’s RecordedByPerson.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Activity. Will be set to null if not specified.
-
Return Value
Action Accepted
{
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
Id: Guid for the new Job Activity.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
-
Details: Additional information about the error.
Action Rejected
"Data": <Array>
- Data: Error Message
Find Job Activities
URI
api/v1/jobs/activities/FindJobActivities
Supported Verbs
- GET: return a filtered list of job activities. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1
-
Optional Parameters
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Job Activity with the given Id
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&Id=d21d73fb-bb69-11e8-8102-00155d040945
-
-
JobId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Activities with the given JobId
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&JobId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ResourceId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Activities with the given ResourceId
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&ResourceId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ChangedSince:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return job activities that have been modified or created since the datetime.
-
Example Usage
api/v1/jobs/activities/FindJobActivities?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
ActivityTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Activities with the given ActivityTypeId
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&ActivityTypeId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
FromDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Activities where the EndDate (or PlannedEndDate if EndDate is blank) is >= FromDate
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Activities where the StartDate (or PlannedStartDate if StartDate is blank) is <= ToDate
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&ToDate=2016-03-10T14:23:00-08:00
-
-
FromLocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Activities with the given FromLocationId
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&FromLocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ToLocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Activities with the given ToLocationId
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&ToLocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
RecordedByPersonId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Activities with the given RecordedByPersonId
-
Example Usage:
api/v1/jobs/activities/FindJobActivities?page=1&RecordedByPersonId=d21d73fb-bb69-11e8-8102-00155d040945
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"JobId": <GUID>,
"ResourceId": <GUID>,
"ActivityTypeId": <GUID>,
"FromLocationId": <GUID>,
"ToLocationId": <GUID>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"StartDate": <date>,
"EndDate": <date>,
"IsStartDateAutomatic": <boolean>,
"IsEndDateAutomatic": <boolean>,
"RecordedByPersonId": <GUID>,
"UserDefined": UserDefinedDataModel (see User Defined Fields section for more details)
},
...
]
}
}
Activity Type
URI
api/v2/public/activitytypes
Supported Verbs
GET
- Find Activity Types.
Data Models
Activity Type Model
{
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>,
"Type": <string>,
"Tags": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
},
...
]
}
Activity Type Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify an activity type.
-
-
Name
-
DataType: string [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of an activity type.
-
-
AccountingCode
-
DataType: string [max. 50 char]
-
Filterable: true
-
Purpose: Specifies the name of an activity type.
-
-
Type
-
DataType: string
-
Filterable: true
-
Purpose: Indicates the type of the activity type; for example, “Primary”, “RunningFrom”, “RunningTo”, or “Downtime”.
-
-
Tags
-
DataType: Array
-
Purpose: Defines the tags this activity type has.
-
Fields:
- Id
<GUID>
- Name
<string>
- Id
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Activity Types
URI
GET api/v2/public/activitytypes
or
GET api/v2/public/activitytypes/{Id}
Example Usage
// Get a paginated response of all activity types
GET api/v2/public/activitytypes
// Get a specific activity type by Id
GET api/v2/public/activitytypes/d21d73fb-bb69-11e8-8102-00155d040945
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/activitytypes?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Activity Types with Name equal to "Sailing" GET api/v2/public/activitytypes?$filter=Name eq 'Sailing'
-
Return Value
Action Accepted
Returns an array containing the requested Activity Types in the format of the Activity Types Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Activity Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Setup > Events > Activity Types
Assets
Update Asset
URI
api/v1/core/assets/CreateOrUpdateAsset
Supported Verbs
- POST: update an asset
Required Parameters
-
Asset Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Asset Model to be updated.
-
Data Model
Asset Model
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"AccountingCode": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Asset Object Fields
-
Id
-
DataType: GUID
-
Required: true
-
Purpose: Identify the asset to update
-
-
Name
-
DataType: string [max. 400 char]
-
Required: false
-
Purpose: Sets the Name for the Asset.
-
-
ShortName
-
DataType: string [max. 100 char]
-
Required: false
-
Purpose: Sets the ShortName for the Asset.
-
-
AccountingCode
-
DataType: string [max. 50 char]
-
Required: false
-
Purpose: Sets the AccountingCode for the Asset.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined fields for the Asset.
-
Return Value
Action Accepted
{
"Data":
{
"ActionType": <string>,
"Id": <GUID>
}
}
-
ActionType: Insert (Not implemented) or Update
-
Id: Guid of the updated Asset
Find Assets
URI
api/v1/core/assets/FindAssets
Supported Verbs
- GET: return a filtered list of Assets. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/core/assets/FindAssets?page=1
-
Optional Parameters
-
Name:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the assets with a Name that contains the given string.
-
Example Usage:
api/v1/core/assets/FindAssets?page=1&Name=Frigate
-
-
ShortName:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the assets with a ShortName that contains the given string.
-
Example Usage:
api/v1/core/assets/FindAssets?page=1&ShortName=HM
-
-
AccountingCode:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the assets with AccountingCode that contains the given string.
-
Example Usage:
api/v1/core/assets/FindAssets?page=1&AccountingCode=142
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"AccountingCode": <string>,
"VesselTypeNames": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
}
...
]
}
}
Barging
Barges
URI
api/v2/public/bargingbarges
Supported Verbs
GET
- Find Barges.
Data Models
Barge Model
{
"Id": <GUID>,
"Name": <string>
}
Barge Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barge.
-
-
Name
-
DataType: string [max. 100 char]
-
Filterable: false
-
Purpose: Specifies the name of a barge.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barges
URI
GET api/v2/public/bargingbarges
Example Usage
GET api/v2/public/bargingbarges
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingbarges?page=2
-
Return Value
Action Accepted
Returns an array containing the requested Barges in the format of the Barges Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barge Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Barging Commodities
URI
api/v2/public/bargingcommodities
Supported Verbs
GET
- Find Barging Commodities.
Data Models
Barging Commodity Model
{
"Id": <GUID>,
"Name": <string>,
"CommodityTypeId": <GUID>
}
Barging Commodity Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barging commodity.
-
-
Name
-
DataType: string [max. 100 char]
-
Filterable: false
-
Purpose: Specifies the name of a barging commodity.
-
-
CommodityTypeId
-
DataType: Guid
-
Purpose: To identify the commodity’s type from Barging Commodity Types.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barging Commodities
URI
GET api/v2/public/bargingcommodities
Example Usage
GET api/v2/public/bargingcommodities
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingcommodities?page=2
-
Return Value
Action Accepted
Returns an array containing the requested Bargig Commodities in the format of the Barging Commodity Type Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barging Commodity Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Barging Commodity Types
URI
api/v2/public/bargingcommoditytypes
Supported Verbs
GET
- Find Barging Commodity Types.
Data Models
Barging Commodity Type Model
{
"Id": <GUID>,
"Name": <string>
}
Barging Commodity Type Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barging commodity type.
-
-
Name
-
DataType: string [max. 100 char]
-
Filterable: false
-
Purpose: Specifies the name of a barging commodity type.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barging Commodity Types
URI
GET api/v2/public/bargingcommoditytypes
Example Usage
GET api/v2/public/bargingcommoditytypes
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingcommoditytypes?page=2
-
Return Value
Action Accepted
Returns an array containing the requested Bargig Commodity Types in the format of the Barging Commodity Types Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barging Commodity Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Barging Orders
URI
api/v2/public/bargingorders
Supported Verbs
GET
- Find Barging Orders.
Data Models
Barging Order Model
{
"Id": <GUID>,
"OrderNumber": <string>,
"ShipperId": <GUID>,
"OriginatorId": <GUID>,
"CustomerId": <GUID>,
"ConsigneeId": <GUID>,
"CommodityId": <GUID>,
"Quantity": <decimal>,
"QuanityUnitId": <GUID>,
"LoadLocationId": <GUID>,
"UnloadLocationId": <GUID>,
"LoadStartDate": <datetime>,
"LoadEndDate": <datetime>,
"RequestedStartDate": <datetime>,
"UnloadStartDate": <datetime>,
"UnloadEndDate": <datetime>,
"BargeId": <GUID>,
"BargeSizeNeeded": <integer>,
"BillingComments": <string>,
"OnHold": <boolean>,
"PartialBarge": <boolean>,
"ParentOrderId": <GUID>,
"Billable": <boolean>,
"OfficialQuantity": <decimal>,
"OfficialQuantityUnitId": <GUID>,
"OnTime": <datetime>,
"OnTimeAdjusted": <datetime>,
"SplitShipment": <boolean>,
"UnloadingComments": <string>,
"LoadingComments": <string>,
"ArrivalDate": <datetime>,
"ShoreNet": <decimal>,
"ShoreGross": <decimal>,
"BargeNet": <decimal>,
"Created": <datetime>,
"Tugs": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"Spotting": <boolean>,
"PickUp": <boolean>
},
...
],
"Trip": <Object> {
"Id": <GUID>,
"BeginDate": <datetime>,
"EndDate": <datetime>,
"Comments": <string>,
"TripNumber": <string>,
"BeginLocationId": <GUID>,
"EndLocationId": <GUID>,
"TripTypeId": <GUID>,
"Tugs": <Array of GUID>,
"Created": <datetime>,
}
}
Barging Order Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barging order.
-
-
OrderNumber
-
DataType: string
-
Filterable: true
-
Required: false
-
Purpose: Specifies the unique, iterative number assigned to the barging order.
-
-
ShipperId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s shipper company.
-
-
OriginatorId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s originator company.
-
-
CustomerId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s customer company.
-
-
ConsigneeId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s consignee company.
-
-
CommodityId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s commodity.
-
-
CommodityTypeId
-
DataType: Guid
-
Filterable: true
-
Required: false
-
Purpose: The order’s commodity type derived from the commodity.
-
-
Quantity
-
DataType: decimal
-
Required: false
-
Purpose: The order’s quantity using the units specified in QuantityUnitId.
-
-
QuantityUnitId
-
DataType: Guid
-
Required: false
-
Purpose: The type of units used in the Quantity field. References Barging Units.
-
-
LoadLocationId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s load location.
-
-
UnloadLocationId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s unload location.
-
-
LoadStartDate
-
DataType: datetime
-
Filterable: true
-
Required: false
-
Purpose: The order’s load start date.
-
-
LoadEndDate
-
DataType: datetime
-
Filterable: true
-
Required: false
-
Purpose: The order’s load end date.
-
-
RequestedStartDate
-
DataType: datetime
-
Required: false
-
Purpose: The order’s requested start date.
-
-
UnloadStartDate
-
DataType: datetime
-
Required: false
-
Purpose: The order’s unload start date.
-
-
UnloadEndDate
-
DataType: datetime
-
Required: false
-
Purpose: The order’s unload end date.
-
-
BargeId
-
DataType: Guid
-
Required: false
-
Purpose: The order’s barge.
-
-
BargeSizeNeeded
-
DataType: integer
-
Required: false
-
Purpose: The size of barge required for the order.
-
-
BillingComments
-
DataType: string
-
Required: false
-
Purpose: Comments relevant to billing.
-
-
OnHold
-
DataType: boolean
-
Required: false
-
Purpose: Barging orders that are on hold are not ready to be assigned to a trip yet.
-
-
PartialBarge
-
DataType: boolean
-
Required: false
-
Purpose: Indicates that the order is not enough to fill a whole barge.
-
-
ParentOrderId
-
DataType: GUID
-
Required: false
-
Purpose: References the order that encompasses the whole barge.
-
-
Billable
-
DataType: boolean
-
Filterable: true
-
Required: false
-
Purpose: Indicates whether the order should be available for billing.
-
-
OfficialQuantity
-
DataType: decimal
-
Required: false
-
Purpose: The order’s actual quantity using the units specified in OfficalQuantityUnitId.
-
-
OfficialQuantityUnitId
-
DataType: GUID
-
Required: false
-
Purpose: The type of units used in the OfficialQuantity field. References Barging Units.
-
-
OnTime
-
DataType: datetime
-
Required: false
-
Purpose: The order’s on time.
-
-
OnTimeAdjusted
-
DataType: datetime
-
Required: false
-
Purpose: The order’s adjusted on time.
-
-
SplitShipment
-
DataType: boolean
-
Required: false
-
Purpose: Indicates whether this order is a split shipment.
-
-
UnloadingComments
-
DataType: string
-
Required: false
-
Purpose: Comments relevant to unloading.
-
-
LoadingComments
-
DataType: string
-
Required: false
-
Purpose: Comments relevant to loading.
-
-
ArrivalDate
-
DataType: datetime
-
Required: false
-
Purpose: The order’s arrival date.
-
-
ShoreNet
-
DataType: decimal
-
Required: false
-
Purpose: The order’s shore net amount.
-
-
ShoreGross
-
DataType: decimal
-
Required: false
-
Purpose: The order’s shore gross amount.
-
-
BargeNet
-
DataType: decimal
-
Required: false
-
Purpose: The order’s barge net amount.
-
-
Created
-
DataType: datetime
-
Filterable: true
-
Required: false
-
Purpose: The date the order was originally created.
-
-
Tugs
-
DataType: Array of JSON Objects
-
Required: true
-
Purpose: The spotting and pick up tugs for this order.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
Spotting
<boolean>
-
PickUp
<boolean>
-
-
-
Trip
-
DataType: JSON Object
-
Required: false
-
Purpose: The trip this order is assigned to.
-
Fields:
-
Id
<GUID>
-
Status
<string>
-
BeginDate
<datetime>
-
EndDate
<datetime>
-
Comments
<string>
-
TripNumber
<string>
-
BeginLocationId
<GUID>
-
EndLocationId
<GUID>
-
TripTypeId
<GUID>
-
Tugs
<Array of GUID>
-
Created
<datetime>
-
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barging Orders
URI
GET api/v2/public/bargingorders
Example Usage
GET api/v2/public/bargingorders
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingorders?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get a specific Barging Order with OrderNumber equal to "1234" GET api/v2/public/bargingorders?$filter=OrderNumber eq '1234' // Get Barging Orders with LoadStartDate greater than "2022-09-01" GET api/v2/public/bargingorders?$filter=LoadStartDate gt datetime'2022-09-01' // Get Barging Orders with CommodityTypeId Id equal to "c26ede07-67f8-11ec-b9aa-144f8a6a31b3" GET api/v2/public/bargingorders?$filter=CommodityTypeId eq guid'c26ede07-67f8-11ec-b9aa-144f8a6a31b3'
-
Return Value
Action Accepted
Returns an array containing the requested Bargig Orders in the format of the Barging Order Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barging Order Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Barging Trips
URI
api/v2/public/bargingtrips
Supported Verbs
GET
- Find Barging Trips.
Data Models
Barging Trip Model
{
"Id": <GUID>,
"BeginDate": <datetime>,
"EndDate": <datetime>,
"Comments": <string>,
"TripNumber": <string>,
"BeginLocationId": <GUID>,
"EndLocationId": <GUID>,
"TripTypeId": <GUID>,
"Tugs": <Array of GUID>,
"Created": <datetime>,
"Orders": <Array>
[
{
"Id": <GUID>,
"OrderNumber": <string>,
"ShipperId": <GUID>,
"OriginatorId": <GUID>,
"CustomerId": <GUID>,
"ConsigneeId": <GUID>,
"CommodityId": <GUID>,
"Quantity": <decimal>,
"QuanityUnitId": <GUID>,
"LoadLocationId": <GUID>,
"UnloadLocationId": <GUID>,
"LoadStartDate": <datetime>,
"LoadEndDate": <datetime>,
"RequestedStartDate": <datetime>,
"UnloadStartDate": <datetime>,
"UnloadEndDate": <datetime>,
"BargeId": <GUID>,
"BargeSizeNeeded": <integer>,
"BillingComments": <string>,
"OnHold": <boolean>,
"PartialBarge": <boolean>,
"ParentOrderId": <GUID>,
"Billable": <boolean>,
"OfficialQuantity": <decimal>,
"OfficialQuantityUnitId": <GUID>,
"OnTime": <datetime>,
"OnTimeAdjusted": <datetime>,
"SplitShipment": <boolean>,
"UnloadingComments": <string>,
"LoadingComments": <string>,
"ArrivalDate": <datetime>,
"ShoreNet": <decimal>,
"ShoreGross": <decimal>,
"BargeNet": <decimal>,
"Created": <datetime>,
"Tugs": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"Spotting": <boolean>,
"PickUp": <boolean>
},
...
]
},
...
]
}
Barging Trip Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barging trip.
-
-
Status
-
DataType: string
-
Required: false
-
Purpose: Sets the Status of the Trip.
-
Note: Status can be one of the following values and is case sensitive:
- “Open”: will mark this Trip as open/non-complete
- “Complete”: will mark this Trip as complete
-
-
BeginDate
-
DataType: datetime
-
Filterable: true
-
Required: false
-
Purpose: The begin date of the trip.
-
-
EndDate
-
DataType: Guid
-
Filterable: true
-
Required: false
-
Purpose: The end date of the trip.
-
-
TripNumber
-
DataType: Guid
-
Filterable: true
-
Required: true
-
Purpose: The trip’s unique, incremental identifier.
-
-
BeginLocationId
-
DataType: Guid
-
Required: false
-
Purpose: The trip’s begin location.
-
-
EndLocationId
-
DataType: Guid
-
Required: false
-
Purpose: The trip’s end location.
-
-
TripTypeId
-
DataType: Guid
-
Filterable: true
-
Required: false
-
Purpose: The trip’s type.
-
-
Tugs
-
DataType: Array of GUID
-
Required: false
-
Purpose: The tugs that will be utilized on this trip.
-
-
Created
-
DataType: datetime
-
Filterable: true
-
Required: false
-
Purpose: The order’s commodity type derived from the commodity.
-
-
Orders
-
DataType: Array of JSON Objects
-
Required: false
-
Purpose: The orders assigned to this trip.
-
Fields:
-
Id
<GUID>
: required -
OrderNumber
<string>
: required -
Quantity
<decimal>
: optional -
LoadStartDate
<datetime>
: optional -
LoadEndDate
<datetime>
: optional -
RequestedStartDate
<datetime>
: optional -
UnloadStartDate
<datetime>
: optional -
UnloadEndDate
<datetime>
: optional -
BargeSizeNeeded
<integer>
: optional -
BillingComments
<string>
: optional -
OnHold
<boolean>
: required -
PartialBarge
<boolean>
: required -
Billable
<boolean>
: required -
OfficialQuantity
<decimal>
: optional -
OnTime
<datetime>
: optional -
OnTimeAdjusted
<datetime>
: optional -
SplitShipment
<boolean>
: required -
UnloadingComments
<string>
: optional -
LoadingComments
<string>
: optional -
ArrivalDate
<datetime>
: optional -
ShipperId
<GUID>
: optional -
OriginatorId
<GUID>
: optional -
CustomerId
<GUID>
: optional -
ConsigneeId
<GUID>
: optional -
QuantityUnitId
<GUID>
: optional -
LoadLocationId
<GUID>
: optional -
UnloadLocationId
<GUID>
: optional -
CommodityId
<GUID>
: optional -
CommodityTypeId
<GUID>
: optional -
BargeId
<GUID>
: optional -
ParentOrderId
<GUID>
: optional -
OfficialQuantityUnitId
<GUID>
: optional -
Tugs
<Array of GUID>
: optional -
ShoreNet
<decimal>
: optional -
ShoreGross
<decimal>
: optional -
BargeNet
<decimal>
: optional
-
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barging Trips
URI
GET api/v2/public/bargingtrips
Example Usage
GET api/v2/public/bargingtrips
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingtrips?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get a specific Barging Trip with TripNumber equal to "1234" GET api/v2/public/bargingtrips?$filter=TripNumber eq '1234' // Get Barging Trips with BeginDate greater than "2022-09-01" GET api/v2/public/bargingtrips?$filter=BeginDate gt datetime'2022-09-01' // Get Barging Trips with TripTypeId Id equal to "c26ede07-67f8-11ec-b9aa-144f8a6a31b3" GET api/v2/public/bargingtrips?$filter=TripTypeId eq guid'c26ede07-67f8-11ec-b9aa-144f8a6a31b3'
-
Return Value
Action Accepted
Returns an array containing the requested Bargig Trips in the format of the Barging Trip Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barging Trip Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Barging Trip Types
URI
api/v2/public/bargingtriptypes
Supported Verbs
GET
- Find Barging Trip Types.
Data Models
Barging Trip Type Model
{
"Id": <GUID>,
"Name": <string>,
"DefaultDurationHours": <decimal>,
"DefaultStartLocationId": <GUID>,
"DefaultEndLocationId": <GUID>
}
Barging Trip Type Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barging trip type.
-
-
Name
-
DataType: string [max. 100 char]
-
Filterable: false
-
Purpose: Specifies the name of a barging trip type.
-
-
DefaultDurationHours
-
DataType: decimal
-
Purpose: Used to automatically populate the End Date of a trip using this trip type based on the trip’s Begin Date.
-
-
DefaultBeginLocationId
-
DataType: Guid
-
Purpose: Indicates the location that will be automatically assigned to a trip’s Begin Location field when this trip type is selected.
-
-
DefaultEndLocationId
-
DataType: Guid
-
Purpose: Indicates the location that will be automatically assigned to a trip’s End Location field when this trip type is selected.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barging Trip Types
URI
GET api/v2/public/bargingtriptypes
Example Usage
GET api/v2/public/bargingtriptypes
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingtriptypes?page=2
-
Return Value
Action Accepted
Returns an array containing the requested Bargig Trip Types in the format of the Barging Trip Type Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barging Trip Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Barging Units
URI
api/v2/public/bargingunits
Supported Verbs
GET
- Find Barging Units.
Data Models
Barging Unit Model
{
"Id": <GUID>,
"Name": <string>
}
Barging Unit Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a barging unit.
-
-
Name
-
DataType: string [max. 100 char]
-
Filterable: false
-
Purpose: Specifies the name of a barging unit.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Barging Units
URI
GET api/v2/public/bargingunits
Example Usage
GET api/v2/public/bargingunits
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/bargingunits?page=2
-
Return Value
Action Accepted
Returns an array containing the requested Barging Units in the format of the Barging Unit Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Barge Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Barging
Company
Create/Update Company
URI
api/v1/jobs/companies/CreateOrUpdateCompany
Supported Verbs
- POST: insert and update one or more companies.
Required Parameters
-
Company Model
-
Data Type: Array of JSON Objects (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one or more Company Model to be created or updated.
-
Data Model
Company Model
[
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"ExternalSystemCode": <string>,
"IsMyCompany": <boolean>,
"IsActive": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"AccountingTerm":
{
"Name": <string>,
"ExternalSystemCode": <string>
}
},
....
]
Company Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: update the uniquely matching Company. The Company must be active.
-
-
Name
-
DataType: string
-
Required: true
-
Purpose: Sets the Name for the Company.
-
-
ShortName
-
DataType: string
-
Required: false
-
Purpose: Sets the ShortName for the Company. Will be set to null if not specified.
-
-
ExternalSystemCode
-
DataType: string
-
Required: false
-
Purpose: Sets the ExternalSystemCode for the Company. Will be set to null if not specified.
-
-
IsMyCompany
-
DataType: boolean
-
Required: false
-
Default value: false
-
Purpose: Sets the IsMyCompany for the Company. Will be set to false if not specified.
-
-
IsActive
-
DataType: boolean
-
Required: false
-
Default value: true
-
Purpose: Sets whether the Company is Archived. Will be set to false if not specified.
-
-
UserDefined
-
DataType: User Defined Data Model (see User User Defined Fields for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Company. Will be set to null if not specified.
-
-
AccountingTerm
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the AccountingTermId of the Company.
-
Function: Selects the AccountingTerm that uniquely matches the given fields.
-
Fields:
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
Return Value
With errors
{
"Data":
[
{
"Name": <string>,
"Errors":
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
]
}
Without errors
{
"Data":
{
"Created": <Integer>,
"Updated": <Integer>
}
}
-
Created: The number of Companies created.
-
Updated: The number of Companies updated.
Create/Update Account
URI
api/v1/jobs/companies/CreateOrUpdateCompanyAccount
Supported Verbs
- POST: insert and update one or more Company accounts.
Required Parameters
-
Account Model
-
Data Type: Array of JSON Objects (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one or more Account Model to be created or update.
-
Optional Parameters
-
addNewCompany
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true and company can’t be found, it will create new company based on the information provided.
-
Note: Company’s Name is required when creating New Company
-
Example Usage:
api/v1/jobs/companies/CreateOrUpdateCompanyAccount?addNewCompany=true
-
-
asRequest
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of creating or updating an Account directly, a Request for those changes will be created. This creates new request Accounts which are referenced by the Requests that were created. Requested accounts will have the RequestedOn field set to the current datetime.
-
Example Usage:
api/v1/jobs/companies/CreateOrUpdateCompanyAccount?asRequest=true
-
Data Model
Account Model
[
{
"Id": <GUID>,
"Name": <string>,
"Company":
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"ExternalSystemCode": <string>,
"IsMyCompany": <boolean>,
"IsActive": <boolean>,
"UserDefined":User Defined Data Model (see User Defined Fields section for more details),
"AccountingTerm":
{
"Name": <string>,
"ExternalSystemCode": <string>
}
},
"Division":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"AccountNumber": <string>,
"AccountType": <string>,
"AccountTypeId": <GUID>,
"IsAR": <boolean>,
"IsAP": <boolean>,
"IsBlocked": <boolean>,
"IsActive": <boolean>,
"AccountingTerm":
{
"Name": <string>,
"ExternalSystemCode": <string>
}
},
....
]
Account Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: update the uniquely matching Account.
-
-
Name
-
DataType: string
-
Required: true
-
Purpose: Sets the Name for the Account.
-
-
Company
-
DataType: JSON Object
-
Required: true
-
Purpose: Sets the Company of the Account.
-
Function: Selects the Company that uniquely matches the given Id, Name, Shortname and ExternalSystemCode
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ShortName
<string>
-
ExternalSystemCode
<string>
-
IsMyCompany
<bool>
-
IsActive
<bool>
-
UserDefined
<string>
-
AccountingTerm
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
-
Division
-
DataType: JSON Object
-
Required: true
-
Purpose: Sets the DivisionId of the Account.
-
Function: Selects the Division that uniquely matches the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
AccountNumber
-
DataType: string
-
Required: true
-
Purpose: Sets the AccountName for the Account.
-
-
AccountType
-
DataType: string
-
Required: true
-
Purpose: Sets the AccountType for the Account.
-
-
AccountTypeId
-
DataType: Guid
-
Required: true when AccountType is not set
-
Purpose: Sets the AccountTypeId for the Account.
-
-
IsAR
-
DataType: boolean
-
Required: false
-
Default value: true
-
Purpose: Sets the IsAR for the Account.
-
-
IsAP
-
DataType: boolean
-
Required: false
-
Default value: false
-
Purpose: Sets the IsAP for the Account.
-
-
IsBlocked
-
DataType: boolean
-
Required: false
-
Default value: false
-
Purpose: Sets the IsBlocked for the Account.
-
-
IsActive
-
DataType: boolean
-
Required: false
-
Default value: true
-
Purpose: Sets the IsActive for the Account.
-
-
AccountingTerm
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the AccountingTermId of the Account.
-
Function: Selects the AccountingTerm that uniquely matches the given fields.
-
Fields:
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
Return Value
With errors
{
"Data":
[
{
"Name": <Array>,
"Errors":
[
{
"Entity": <string>
},
....
]
}
]
}
Without errors
{
"Data":
{
"Created": <Integer>,
"Updated": <Integer>,
"CompanyCreated": <Integer>
}
}
-
Created: The number of Company Accounts created.
-
Updated: The number of Company Accounts updated.
-
CompanyCreated: The number of Companies created.
Create/Update Account Address
URI
api/v1/jobs/companies/CreateOrUpdateAccountAddress
Supported Verbs
- POST: insert and update one or more Account Addresses.
Required Parameters
-
Account Address Model
-
Data Type: Array of JSON Objects (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one or more Account Address Model to be created or updated.
-
Data Model
Account Address Model
[
{
"Id": <GUID>,
"Account":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"Name": <string>,
"Address": <string>,
"City": <string>,
"Zipcode": <string>,
"State": <string>,
"Country": <string>,
"Email": <string>,
"ExternalSystemCode": <string>,
"Areas":
[
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
....
]
},
....
]
Account Address Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: update the uniquely matching Account Address.
-
-
Account
-
DataType: JSON Object
-
Required: true
-
Purpose: Sets the Account of the Account Address.
-
Function: Selects the Account that uniquely matches the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
AccountNumber
<string>
-
-
-
Name
-
DataType: string
-
Required: false
-
Purpose: Sets the Name for the Account Address. Will be set to null if not specified.
-
-
Address
-
DataType: string
-
Required: true
-
Purpose: Sets the Address for the Account Address.
-
-
City
-
DataType: string
-
Required: true
-
Purpose: Sets the City for the Account Address.
-
-
Zipcode
-
DataType: string
-
Required: false
-
Purpose: Sets the Zipcode for the Account Address. Will be set to null if not specified.
-
-
State
-
DataType: string
-
Required: false
-
Purpose: Sets the State for the Account Address. Will be set to null if not specified.
-
-
Country
-
DataType: string
-
Required: true
-
Purpose: Sets the Country for the Account Address.
-
-
Email
-
DataType: string
-
Required: false
-
Purpose: Sets the Email for the Account Address. Will be set to null if not specified.
-
-
ExternalSystemCode
-
DataType: string
-
Required: false
-
Purpose: Sets the ExternalSystemCode for the Account Address. Will be set to null if not specified.
-
-
Areas
-
DataType: Array of JSON Objects
-
Required: false
-
Purpose: Sets the Areas for the Account Address. Will be set to null if not specified.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
AccountNumber
<string>
-
-
Return Value
With errors
{
"Data":
[
{
"Name": <Array>,
"Errors":
[
{
"Entity": <string>
},
....
]
}
]
}
Without errors
{
"Data":
{
"Created": <Integer>,
"Updated": <Integer>
}
}
-
Created: The number of Company Accounts created.
-
Updated: The number of Company Accounts updated.
Find Companies
URI
api/v1/jobs/companies/FindCompanies
Supported Verbs
- GET: return a filtered list of Companies, Account, and Account Address. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/companies/FindCompanies?page=2
-
Optional Parameters
-
SearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies with Name or ShortName that contains the given string.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&SearchString=partOfTheName
-
-
ChangedSince:
- **Data Type**: datetime - **Parameter Type**: query string - **Default Value**: null - **Purpose**: When not null, will return companies that have been modified or created since the datetime. - **Example Usage** ``` api/v1/jobs/companies/FindCompanies?page=1&ChangedSince=2016-03-10T14:23:00-08:00 ```
-
CompanyId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Company with the specified ID.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&CompanyId=bb04a615-141a-4068-8db9-7972e4495775
-
-
AccountId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Company that contains the account with the specified account ID. The company’s other accounts, if any, will be omitted.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&AccountId=9160961a-90a7-4b3c-9e7b-539cbb487714
-
-
CompanyExternalSystemCode:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies with the specified external system code.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&CompanyExternalSystemCode=CustomerXYZ
-
-
AccountNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies that contain accounts with the specified account number. Any accounts that do not have the specified account number will be omitted.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&AccountNumber=Account12345
-
-
AccountDivisionId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies that contain accounts associated with the specified division, or with divisions under the specified division. Any accounts not associated with the division in the aforementioned manner will be omitted.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&AccountDivisionId=74dc9c35-cf60-11e9-ac82-d4bed95b193d
-
-
AccountType:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies that contain accounts with the specified type. Any accounts that do not have the specified type will be omitted.
-
Example Usage:
// Search for Customer/Agent accounts: api/v1/jobs/companies/FindCompanies?page=1&AccountType=Customer%2FAgent
-
-
IsAR:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies that contain accounts marked as “Accounts Receivable”. Any accounts that are not marked as “Accounts Receivable” will be omitted.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&IsAR=true
-
-
IsAP:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Companies that contain accounts marked as “Accounts Payable”. Any accounts that are not marked as “Accounts Payable” will be omitted.
-
Example Usage:
api/v1/jobs/companies/FindCompanies?page=1&IsAP=true
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"ExternalSystemCode": <string>,
"IsMyCompany": <boolean>,
"IsActive": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"AccountingTerm":
{
"Name": <string>,
"NumberOfDays": <integer>,
"ExternalSystemCode": <string>
},
"Accounts": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"Division":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"AccountNumber": <string>,
"AccountType": <string>,
"AccountTypeId": <GUID>,
"IsAR": <boolean>,
"IsAP": <boolean>,
"IsBlocked": <boolean>,
"IsActive": <boolean>,
"IsRequested": <boolean>,
"AccountingTerm":
{
"Name": <string>,
"NumberOfDays": <integer>,
"ExternalSystemCode": <string>
},
"Addresses": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"Address": <string>,
"City": <string>,
"Zipcode": <string>,
"State": <string>,
"Country": <string>,
"Email": <string>,
"Areas":
[
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
....
]
},
....
]
},
....
]
},
....
]
}
}
Contract
URI
api/v2/public/contracts
Supported Verbs
GET
- Find Contracts.
Data Models
Contract Model
{
"Id": <GUID>,
"Name": <string>,
"AccountId": <GUID>,
"Account":
{
"Id": <GUID>,
"AccountNumber": <string>,
"Name": <string>
}
"EffectiveDate": <string>,
"ExpiryDate": <string>
}
Contract Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify a contract.
-
-
Name
-
DataType: string [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of a contract.
-
-
AccountId
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify an account.
-
-
Account
-
DataType: JSON Object (See Data Model for details)
-
Purpose: Defines the account.
-
Fields:
- Id
<GUID>
- AccountNumber
<string>
- Name
<string>
- Id
-
-
EffectiveDate
-
DataType:
<date>
-
Filterable: true
-
Purpose: Sets the EffectiveDate for the contract.
-
-
ExpiryDate
-
DataType:
<date>
-
Filterable: true
-
Purpose: Sets the ExpiryDate for the contract.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Required Permissions
- Jobs > Contracts > Read
Components
URI
api/v2/public/components
Supported Verbs
GET
- find components.
Data Models
Component Model
[
{
"Id": <GUID>,
"Name": <string>,
"SnippetTag": <string>,
"VesselComponentId": <GUID>,
"ParentComponentId": <GUID>,
"AssetId": <GUID>,
"Active": <boolean>,
"Deactivated": <date>,
"ComponentTypeId": <GUID>,
"ComponentTypeName": <string>,
"EssentialSystem": <boolean>,
"MakeId": <GUID>,
"MakeName": <string>,
"ModelId": <GUID>,
"ModelName": <string>,
"Modified": <date>,
"SerialNumber": <string>,
"PartNumber": <string>,
"ReceivePropagatedReadings": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
....
]
Component Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify a (physical) component and to specify which component to apply an operation to.
-
-
Name
-
DataType: string
-
Filterable: true
-
Purpose: Specifies the description of a component.
-
-
SnippetTag
-
DataType: string
-
Filterable: true
-
Purpose: The current associated snippet tag of this component.
-
-
VesselComponentId
-
DataType: Guid
-
Filterable: true
-
Purpose: Specifies the vessel component.
-
-
ParentComponentId
-
DataType: Guid
-
Filterable: true
-
Purpose: Specifies the parent vessel component.
-
-
AssetId
-
DataType: Guid
-
Filterable: true
-
Purpose: Specifies the asset that is using or restoring the component.
-
-
Active
-
DataType: boolean
-
Filterable: true
-
Purpose: Specifies if the component is in use.
-
-
Deactivated
-
DataType: date
-
Filterable: true
-
Purpose: Specifies when the component is deactivated.
-
-
ComponentTypeId
-
DataType: Guid
-
Filterable: true
-
Purpose: Specifies the component type of the component.
-
-
ComponentTypeName
-
DataType: string
-
Filterable: true
-
Purpose: Specifies the name of the component type of the component.
-
-
EssentialSystem
-
DataType: boolean
-
Filterable: true
-
Purpose: Specifies if the component is a critical system. Affects responsible party alerting.
-
-
MakeId
-
DataType: Guid
-
Filterable: true
-
Purpose: Specifies the make of the component.
-
-
MakeName
-
DataType: string
-
Filterable: true
-
Purpose: Specifies the name of the make of the component.
-
-
ModelId
-
DataType: Guid
-
Filterable: true
-
Purpose: Specifies the model of the component.
-
-
ModelName
-
DataType: string
-
Filterable: true
-
Purpose: Specifies the name of the model of the component.
-
-
Modified
-
DataType: date
-
Filterable: true
-
Purpose: Specifies the last time that the component is updated.
-
-
SerialNumber
-
DataType: string
-
Filterable: true
-
Purpose: Specifies the serial number of the component.
-
-
PartNumber
-
DataType: string
-
Filterable: true
-
Purpose: Specifies the part number of the component.
-
-
ReceivePropagatedReadings
-
DataType: boolean
-
Filterable: true
-
Purpose: Specifies if the component receives propagated readings.
-
-
UserDefined
-
DataType: User Defined Data Model (see User User Defined Fields for more details)
-
Filterable: false
-
Purpose: Sets the UserDefined for the component. Will be set to null if not specified.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Component
URI
GET api/v2/public/components
or
GET api/v2/public/components/{Id}
Example Usage
// Get a paginated response of all components
GET api/v2/public/components
// Get a specific component by Id
GET api/v2/public/components/d21d73fb-bb69-11e8-8102-00155d040945
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/components?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Components with Name equal to "Main Engine" GET api/v2/public/components?$filter=Name eq 'Main Engine' // Get Components with Active equal to "true" GET api/v2/public/components?$filter=Active eq true // Get Components with EssentialSystem equal to "true" GET api/v2/public/components?$filter=EssentialSystem eq true // Get Components with ComponentTypeId = 4cb25fa3-4b61-11e9-9d1b-f01faf02f2e9 GET api/v2/public/components?$filter=ComponentTypeId eq (guid'4cb25fa3-4b61-11e9-9d1b-f01faf02f2e9') // Get Components with Deactivated that is greater than "2020-02-03" GET api/v2/public/components?$filter=Deactivated gt datetime'2020-02-03' // Get Components with Modified that is less than "2020-02-03" GET api/v2/public/components?$filter=Modified lt datetime'2020-02-03'
-
Required Permissions
One or both of the following:
- Management > Assets > Assets > Components > Read
- Management > Assets > Assets > Components > Edit
Return Value
Action Accepted
Returns an array containing the requested components in the format of the Component Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Component Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Currency Exchange Rate
Create/Update Currency Exchange Rate
URI
api/v1/jobs/billing/CreateOrUpdateCurrencyExchangeRate
Supported Verbs
- POST: insert or update a currency exchange rate.
Required Parameters
-
Currency Exchange Rate Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Currency Exchange Rate Model to be created or updated.
-
Data Model
Currency Exchange Rate Model
{
"CurrencyType":
{
"Id": <GUID>,
"Name": <string>,
},
"EffectiveDate": <date>,
"ExchangeRate": <decimal>
}
Currency Exchange Rate Object Fields
-
CurrencyType
-
DataType: JSON Object
-
Required: true
-
Purpose: Selects the currency type whose exchange rate will be altered.
-
Function: Selects the CurrencyTypeId that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
[max. 200 char]
-
-
-
EffectiveDate
-
DataType:
<date>
-
Required: true
-
Purpose: Selects the date of the exchange rate you want to create or update. If an exchange rate already exists for this date it will be updated; otherwise a new exchange rate will be created. This parameter accepts a fully specified date but only the year, month and day will be used; the time and timezone will not be used.
-
-
ExchangeRate
-
DataType:
<decimal>
-
Required: true
-
Purpose: Sets the Exchange Rate for the currency type and date specified.
-
Return Value
Action Accepted
"Data":
{
"CurrencyTypeId": <Guid>,
"LogMessages":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
CurrencyTypeId: Guid for the currency type that exchange rates were added/updated for.
-
LogMessages: This will describe any failures that occurred when trying to find the matching entity. For example, if the CurrencyType could not be determined from your POST.
Action Rejected
"Data": <Array>
- Data: Log Messages
Delete Currency Exchange Rate
URI
api/v1/jobs/billing/DeleteCurrencyExchangeRate
Supported Verbs
- POST: delete currency exchange rate(s) on a given date.
Required Parameters
-
User Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Currency Exchange Rate Model to be deleted.
-
Data Model
Currency Exchange Rate Model
{
"CurrencyType":
{
"Id": <GUID>,
"Name": <string>,
},
"EffectiveDate": <date>
}
User Object Fields
-
CurrencyType
-
DataType: JSON Object
-
Required: true
-
Purpose: Selects the currency type whose exchange rate(s) may be deleted.
-
Function: Selects the CurrencyTypeId that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
[max. 200 char]
-
-
-
EffectiveDate
-
DataType:
<date>
-
Required: true
-
Purpose: Selects the date of the exchange rate(s) you want to delete. All exchange rates that exist for this date will be deleted. If no exchange rates exist for this date then nothing will be deleted and no error will be returned. This parameter accepts a fully specified date but only the year, month and day will be used; the time and timezone will not be used.
-
Return Value
Action Accepted
"Data":
{
"CurrencyTypeId": <Guid>,
"ExchangeRatesDeleted": <integer>,
"LogMessages":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
CurrencyTypeId: Guid for the currency type that exchange rate(s) may have been deleted for.
-
ExchangeRatesDeleted: The number of exchange rates that were deleted.
-
LogMessages: This will describe any failures that occurred when trying to find the matching entity. For example, if the CurrencyType could not be determined from your POST.
Action Rejected
"Data": <Array>
- Data: Log Messages
Divisions
Find Divisions
URI
api/v1/jobs/Divisions/FindDivisions
Supported Verbs
- GET: return a filtered list of divisions. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/Divisions/FindDivisions?page=2
-
Optional Parameters
-
SearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the Divisions with Name or ShortName that contains the given string.
-
Example Usage:
api/v1/jobs/Divisions/FindDivisions?page=1&SearchString=partOfTheName
-
-
ParentDivisionId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return Divisions with matching ParentDivisionId.
-
Example Usage:
api/v1/jobs/Divisions/FindDivisions?page=1&ParentDivisionId=93c76fd9-790d-4ede-86fb-e9c8470770f0
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"ExternalSystemCode": <string>,
"AccountingCode": <string>,
"ParentDivisionId": <GUID>,
"DivisionType":
{
"Id": <GUID>,
"Name": <string>
},
},
...
]
}
}
Earning Code
Create/Update Earning Code
URI
api/v1/Personnel/EarningCodes/CreateOrUpdateEarningCode
Supported Verbs
- POST: insert or update an earning code.
Required Parameters
-
Earning Code Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Earning Code Model to be created or updated.
-
Data Model
Earning Code Model
{
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>,
"QuantityType": <string>,
"DoArchive": <boolean>
}
Earning Code Object Fields
-
Id
-
DataType: GUID
-
Required: true when updating
-
Purpose: Identify the earning code to update
-
-
Name
-
DataType: string [max. 200 char]
-
Required: true
-
Purpose: Sets the Name for the Earning Code.
-
-
AccountingCode
-
DataType: string [max. 50 char]
-
Required: false
-
Purpose: Sets the AccountingCode for the Earning Code.
-
-
QuantityType
-
DataType: string [max. 20 char]
-
Required: false
-
Purpose: Sets the QuantityType for the Earning Code.
-
Accepted Value: “fixed”, “daily”, “hourly”, “amount”
-
-
DoArchive
-
DataType: boolean
-
Required: false
-
Purpose: Archive the Earning Code.
-
Note: This field will be ignored when creating a new earning code. Once archived, it can’t be reverted.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Insert or Update
-
Id: Guid for the new earning code if ActionType is insert.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Find Earning Code
URI
api/v1/Personnel/EarningCodes/FindEarningCodes
Supported Verbs
- GET: return a filtered list of earning codes. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/Personnel/EarningCodes/FindEarningCodes?page=2
-
Optional Parameters
-
Name:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return earning code with Name containing the string
-
Example Usage:
api/v1/Personnel/EarningCodes/FindEarningCodes?page=2&Name=Foo
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page":
[
{
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>,
"QuantityType": <string>
},
....
]
}
}
Action Rejected
"Data": <Array>
- Data: Error Message
Event
Create/Update Event
URI
api/v1/core/events/CreateOrUpdateEvent
Supported Verbs
- POST: insert or update an event.
Required Parameters
-
Event Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Event Model to be created.
-
Data Model
Event Model
{
"Id": <GUID>,
"Description": <string>,
"EventDate": <date>,
"EventTypeId": <GUID>,
"VesselId": <GUID>,
"SpaceId": <GUID>,
"LocationId": <GUID>,
"RecordedByPersonId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Event Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: Update the uniquely matching event.
-
-
Description
-
DataType: string [max. 1000 char]
-
Required: false
-
Purpose: Sets the description for the Event.
-
-
EventDate
-
DataType: date
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event date.
-
-
EventTypeId
-
DataType: Guid for the Event type
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event type.
-
-
VesselId
-
DataType: Guid for the Event’s vessel.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event asset.
-
-
SpaceId
-
DataType: Guid for the Event’s space.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event space.
-
-
LocationId
-
DataType: Guid for the Event location
-
Required: false
-
Purpose: Sets the Event location.
-
-
RecordedByPersonId
-
DataType: Guid for the Event recorded by person.
-
Required: false
-
Purpose: Sets who recorded the Event.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Event. Will be set to null if not specified.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>
"Message": <string>
},
....
]
}
-
ActionType: ‘Insert or Update’.
-
Id: Guid for the new Event.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Find Events
URI
api/v1/core/events/FindEvents
Supported Verbs
- GET: return a filtered list of Events. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/core/events/FindEvents?page=1
-
Optional Parameters
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Event with the given Id
-
Example Usage:
api/v1/core/events/FindEvents?page=1&Id=d21d73fb-bb69-11e8-8102-00155d040945
-
-
AssetId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Event with the given Asset Id
-
Example Usage:
api/v1/core/events/FindEvents?page=1&AssetId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ChangedSince:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return events that have been modified or created since the datetime.
-
Example Usage
api/v1/core/events/FindEvents?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
EventTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Event with the given EventTypeId
-
Example Usage:
api/v1/core/events/FindEvents?page=1&EventTypeId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
LocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Event with the given LocationId
-
Example Usage:
api/v1/core/events/FindEvents?page=1&LocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
RecordedByPersonId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Event with the given RecordedByPersonId
-
Example Usage:
api/v1/core/events/FindEvents?page=1&RecordedByPersonId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
FromDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Events based on EventDate >= FromDate
-
Example Usage:
api/v1/core/events/FindEvents?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Events based on EventDate <= ToDate
-
Example Usage:
api/v1/core/events/FindEvents?page=1&ToDate=2016-03-10T14:23:00-08:00
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Description": <string>,
"EventDate": <date>,
"EventTypeId": <GUID>,
"AssetId": <GUID>,
"SpaceId": <GUID>,
"LocationId": <GUID>,
"RecordedByPersonId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
...
]
}
}
Archive Event
URI
api/v1/core/events/ArchiveEvent
Supported Verbs
- POST: Archive an event.
Required Parameters
-
Archive Event Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Event Id to be archived.
-
Data Model
Archive Event Model
{
"Id": <Guid>
}
Archive Event Object Fields
-
Id
-
DataType: Guid
-
Required: true
-
Purpose: Archives the uniquely matching Event
-
Return Value
Action Accepted
{
"ActionType": "Archive",
"Id": <GUID>
}
-
ActionType: Will always be ‘Archive’.
-
Id: Guid for the Event.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Create/Update Trip Event
URI
api/v1/jobs/events/CreateOrUpdateTripEvent
Supported Verbs
- POST: insert or update a trip event.
Required Parameters
-
Trip Event Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Trip Event Model to be created.
-
Data Model
Trip Event Model
{
"Id": <Guid>,
"TripId": <GUID>,
"EventTypeId": <GUID>,
"Description": <string>,
"EventDate": <date>,
"LocationId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Trip Event Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: Update the uniquely matching Trip Event
-
-
TripId
-
DataType: Guid for the Trip Event’s trip.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Trip Event’s trip.
-
-
EventTypeId
-
DataType: Guid for the Trip Event’s type.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event type.
-
-
Description
-
DataType: string
-
Required: false
-
Purpose: Sets the description for the Trip Event.
-
-
EventDate
-
DataType: date
-
Required: false
-
Purpose: Sets the Trip Event’s date.
-
-
LocationId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the Trip Event’s location.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Trip Event. Will be set to null if not specified.
-
Return Value
Action Accepted
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
ActionType: ‘Insert’ or ‘Update’.
-
Id: Guid for the Trip Event.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
-
Details: Additional information about the error.
Action Rejected
"Data": <Array>
- Data: Error Message
Find Trip Events
URI
api/v1/jobs/events/FindTripEvents
Supported Verbs
- GET: return a filtered list of Trip Events. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/events/FindTripEvents?page=1
-
Optional Parameters
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Trip Event with the given Id
-
Example Usage:
api/v1/jobs/events/FindTripEvents?page=1&Id=d21d73fb-bb69-11e8-8102-00155d040945
-
-
TripId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trip Events with the given TripId
-
Example Usage:
api/v1/jobs/events/FindTripEvents?page=1&TripId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ChangedSince:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trip Events that have been modified or created since the datetime.
-
Example Usage
api/v1/jobs/events/FindTripEvents?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
EventTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trip Events with the given EventTypeId
-
Example Usage:
api/v1/jobs/events/FindTripEvents?page=1&EventTypeId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
LocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trip Events with the given LocationId
-
Example Usage:
api/v1/jobs/events/FindTripEvents?page=1&LocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
FromDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trip Events based on TripEvent.EventDate >= FromDate
-
Example Usage
api/v1/jobs/events/FindTripEvents?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Trip Events based on TripEvent.EventDate <= ToDate
-
Example Usage
api/v1/jobs/events/FindTripEvents?page=1&ToDate=2016-03-10T14:23:00-08:00
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"TripId": <GUID>,
"EventTypeId": <GUID>,
"Description": <string>,
"EventDate": <date>,
"LocationId": <Guid>,
"UserDefined": UserDefinedDataModel (see User Defined Fields section for more details)
},
...
]
}
}
Create/Update Job Event
URI
api/v1/jobs/events/CreateOrUpdateJobEvent
Supported Verbs
- POST: insert or update a Job Event.
Required Parameters
-
Job Event Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Job Event Model to be created.
-
Data Model
Job Event Model
{
"Id": <Guid>,
"JobId": <GUID>,
"EventTypeId": <GUID>,
"Description": <string>,
"PlannedEventDate": <date>,
"EventDate": <date>,
"LocationId": <GUID>,
"RecordedByPersonId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Job Event Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: Update the uniquely matching Job Event
-
-
JobId
-
DataType: Guid for the Job Events’s job.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Job Event’s job. Not supported for update.
-
-
EventTypeId
-
DataType: Guid for the Job Event’s type.
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event type.
-
-
Description
-
DataType: string [max. 1000 char]
-
Required: false
-
Purpose: Sets the description for the Job Event.
-
-
PlannedEventDate
-
DataType: date
-
Required: false
-
Purpose: Sets the Job Event’s planned date. Only one of PlannedEventDate and EventDate may be set.
-
-
EventDate
-
DataType: date
-
Required: false
-
Purpose: Sets the Job Event’s date. Only one of PlannedEventDate and EventDate may be set.
-
-
LocationId
-
DataType: Guid for the Location
-
Required: false
-
Purpose: Sets the Job Event’s location.
-
-
RecordedByPersonId
-
DataType: Guid for the Recorded By Person
-
Required: false
-
Purpose: Sets the Job Event’s Recorded By Person.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Job Event. Will be set to null if not specified.
-
Return Value
Action Accepted
{
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
Id: Guid for the Job Event.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
-
Details: Additional information about the error.
Action Rejected
"Data": <Array>
- Data: Error Message
Find Job Events
URI
api/v1/jobs/events/FindJobEvents
Supported Verbs
- GET: return a filtered list of Job Events. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1
-
Optional Parameters
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Job Event with the given Id
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&Id=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ResourceId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events with the given ResourceId
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&ResourceId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
JobId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events with the given JobId
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&JobId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
ChangedSince:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return job events that have been modified or created since the datetime.
-
Example Usage
api/v1/jobs/events/FindJobEvents?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
EventTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events with the given EventTypeId
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&EventTypeId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
LocationId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events with the given LocationId
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&LocationId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
RecordedByPersonId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events with the given RecordedByPersonId
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&RecordedByPersonId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
TripId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events whose Jobs have the given TripId
-
Example Usage:
api/v1/jobs/events/FindJobEvents?page=1&TripId=d21d73fb-bb69-11e8-8102-00155d040945
-
-
FromDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events based on EventDate >= FromDate
-
Example Usage
api/v1/jobs/events/FindJobEvents?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Job Events based on EventDate <= ToDate
-
Example Usage
api/v1/jobs/events/FindJobEvents?page=1&ToDate=2016-03-10T14:23:00-08:00
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"ResourceId": <GUID>,
"TripId": <GUID>,
"JobId": <GUID>,
"EventTypeId": <GUID>,
"Description": <string>,
"PlannedEventDate": <date>,
"EventDate": <date>,
"LocationId": <GUID>,
"RecordedByPersonId": <GUID>,
"UserDefined": UserDefinedDataModel (see User Defined Fields section for more details)
},
...
]
}
}
Event Type
URI
api/v2/public/eventtypes
Supported Verbs
GET
- Find Event Types.
Data Models
Event Type Model
{
"Id": <GUID>,
"Name": <string>,
"Spaces": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
},
...
],
"Tags": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
},
...
]
}
Event Type Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify an event type.
-
-
Name
-
DataType: string [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of an event type.
-
-
Spaces
-
DataType: Array
-
Purpose: Defines the spaces this event type is visible in.
-
Fields:
- Id
<GUID>
- Name
<string>
- Id
-
-
Tags
-
DataType: Array
-
Purpose: Defines the tags this event type has.
-
Fields:
- Id
<GUID>
- Name
<string>
- Id
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Event Types
URI
GET api/v2/public/eventtypes
or
GET api/v2/public/eventtypes/{Id}
Example Usage
// Get a paginated response of all event types
GET api/v2/public/eventtypes
// Get a specific event type by Id
GET api/v2/public/eventtypes/d21d73fb-bb69-11e8-8102-00155d040945
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/eventtypes?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Event Types with Name equal to "Drill" GET api/v2/public/eventtypes?$filter=Name eq 'Drill'
-
Return Value
Action Accepted
Returns an array containing the requested Event Types in the format of the Event Types Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Event Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Setup > Events > Event Types
Emergency Contacts
URI
api/v2/public/emergencycontacts
Supported Verbs
-
GET
- Find emergency contacts
-
POST
- Create new emergency contacts
-
PATCH
- Update existing emergency contacts
-
DELETE
- Remove existing emergency contacts
Data Models
Emergency Contact Model
{
"Id": <GUID>,
"PersonId": <GUID>,
"Name": <string>,
"PhoneNumber": <string>,
"AlternatePhoneNumber": <string>,
"EmailAddresses": <string>,
"Relationship": <string>,
"Address": <string>,
"City": <string>,
"Country": <string>,
"StateOrProvince": <string>,
"PostalZipCode": <string>,
"SortOrder": <integer>,
"UserDefinedFields": User Defined Data Model (see User Defined Fields section for more details)
}
Emergency Contact Fields
-
Id
-
Data Type: Guid
-
Required: False when using
POST
to create. True when usingPATCH
to update orDELETE
to delete (unless Id is already specified in the URI). -
Purpose: To uniquely identify an Emergency Contact and to specify which Emergency Contact to apply an operation to.
-
-
PersonId
-
Data Type: Guid
-
Required: True when using
POST
to create; otherwise, False. -
Filterable: True
-
Purpose: Specifies the person this emergency contact is for. Cannot be
PATCH
ed.
-
-
Name
-
Data Type: string [max. 300 char]
-
Required: True when using
POST
to create; otherwise, False. -
Filterable: True
-
Purpose: Specifies the name of the emergency contact.
-
-
PhoneNumber
-
Data Type: string [max. 50 char]
-
Required: True when using
POST
to create; otherwise, False. -
Filterable: True
-
Purpose: Specifies the primary phone number of the emergency contact.
-
-
AlternatePhoneNumber
-
Data Type: string [max. 50 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies an alternative phone number of the emergency contact.
-
-
EmailAddresses
-
Data Type: string [max. 1000 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies a comma-separated list of email addresses of the emergency contact. The maximum length includes comma characters.
-
-
Relationship
-
Data Type: string [max. 200 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the relationship of the emergency contact to the person. Eg: Wife, girlfriend, husband, mother, etc.
-
-
Address
-
Data Type: string [max. 1000 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the address line of the emergency contact. Eg: 1600 Pennsylvania Avenue NW.
-
-
City
-
Data Type: string [max. 200 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the city the emergency contact lives in.
-
-
Country
-
Data Type: string [max. 200 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the country the emergency contact lives in.
-
-
StateOrProvince
-
Data Type: string [max. 200 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the state or province the emergency contact lives in.
-
-
PostalZipCode
-
Data Type: string [max. 20 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the postal or zip code of the emergency contact.
-
-
SortOrder
-
Data Type: integer [min: 0]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the order of the emergency contact in the list of contacts for the person. If there is a collision between two contact’s
SortOrder
, then the updated one is used. If both are updated, they are processed in the order sent in the request body. The contact is appended if theSortOrder
is too large. -
Default Value: 0
-
-
UserDefinedFields
-
Data Type: User Defined Data Model (see User Defined Fields section for more details)
-
Required: False
-
Purpose: Specifies the User Defined Fields of the emergency contact.
-
Default Value: null
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
Data Type: integer
-
Purpose: A unique identifier for this type of error.
-
-
ErrorMessage
-
Data Type: string
-
Purpose: A message which describes what the error means.
-
Find Emergency Contacts
URIs
GET api/v2/public/emergencycontacts
or
GET api/v2/public/emergencycontacts/{Id}
Example Usage
// Gets a paged result of emergency contacts
GET api/v2/public/emergencycontacts
// Gets a single emergency contact
GET api/v2/public/emergencycontacts/c5e69784-24c5-11e7-82c5-f01faf32a6aa
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/emergencycontacts?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get the emergency contacts who are wives GET api/v2/public/emergencycontacts?$filter=Relationship eq 'Wife' // Get the emergency contacts who reside in the USA GET api/v2/public/emergencycontacts?$filter=Country eq 'USA' // Get the first emergency contacts of everyone GET api/v2/public/emergencycontacts?$filter=SortOrder eq 0
-
Required Permissions
One or both of the following:
- Sensitive Api > Emergency Contacts > Read
- Sensitive Api > Emergency Contacts > Edit
Return Value
Action Accepted
Returns an array containing the requested Emergency Contacts in the format of the Emergency Conact Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Emergency Contact Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Create Emergency Contact
URI
POST api/v2/public/emergencycontacts
Example Usage
// Add a single emergency contact
POST api/v2/public/emergencycontacts
{
"PersonId": "c5e69784-24c5-11e7-82c5-f01faf32a6aa",
"Name": "George Washington",
"PhoneNumber": "202-456-1111"
}
// Add multiple emergency contacts.
POST api/v2/public/emergencycontacts
[
{
"PersonId": "c5e69784-24c5-11e7-82c5-f01faf32a6aa",
"Name": "Benjamin Franklin",
"PhoneNumber": "1-800-ASK-USPS"
},
{
"PersonId": "c5e69784-24c5-11e7-82c5-f01faf32a6aa",
"Name": "James Madison",
"PhoneNumber": "1-866-272-6272"
}
]
// The contacts current order would look like the following:
// - James Madison
// - Benjamin Franklin
// - George Washington
// Append an emergency contact
POST api/v2/public/emergencycontacts
{
"PersonId": "c5e69784-24c5-11e7-82c5-f01faf32a6aa",
"Name": "Alexandar Hamilton",
"PhoneNumber": "(202) 622-2000",
"SortOrder": 100,
}
// Contacts:
// - James Madison
// - Benjamin Franklin
// - George Washington
// - Alexander Hamilton
// Insert an emergency contact
POST api/v2/public/emergencycontacts
{
"PersonId": "c5e69784-24c5-11e7-82c5-f01faf32a6aa",
"Name": "Thomas Jefferson",
"PhoneNumber": "1-866-272-6272",
"SortOrder": 2,
}
// Contacts:
// - James Madison
// - Benjamin Franklin
// - Thomas Jefferson
// - George Washington
// - Alexander Hamilton
Required Parameters
-
Data Type: Emergency Contact Model or Array of Emergency Contact Model
-
Parameters Type: request body
-
Purpose: Supplies the Emergency Contact(s) to be created.
Required Permissions
- Sensitive Api > Emergency Contacts > Edit
Return Value
Action Accepted
Returns a single Emergency Contact Model or an array of Emergency Contact Model.
<Emergency Contact Model> | <Array of Emergency Contact Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Update Emergency Contact
URI
PATCH api/v2/public/emergencycontacts
or
PATCH api/v2/public/emergencycontacts/{Id}
Example Usage
// Contacts:
// - James Madison
// - Benjamin Franklin
// - George Washington (Id: 7694520e-b2de-4dbe-9d6d-fbf8addd8a28)
// - Alexander Hamilton
// Update George to be the first contact
PATCH api/v2/public/emergencycontacts/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
{
"SortOrder": 0
}
// Contacts:
// - George Washington (Id: 7694520e-b2de-4dbe-9d6d-fbf8addd8a28)
// - James Madison
// - Benjamin Franklin
// - Alexander Hamilton
// Update an Emergency Contact's City
PATCH api/v2/public/emergencycontacts
{
"Id": "7694520e-b2de-4dbe-9d6d-fbf8addd8a28",
"City": "Mount Vernon"
}
// or
PATCH api/v2/public/emergencycontacts/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
{
"City": "Mount Vernon"
}
Required Parameters
-
Id
-
Data Type: Guid
-
Parameters Type: request path or request body
-
Purpose: To specify which Emergency Contact to apply an operation to.
-
Required Permissions
- Sensitive Api > Emergency Contacts > Edit
Return Value
Action Accepted
Returns a single or an array of all modified Emergency Contacts. If there were two emergency contacts and the second one was updated to be the first, both contacts would be returned.
<Emergency Contact Model> | <Array of Emergency Contact Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Delete Emergency Contact
URI
DELETE api/v2/public/emergencycontacts/{Id}
Example Usage
// Contacts:
// - James Madison
// - Benjamin Franklin
// - George Washington (Id: 7694520e-b2de-4dbe-9d6d-fbf8addd8a28)
// - Alexander Hamilton
// Remove George as a contact
DELETE api/v2/public/emergencycontacts/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
// Contacts:
// - James Madison
// - Benjamin Franklin
// - Alexander Hamilton
Required Parameters
-
Id
-
Data Type: Guid
-
Parameters Type: request path
-
Purpose: To specify which Emergency Contact to delete.
-
Required Permissions
- Sensitive Api > Emergency Contacts > Edit
Return Value
Action Accepted
Returns nothing.
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Field Settings
URI
api/v1/system/fieldsettings
Supported Verbs
GET
- Find Field Settings.
Data Models
Field Setting Model
{
"EntityType": <string>,
"TargetType": <string>,
"TargetId": <GUID>,
"TargetName": <string>,
"Site": <string>,
"DivisionId": <GUID>,
"DivisionName": <string>,
"Modified": <date>,
"SystemFields": {
ENTITY_SPECIFIC_SYSTEM_FIELD_NAME_1: <Field Details Model>,
ENTITY_SPECIFIC_SYSTEM_FIELD_NAME_2: <Field Details Model>,
...
},
"UserDefinedFields": {
ENTITY_SPECIFIC_USER_DEFINED_FIELD_NAME_1: <Field Details Model>,
ENTITY_SPECIFIC_USER_DEFINED_FIELD_NAME_2: <Field Details Model>,
...
}
}
Field Details Model
{
"Visible": <bool>,
"Required": <bool>,
"SortOrder": <integer>
}
Field Setting Fields
-
EntityType
-
DataType: string
-
Purpose: Specifies the entity (e.g., Order, Trip) that the setting entry applies to. See “Supported Entity Types” below.
-
-
TargetType
-
DataType: string
-
Purpose: Specifies the type of the target (i.e., category) that the setting entry applies to. For example, a user may give a “sailing trip” and a “docking trip” different settings; the setting that pertains to the “sailing trip” has a target type of “TripType” and a TargetId that references the sailing TripType entity. The API sets this field to null for entities that do not have targets (e.g., Order). See “Supported Target Types” below.
-
-
TargetId
-
DataType: Guid
-
Purpose: Specifies the ID of the target that the setting entry applies to.
-
-
TargetName
-
DataType: string
-
Purpose: Specifies the name of the target that the setting entry applies to.
-
-
Site
-
DataType: string
-
Purpose: Specifies where Helm applies the setting entry. Valid values include “shore”, “asset”, and null. Null indicates that Helm applies the setting entry everywhere.
-
-
DivisionId
-
DataType: Guid
-
Purpose: Specifies the division ID of the setting entry.
-
-
DivisionName
-
DataType: string
-
Purpose: Specifies the division name of the setting entry.
-
-
Modified
-
DataType: date
-
Purpose: Specifies when the setting entry was created or last modified.
-
-
SystemFields
-
DataType: Dictionary of Field Details Model
-
Purpose: Specifies configuration parameters for the entity’s built-in fields.
-
-
UserDefinedFields
-
DataType: Dictionary of Field Details Model
-
Purpose: Specifies configuration parameters for the entity’s user defined fields.
-
Field Details Fields
-
Visible
-
DataType: boolean
-
Purpose: Specifies if the UI should show the field.
-
-
Required
-
DataType: boolean
-
Purpose: Specifies if the UI should require a value for the field.
-
-
SortOrder
-
DataType: integer
-
Purpose: Specifies the order in which the UI shows the field. Null indicates no preference.
-
Supported Entity Types
-
Transaction: Configured from Setup > Invoicing > Transaction Configurations
-
Order: Configured from Setup > Orders > Order Configurations
-
Trip and Job: Configured from Setup > Orders > Trip Types (independently configurable)
-
TripEvent, JobEvent, and Event: Configured from Setup > Events > Event Types (not independently configurable)
-
JobActivity and Activity: Configured from Setup > Events > Activity Types (not independently configurable)
Note that the Helm CONNECT user interface does not support independent configurations for TripEvents, JobEvents, and (core) Events; and JobActivities and (core) Activities. So you will see that the API returns identical data for these types of entities. Moreover, additional entity types may be supported in the future.
Supported Target Types
-
TripType: The target type for Trip and Job settings.
-
EventType: The target type of TripEvent, JobEvent, and Event settings.
-
ActivityType: The target type for JobActivity and Activity settings.
Note that additional target types may be supported in the future.
Find Field Settings
URI
GET api/v1/system/fieldsettings
Example Usage
// Get a paginated response of all field settings
GET api/v1/system/fieldsettings?page=1
// Get a specific setting entry
GET api/v1/system/fieldsettings?page=1&entityType=Job
Required Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains at least 20 records, except for the last batch, which may contain less than 20 records. -
Example Usage:
GET api/v1/system/fieldsettings?page=2
-
Optional Parameters
-
entityType
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by EntityType. See “Supported Entity Types” above.
-
Example Usage:
GET api/v1/system/fieldsettings?page=1&entityType=JobActivity
-
-
targetType
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by TargetType. Filtering by null is not supported. See “Supported Target Types” above.
-
Example Usage:
GET api/v1/system/fieldsettings?page=1&targetType=TripType
-
-
targetId
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by targetId. Filtering by null is not supported.
-
Example Usage:
// Assuming 08af3ea4-4e8e-4455-b7ba-97c85470d4c9 references the sailing TripType, // get all trip settings for sailing GET api/v1/system/fieldsettings?page=1&targetId=08af3ea4-4e8e-4455-b7ba-97c85470d4c9
-
-
site
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by site. Filtering by null is not supported.
-
Example Usage:
GET api/v1/system/fieldsettings?page=1&site=asset
-
-
divisionId
:-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by division ID.
-
Example Usage:
GET api/v1/system/fieldsettings?page=1&divisionId=e835f434-f5e7-4fbf-904a-96c13c5499c5
-
-
changedSince
:-
Data Type: date
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by created or last modified date.
-
Example Usage:
GET api/v1/system/fieldsettings?page=1&changedSince=2020-06-20T12:00:00-07:00
-
Required Permissions
- Setup > Jobs > Invoicing > Transaction Configurations
- Setup > Jobs > Orders > Order Configuration
- Setup > Jobs > TripTypes > Configurable
- Setup > Jobs > Events > Activity Types
- Setup > Jobs > Events > Event Types
Return Value
Action Accepted
Returns an array containing the requested Field Settings in the format of the Field Setting Model.
{
"Page": <Array of Field Setting Model>
}
Job
Create Job
URI
api/v1/jobs/jobs/CreateJob
Supported Verbs
- POST: insert a Job.
Required Parameters
-
Job Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies the Job information to be created.
-
Optional Parameters
-
asRequest
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of creating a Job directly, a Request for those changes will be created.
-
Example Usage:
api/v1/jobs/jobs/CreateJob?asRequest=true
-
Data Model
Job Model
{
"Trip": {
"Id": <GUID>,
"TripNumber": <string>
},
"RequiredResourceType":
{
"Id": <GUID>,
"Name": <string>
},
"Resource": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Acknowledged": <boolean>,
"RunningTo": <decimal>,
"StartDate": <date>,
"EndDate": <date>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"RunningFrom": <decimal>,
"CancelledDate": <date>,
"IsNoCharge": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Job Object Fields
-
Trip
-
DataType: JSON Object
-
Required: true
-
Purpose: Identify which Trip to add the Job to.
-
Fields:
-
Id
<GUID>
-
TripNumber
<string>
-
-
-
RequiredResourceType
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the RequiredResourceTypeId of the Job.
-
Function: Selects the RequiredResourceType that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
-
-
Resource
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the ResourceId of the Job.
-
Function: Selects the ResourceId of the resource that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
Acknowledged
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the Acknowledged value of the Job.
-
-
RunningTo
-
DataType: decimal
-
Required: false
-
Purpose: Sets the RunningTo time of the of the Job (in minutes).
-
-
StartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the StartDate of the Job.
-
-
EndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the EndDate of the Job.
-
-
PlannedStartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the PlannedStartDate of the Job.
-
-
PlannedEndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the PlannedEndDate of the Job.
-
-
RunningFrom
-
DataType: decimal
-
Required: false
-
Purpose: Sets the RunningFrom time of the of the Job (in minutes).
-
-
CancelledDate
-
DataType: date
-
Required: false
-
Default Value: false
-
Purpose: Sets the CancelledDate of the Job.
-
-
IsNoCharge
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the IsNoCharge status of the Job.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Job.
-
Return Value
With no results
{
"Data":
{
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
}
With results
{
"Data":
{
"JobId": <GUID>,
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
}
Update Job
URI
api/v1/jobs/jobs/UpdateJob
Supported Verbs
- POST: update specified Job. Only Non-Invoiced jobs can be updated. When job’s dates are updated, its job activities’ dates will be updated correspondingly.
Required Parameters
-
Job Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies Job Model to be updated.
-
Optional Parameters
-
asRequest
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of updating a Job directly, a Request for those changes will be created.
-
Example Usage:
api/v1/jobs/jobs/UpdateJob?asRequest=true
-
Data Model
Job Model
{
"Id": <GUID>,
"RequiredResourceType":
{
"Id": <GUID>,
"Name": <string>
},
"Resource": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Acknowledged": <boolean>,
"RunningTo": <decimal>,
"StartDate": <date>,
"EndDate": <date>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"RunningFrom": <decimal>,
"CancelledDate": <date>,
"IsNoCharge": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Job Object Fields
-
Id
-
DataType: GUID
-
Required: true
-
Purpose: If not NULL, the specified job will be updated
-
-
RequiredResourceType
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the RequiredResourceTypeId of the Job.
-
Function: Selects the RequiredResourceType that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
-
-
Resource
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the ResourceId of the Job.
-
Function: Selects the ResourceId of the resource that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
Acknowledged
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the Acknowledged value of the Job.
-
-
RunningTo
-
DataType: decimal
-
Required: false
-
Purpose: Sets the RunningTo time of the of the Job (in minutes).
-
-
StartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the StartDate of the Job.
-
-
EndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the EndDate of the Job.
-
-
PlannedStartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the PlannedStartDate of the Job.
-
-
PlannedEndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the PlannedEndDate of the Job.
-
-
RunningFrom
-
DataType: decimal
-
Required: false
-
Purpose: Sets the RunningFrom time of the of the Job (in minutes).
-
-
CancelledDate
-
DataType: date
-
Required: false
-
Default Value: false
-
Purpose: Sets the CancelledDate of the Job.
-
-
IsNoCharge
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the IsNoCharge status of the Job.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Job.
-
Return Value
With no results
{
"Data":
{
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
}
With results
{
"Data":
{
"JobId": <GUID>,
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
}
Find Jobs
URI
api/v1/jobs/jobs/FindJobs
Supported Verbs
- GET: return a filtered list of Jobs. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/jobs/FindJobs?page=2
-
Optional Parameters
-
JobNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this JobNumber.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&JobNumber=12.3.4
-
-
JobId:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this JobId.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&JobId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
AssignedResourceId:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this Resource assigned (specified by id).
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&AssignedResourceId=c5e69786-24c5-11e7-82c5-f01faf32a6aa
-
-
TripNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this TripNumber.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&TripNumber=12.3
-
-
TripId:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this TripId.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&TripId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
TripStatus:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return jobs on trips that have that currently have this status. Must be one of “STATUS_PENDING”, “STATUS_CONFIRMED”, “STATUS_COMPLETE”, or “STATUS_CANCELLED”.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&TripStatus=STATUS_CONFIRMED
-
-
OrderNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this OrderNumber.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&OrderNumber=12
-
-
OrderId:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have this OrderId.
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&OrderId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
FromDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs where the EndDate is >= FromDate
-
Example Usage:
api/v1/jobs/jobs/FindJobs?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return jobs where the StartDate is <= ToDate.
-
Example Usage
api/v1/jobs/jobs/FindJobs?page=1&ToDate=2016-03-10T14:23:00-08:00
-
-
ChangedSince:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have been created or modified since the date.
-
Example Usage
api/v1/jobs/jobs/FindJobs?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
includeRequests:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, requested Jobs will also be returned
-
Example Usage
api/v1/jobs/jobs/FindJobs?page=1&includeRequests=true
-
-
excludeNonRequests:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, only requested Jobs will be returned
-
Example Usage
api/v1/jobs/jobs/FindJobs?page=1&includeRequests=true&excludeNonRequests=true
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"TripId": <GUID>,
"JobNumber": <string>,
"RequiredResourceType":
{
"Id": <GUID>,
"Name": <string>
},
"Resource": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Acknowledged": <boolean>,
"RunningTo": <decimal>,
"RunningFrom": <decimal>,
"StartDate": <date>,
"EndDate": <date>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"CancelledDate": <date>,
"IsNoCharge": <boolean>,
"IsRequest": <boolean>
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
....
]
}
Delete Job
URI
api/v1/jobs/jobs/DeleteJob
Supported Verbs
- POST: Delete a Job.
Required Parameters
-
Delete Job Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Job Id to be deleted.
-
Data Model
Delete Job Model
{
"Id": <Guid>
}
Delete Job Object Fields
-
Id
-
DataType: Guid
-
Required: true
-
Purpose: Deletes the uniquely matching Job
-
Return Value
Action Accepted
{
"ActionType": "Delete",
"Id": <GUID>
}
-
ActionType: Will always be ‘Delete’.
-
Id: Guid for the Job.
Action Rejected
"Data": <Array>
- Data: Error Message
Acknowledge Job
URI
api/v1/jobs/jobs/AcknowledgeJob
Supported Verbs
- POST: Set specified Job with assigned Resource to Acknowledged.
Required Parameters
-
JobId
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: The JobId of the Job to be acknowledged.
-
Example Usage:
api/v1/jobs/jobs/AcknowledgeJob?JobId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
Optional Parameters
- None
Return Value
Action Accepted
{
"Data": null
}
Action Rejected
{
"Message": <string>
}
- Message: Error Messages
Location
URI
api/v2/public/locations
Supported Verbs
-
GET
- Find Locations.
-
POST
- Create new Locations.
- Add Divisions to existing Locations.
-
PATCH
- Update existing Locations.
-
DELETE
- Remove Divisions from existing Locations.
Data Models
Location Model
{
"Id": <GUID>,
"Name": <string>,
"ShortName": <string>,
"RunningTime": <integer>,
"IsRequested": <boolean>,
"ExternalSystemCode": <string>,
"IsArea": <boolean>,
"Latitude": <decimal>,
"Longitude": <decimal>,
"TimeZone": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Parent": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"LocationType": {
"Id": <GUID>,
"Name": <string>
},
"Divisions": <Array> [
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
...
],
"Modified": <datetime>
}
Location Fields
-
Id
-
DataType: GUID
-
Required: False when using POST to create, True when using PATCH to update (unless Id is already specified in the URI).
-
Purpose: To uniquely identify a Location and to specify which Location to apply an operation to.
-
-
Name
-
DataType: string [max. 400 char]
-
Required: True when using POST to create, False when using PATCH to update.
-
Filterable: True
-
Purpose: Specifies the name of a Location.
-
-
ShortName
-
DataType: string [max. 100 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies a shortened name for a Location.
-
-
RunningTime
-
DataType: integer
-
Required: False
-
Purpose: Specifies the Running Time in minutes. For example, a running time of 2 hours would be represented by a value of
120
(representing 120 minutes).
-
-
IsRequested
-
DataType: boolean
-
Required: False
-
Filterable: True
-
Purpose: If true on POST, specifies that this Location be created as a request. It is invalid to set this field on a PATCH.
-
-
ExternalSystemCode
-
DataType: string [max. 200 char]
-
Required: False
-
Filterable: True
-
-
IsArea
-
DataType: boolean
-
Required: False. Providing it for any request is an error.
-
Filterable: True
-
Purpose: True if this Location is also an Area. Being an Area means a Location has one or more Divisions. If a Location has no Divisions then this is false. This field is read-only and it is an error to attempt to set it to any value; set Divisions instead.
-
-
Latitude
-
DataType: decimal
-
Required: False
-
Purpose: Specifies the latitude of the location in degrees. Must be between -90 and 90.
-
-
Longitude
-
DataType: decimal
-
Required: False
-
Purpose: Specifies the longitude of the location in degrees. Must be between -180 and 180.
-
-
TimeZone
-
DataType: string
-
Required: False
-
Purpose: Specifies the timezone of the location as an IANA zone ID.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Location. Will be set to null if not specified.
-
-
Parent
-
DataType: object
-
Required: false
-
Filterable: True
-
Purpose: Defines a Parent for this Location, so that it is possible to construct a tree of Locations. Either Name or Id can be set to identify another Location. If both are set, they must point to the same Location. If there are multiple Locations with the same Name then Id must be used. If Name is used, supports referring to other Locations in the same request; for example, if multiple Locations are POST in an array at the same time, Name can be used to refer to the name of other Locations in the same request, allowing a tree of Locations to be built using one request.
-
Fields:
- Id
<GUID>
: optional - Name
<string>
: optional - ExternalSystemCode
<string>
: read-only
- Id
-
-
LocationType
-
DataType: object
-
Required: false
-
Purpose: Defines a Location Type for this Location. Either Name or Id can be set to identify a Location Type. If both are set, they must point to the same Location Type.
-
Fields:
- Id
<GUID>
: optional - Name
<string>
: optional
- Id
-
-
Divisions
-
DataType: Array
-
Required: false
-
Filterable: True
-
Purpose: Defines the Divisions which are attached to this Location. Divisions must not be redundant (for example, a division that is the root of the division tree can not be specified at the same time as a division that is a child of that division).
-
Fields:
- Id
<GUID>
: required for each Division - Name
<string>
: read-only - ExternalSystemCode
<string>
: read-only
- Id
-
-
Modified
-
DataType: datetime
-
Required: False
-
Purpose: The latest modified date of this location
-
Filterable: True
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Location
URI
GET api/v2/public/locations
or
GET api/v2/public/locations/{Id}
Example Usage
// Get a paginated response of all locations
GET api/v2/public/locations
// Get a specific location by Id
GET api/v2/public/locations/d21d73fb-bb69-11e8-8102-00155d040945
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/locations?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Locations with Name equal to "Canada" GET api/v2/public/locations?$filter=Name eq 'Canada' // Get Locations with ShortName equal to "CA" GET api/v2/public/locations?$filter=ShortName eq 'CA' // Get Locations with Parent Name equal to "Halifax" GET api/v2/public/locations?$filter=Parent/Name eq 'Halifax' // Get Locations with Division Name equal to "CANADA WEST" GET api/v2/public/locations?$filter=Divisions/any(p:p/Name eq 'CANADA WEST') // Get Locations with IsRequested = true GET api/v2/public/locations?$filter=IsRequested eq true
-
Required Permissions
One or both of the following:
- Setup > Locations > Locations > Read
- Setup > Locations > Locations > Edit
Return Value
Action Accepted
Returns an array containing the requested Locations in the format of the Location Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Location Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Create Location
URI
POST api/v2/public/locations
Example Usage
// Create one Location
POST api/v2/public/locations
{ "Name": "Canada" }
// Create a Location tree
POST api/v2/public/locations
[
{
"Name": "Canada"
},
{
"Name": "British Columbia",
"Parent": {
Name: "Canada"
}
}
]
Required Parameters
-
Data Type: Location Model or Array of Location Model
-
Parameter Type: request body
-
Purpose: Supplies the Location(s) to be created.
Required Permissions
- Setup > Locations > Locations > Edit
Return Value
Action Accepted
Returns an array containing the created Locations.
<Array of Location Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Update Location
URIs
Update a Location
PATCH api/v2/public/locations/
or
PATCH api/v2/public/locations/{Id}
Add a Division to a Location
POST api/v2/public/locations/{Id}/divisions
Remove a Division from a Location
DELETE api/v2/public/locations/{Id}/divisions/{DivisionId}
Required Parameters
-
Id
:-
Data Type: GUID
-
Parameter Type: request path or request body
-
Purpose: To specify which Location to apply an operation to.
-
Example Usage:
// Update a Location Name by providing the Id in the request path PATCH api/v2/public/locations/c5e69784-24c5-11e7-82c5-f01faf32a6aa { "Name": "Canada" } // Update the Name of multiple Locations by providing the Id in the request body PATCH api/v2/public/locations [ { "Id": "c5e69784-24c5-11e7-82c5-f01faf32a6aa", "Name": "Canada" }, { "Id": "d21d73fb-bb69-11e8-8102-00155d040945", "Name": "Victoria" } ] // Add a Division to an existing Location POST api/v2/public/locations/c5e69784-24c5-11e7-82c5-f01faf32a6aa/divisions { "Id": "c5e69784-24c5-11e7-82c5-f01faf32a6aa" }
-
Optional Parameters
-
DivisionId
:-
Data Type: GUID
-
Parameter Type: request path
-
Purpose: To specify which Location Division to apply an operation to.
-
Example Usage:
// To remove a Division (with Id of 7694520e-b2de-4dbe-9d6d-fbf8addd8a28) from a Location DELETE api/v2/public/locations/c5e69784-24c5-11e7-82c5-f01faf32a6aa/divisions/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
-
Required Permissions
- Setup > Locations > Locations > Edit
Return Value
Action Accepted
Returns an array containing the modified Locations.
<Array of Location Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Location Type
URI
api/v2/public/locationtypes
Supported Verbs
GET
- Find Location Types.
URI
GET api/v2/public/locationtypes
or
GET api/v2/public/locationtypes/{Id}
Data Models
Location Type Model
{
"Id": <GUID>,
"Name": <string>
}
Location Type Fields
-
Id
-
DataType: GUID
-
Filterable: True
-
Purpose: To uniquely identify a Location Type.
-
-
Name
-
DataType: string [max. 400 char]
-
Filterable: True
-
Purpose: Specifies the name of a Location Type.
-
Example Usage
// Get a paginated response of all location types
GET api/v2/public/locationtypes
// Get a specific location type by Id
GET api/v2/public/locationtypes/15754c54-95b1-4ada-b5bd-f7aef0448348
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/locationtypes?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Location types with Name equal to "Port" GET api/v2/public/locationtypes?$filter=Name eq 'Port'
-
Required Permissions
One or both of the following:
- Setup > Locations > Location Types > Read
- Setup > Locations > Location Types > Edit
Return Value
Action Accepted
Returns an array containing the requested Location Types in the format of the Location Type Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Location Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Order
Create Order
URI
api/v1/jobs/orders/CreateOrder
Supported Verbs
- POST: insert an Order and any associated Trips and Jobs.
Required Parameters
-
OrderModel
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies the Order information and Trip(s)/Job(s) information to be created.
-
Optional Parameters
-
addNewShip
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true and if Ship can’t be found, it will create new Ship based on the information provided.
-
Note: Name is required to add the new Ship
-
Example Usage:
api/v1/Jobs/Orders/CreateOrder?addNewShip=true
-
-
asRequest
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of creating an Order directly, a Request for those changes will be created. Any Trip, Job or Ship that is created as a result will also be created as requests.
-
Example Usage:
api/v1/Jobs/Orders/CreateOrder?asRequest=true
-
Data Model
Order Model
{
"Division":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Area":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Ship":
{
"Id": <GUID>,
"ShipTypeId": <GUID>,
"Name": <string>,
"IMONumber": <string>,
"MMSI": <string>,
"Nation": <string>,
"CallSign": <string>,
"Height": <decimal>,
"Deadweight": <decimal>,
"GT": <decimal>,
"LOA": <decimal>,
"Beam": <decimal>,
"TEU": <decimal>,
"NT": <decimal>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
"CustomerAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"AgentAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"AwardedToAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"OrderDate": <date>,
"CustomerPONumber": <string>,
"VoyageNumber": <string>,
"CargoType":
{
"Id": <GUID>,
"Name": <string>
}
"IsBillable": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"OrderNotes": <Array>
[
{
"Id": <GUID>,
"Message": <string>,
"MessageDate": <date>,
"NoteType": <string>
},
....
],
"Trips": <Array>
[
<TripModel>,
....
]
}
Trip Model
{
"TripType":
{
"Id": <GUID>,
"Name": <string>
},
"FromLocation":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"ToLocation":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Status": <string>,
"RequestedDate": <date>,
"StartDate": <date>,
"EndDate": <date>,
"IsRequestedDateFirm": <boolean>,
"EstimatedDuration": <decimal>,
"NumberRequiredResources": <integer>,
"CancelledDate": <datetime>,
"IsNoCharge": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Jobs": <Array>
[
<JobModel>,
....
]
}
Job Model
{
"RequiredResourceType":
{
"Id": <GUID>,
"Name": <string>
},
"Resource": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Acknowledged": <boolean>,
"RunningTo": <decimal>,
"StartDate": <date>,
"EndDate": <date>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"RunningFrom": <decimal>,
"CancelledDate": <date>,
"IsNoCharge": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Order Object Fields
-
Division
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the DivisionId of the Order.
-
Function: Selects the Division that uniquely matches one or more of the given fields.
-
Note: If a DivisionId is found, it will filter the data by division for the CustomerAccount, AgentAccount, and AwardedToAccount fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
Ship
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the ShipId of the OrderShip of the Order.
-
Function: Selects the Ship that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
ShipTypeId
<GUID>
-
Name
<string>
-
IMONumber
<string>
-
MMSI
<string>
-
Nation
<string>
-
CallSign
<string>
-
Height
<decimal>
-
Deadweight
<decimal>
-
GT
<decimal>
-
LOA
<decimal>
-
Beam
<decimal>
-
TEU
<decimal>
-
NT
<decimal>
-
UserDefined
<JSON>
-
-
Note: The endpoint uses Id, Name, IMONumber, MMSI, CallSign to find ShipId. If no matching ship is found and
?addNewShip=true
is specified, it will create a new Ship with all other properties provided.
-
-
CustomerAccount
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the CustomerAccountId of the Order.
-
Function: Selects the CustomerAccount that uniquely matches one or more of the given fields.
-
Note: Can be filtered by Division. Only matches accounts that have an AccountType that has
IsCustomer = true
. -
Fields:
-
Id
<GUID>
-
Name
<string>
-
AccountNumber
<string>
-
-
-
AgentAccount
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the AgentAccountId of the Order.
-
Function: Selects the AgentAccount that uniquely matches one or more of the given fields.
-
Note: Can be filtered by Division. Only matches accounts that have an AccountType that has
IsAgent = true.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
AccountNumber
<string>
-
-
-
Area
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the Area of the Order.
-
Function: Selects the Area that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
AwardedToAccount
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the AwardedToAccountId of the Order.
-
Function: Selects the AwardedToAccount that uniquely matches one or more of the given fields.
-
Note: Can be filtered by Division. Only matches accounts that have an AccountType that has
IsCompetitor = true
or is an Account that is part of a Company that hasIsMyCompany = true
. -
Fields:
-
Id
<GUID>
-
Name
<string>
-
AccountNumber
<string>
-
-
-
OrderDate
-
DataType: date
-
Required: false
-
Purpose: Sets the OrderDate of the Order.
-
-
VoyageNumber
-
DataType: string
-
Required: false
-
Purpose: Sets the VoyageNumber of the Order.
-
-
CargoType
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the CargoType of the Order.
-
Function: Selects the CargoType that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
-
-
CustomerPONumber
-
DataType: string
-
Required: false
-
Purpose: Sets the CustomerPONumber of the Order.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Order.
-
-
IsBillable
-
DataType: boolean
-
Required: false
-
Default: true when creating an Order. No change when updating an Order.
-
Purpose: Sets whether the Order is billable or not
-
-
OrderNotes
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets Notes on the Order
-
Function: Adds Notes to the Order
-
Fields:
-
Id
<GUID>
-
Message
<string>
-
MessageDate
<date>
-
NoteType
<string>
-
-
Note:
-
Id is required for update
-
NoteType is required for create and must be one of “DISPATCH”, “BILLING”, “CREW”, or “EXTERNAL”
-
Message is required for both create and update
-
MessageDate will default to current date when creating note or existing value if updating note
-
-
-
Trips
-
DataType: Array of JSON Trip Objects (see below)
-
Required: true
-
Purpose: Sets the Trips for the Order.
-
Note: Creating an Order must have at least one Trip attached.
-
Trip Object Fields
-
TripType
-
DataType: JSON Object
-
Required: true
-
Purpose: Sets the TripTypeId of the Trip.
-
Function: Selects the TripType that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
-
-
FromLocation
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the FromLocationId of the Trip.
-
Function: Selects the FromLocation that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<String>
-
ExternalSystemCode
<string>
-
-
-
ToLocation
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the ToLocationId of the Trip.
-
Function: Selects the ToLocation that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<String>
-
ExternalSystemCode
<string>
-
-
-
Status
-
DataType: string
-
Required: false
-
Purpose: Sets the Status of the Trip.
-
Note: Status can be one of the following values and is case sensitive:
-
Null: will mark this Trip as unconfirmed
-
**"**STATUS_COMPLETE": will mark this Trip as complete
-
“STATUS_CONFIRMED”: will mark this Trip as confirmed
-
“STATUS_CANCELLED”: will mark this Trip as cancelled
-
-
-
RequestedDate
-
DataType: date
-
Required: false
-
Purpose: Sets the RequestedDate of the Trip.
-
-
IsRequestedDateFirm
-
DataType: boolean
-
Required: false
-
Purpose: Sets the IsRequestedDateFirm of the Trip.
-
-
EstimatedDuration
-
DataType: decimal
-
Required: false
-
Purpose: Sets the Duration of the Trip.
-
Note: This value is stored in minutes.
-
-
StartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the StartDate of the Trip.
-
-
EndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the EndDate of the Trip.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Trip.
-
-
NumberRequiredResources
-
DataType: Integer
-
Required: false
-
Purpose: Create specified number of Jobs if the Jobs field (see below) is not specified
-
Note: Jobs will have default resource type if client only has one root resource type. Jobs’ startDate and endDate will default to Trip’s startDate and EndDate. Job’s RunningFrom and RunningTo will be defaulted based on the From and To Location.
-
-
CancelledDate
-
DataType: datetime
-
Required: false
-
Purpose: Sets the CancelledDate of the Trip.
-
Note: CancelledDate can only be set on a trip with a status of “STATUS_CANCELLED”.
-
-
IsNoCharge
-
DataType: boolean
-
Required: false
-
Purpose: Sets the IsNoCharge status of the Trip.
-
-
Jobs
-
DataType: an Array of JSON Objects
-
Required: false
-
Purpose: Create Jobs on the Trip
-
Job Object Fields
-
RequiredResourceType
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the RequiredResourceTypeId of the Job.
-
Function: Selects the RequiredResourceType that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
-
-
Resource
-
DataType: JSON Object
-
Required: false
-
Purpose: Sets the ResourceId of the Job.
-
Function: Selects the ResourceId of the resource that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
Acknowledged
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the Acknowledged value of the Job.
-
-
RunningTo
-
DataType: decimal
-
Required: false
-
Purpose: Sets the RunningTo time of the of the Job (in minutes).
-
-
StartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the StartDate of the Job.
-
-
EndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the EndDate of the Job.
-
-
PlannedStartDate
-
DataType: date
-
Required: false
-
Purpose: Sets the PlannedStartDate of the Job.
-
-
PlannedEndDate
-
DataType: date
-
Required: false
-
Purpose: Sets the PlannedEndDate of the Job.
-
-
RunningFrom
-
DataType: decimal
-
Required: false
-
Purpose: Sets the RunningFrom time of the of the Job (in minutes).
-
-
CancelledDate
-
DataType: date
-
Required: false
-
Default Value: false
-
Purpose: Sets the CancelledDate of the Job.
-
-
IsNoCharge
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the IsNoCharge status of the Job.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Job.
-
Return Value
With no results
{
"Data":
{
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
}
With results
{
"Data":
{
"OrderId": <GUID>,
"NewShipId": <GUID>,
"TripIds": <Array of GUID>,
"JobIds": <Array>
[
{
"TripId": GUID,
"JobIds": <Array of GUID>
},
...
],
"OrderNoteIds": <Array of GUID>,
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
...
]
}
}
-
LogMessages: This will describe any failures that occurred when trying to find the matching entity. For Example, if you tried to post:
{ "Division": { "Name": "BadNameThatDoesNotExist" } }
then the Log Message would inform you that Division (the Entity) returned no results. If an entity is required, such as Trip Type, and no result was returned then the operation will not be completed.
Update Order
URI
api/v1/jobs/orders/UpdateOrder
Supported Verbs
- POST: update an Order and any associated Trips.
Note
- This endpoint functions almost exactly like Create Order. The only difference is that an Id must be supplied for the Order Data Model object. For Trips, an Id must be supplied for any Trip that is being updated. If a Trip has no Id, when using Update Order, it is assumed to be a new Trip for the Order, and will be inserted. Any Trips not included will be deleted. NumberRequiredResources and Jobs will be ignored if the Trip already exists in database.
Required Parameters
-
OrderModel
-
Data Type: JSON Object (See Data Model from Create Order for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies the Order information and Trip(s) information to be updated.
-
Optional Parameters
-
addNewShip
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true and if Ship can’t be found, it will create new Ship based on the information provided.
-
Note: Name is required to add the new Ship
-
Example Usage:
api/v1/Jobs/Orders/UpdateOrder?addNewShip=true
-
-
asRequest
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of updating an Order directly, a Request for those changes will be created. Any Trip, Job or Ship that is created as a result will also be created as requests.
-
Example Usage:
api/v1/Jobs/Orders/UpdateOrder?asRequest=true
-
Data Model
-
Refer to Create Order, for full details. This outlines how the Id for Order, Trip(s), and OrderNote(s) must be used when using Update Order. Trips and/or OrderNotes with no Id will be added to the Order.
{ "Id": <GUID>, .... "OrderNotes": <Array> [ { "Id": <GUID>, .... }, { "Message": <string>, "MessageDate": <date>, "NoteType": <string> } ], "Trips": <Array> [ { "Id": <GUID>, .... }, { "TripType": { "Id": <GUID>, "Name": <string> }, "FromLocation": { "Id": <GUID>, "ExternalSystemCode": <string> }, "ToLocation": { "Id": <GUID>, "ExternalSystemCode": <string> }, "Status": <string>, "RequestedDate": <date>, "StartDate": <date>, "EndDate": <date>, "IsRequestedDateFirm": <boolean>, "EstimatedDuration": <decimal> "CancelledDate": <date>, "IsNoCharge": <boolean> }, .... ] }
In the above model, the Order is being updated (Id is supplied). The first Trip is being updated (Id is supplied). The second Trip (which has no Id given), is being inserted for this Order. The first OrderNote is being updated (Id is supplied). The second OrderNote (which has no Id given), is being inserted for this Order.
Return Value
- Same as Create Order.
Find Orders
URI
api/v1/jobs/orders/FindOrders
Supported Verbs
- GET: return a filtered list of Orders and Trips. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=2
-
Optional Parameters
-
ShipName:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have a Ship with the given name.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&ShipName=Helm
-
-
ShipIMONumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have a Ship with the given IMO number.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&ShipIMONumber=12345
-
-
CustomerPONumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have this CustomerPONumber.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&CustomerPONumber=12345
-
-
VoyageNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have this VoyageNumber.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&VoyageNumber=12345
-
-
CargoTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have this CargoTypeId.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&CargoTypeId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
OrderNumber:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have this OrderNumber.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&OrderNumber=12345
-
-
OrderId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have this OrderId.
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&OrderId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
FromDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have Trip(s) where the latest Trip based on EndDate (or RequestedDate if EndDate is blank) is >= FromDate
-
Example Usage:
api/v1/Jobs/Orders/FindOrders?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have Trip(s) where the earliest Trip based on StartDate (or RequestedDate if StartDate is blank) is <= ToDate.
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&ToDate=2016-03-10T14:23:00-08:00
-
-
ChangedSince:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have been created or modified since the date.
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
includeRequests:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, requested Orders will also be returned
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&includeRequests=true
-
-
excludeNonRequests:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, only requested Orders will be returned
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&includeRequests=true&excludeNonRequests=true
-
-
includeArchived:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, archived Orders will also be returned
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&includeArchived=true
-
-
areaId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have an Area with the given areaId
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&areaId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
areaSearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have an Area whose name contains the given areaSearchString
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&areaSearchString=partOfTheName
-
-
agentAccountId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have an Agent Account with the given agentAccountId
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&agentAccountId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
agentAccountSearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have an Agent Account whose name contains the given agentAccountSearchString
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&agentAccountSearchString=partOfTheName
-
-
awardedToAccountId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have an Awarded to Account with the given awardedToAccountId
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&awardedToAccountId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
awardedToAccountSearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have an Awarded to Account whose name contains the given awardedToAccountSearchString
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&awardedToAccountSearchString=partOfTheName
-
-
customerAccountId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have a Customer Account with the given customerAccountId
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&customerAccountId=c5e69784-24c5-11e7-82c5-f01faf32a6aa
-
-
customerAccountSearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have a Customer Account whose name contains the given customerAccountSearchString
-
Example Usage
api/v1/Jobs/Orders/FindOrders?page=1&customerAccountSearchString=partOfTheName
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"OrderNumber": <string>,
"CustomerPONumber": <string>,
"VoyageNumber": <string>,
"CargoType": {
"Id": <GUID>,
"Name": <string>
}
"OrderDate": <date>,
"ArchivedDate": <date>,
"Modified": <date>,
"IsRequest": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Division":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Area": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Ship":
{
"Id": <GUID>,
"Name": <string>,
"IMONumber": <string>
},
"CustomerAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"AgentAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"AwardedToAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"Trips": <Array>
[
{
"Id": <GUID>,
"OrderId": <GUID>,
"TripNumber": <string>,
"StartDate": <date>,
"EndDate": <date>,
"RequestedDate": <date>,
"IsRequestedDateFirm": <boolean>,
"EstimatedDuration": <decimal>,
"Status": <string>,
"ArchivedDate": <date>,
"IsRequest": <boolean>,
"OriginalTripId": <GUID>,
"CancelledDate": <datetime>,
"IsNoCharge": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Triptype":
{
"Id": <GUID>,
"Name": <string>
},
"FromLocation":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"ToLocation":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"ContractId": <GUID>,
"ContractAccount":
{
"Id": <GUID>,
"Name": <string>,
"AccountNumber": <string>
},
"Jobs" : <Array>
[
{
"Id": <GUID>,
"TripId": <GUID>,
"JobNumber": <string>,
"RequiredResourceType":
{
"Id": <GUID>,
"Name": <string>
},
"Resource": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Acknowledged": <boolean>,
"RunningTo": <decimal>,
"RunningFrom": <decimal>,
"StartDate": <date>,
"EndDate": <date>,
"PlannedStartDate": <date>,
"PlannedEndDate": <date>,
"CancelledDate": <date>,
"IsNoCharge": <boolean>,
"ArchivedDate": <date>,
"IsRequest": <boolean>
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
....
]
},
....
],
"OrderNotes": <Array>
[
{
"Id": <GUID>,
"Message": <string>,
"MessageDate": <date>,
"NoteType": <string>
},
....
]
},
....
]
}
Part
Create/Update Part
URI
api/v1/hsqe/parts/CreateOrUpdatePart
Supported Verbs
- POST: insert and update one Part.
Required Parameters
-
Part Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Part Model to be created or updated.
-
Optional Parameters
-
Delete
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: To update and delete an existing part (must provide the part’s Id in Part Model)
-
Example Usage:
api/v1/hsqe/Parts/CreateOrUpdatePart?delete=true
-
-
asRequest
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of creating or updating a Part directly, a Request for those changes will be created.
-
Example Usage:
api/v1/hsqe/Parts/CreateOrUpdatePart?asRequest=true
-
Required Permissions
Needed for asRequest:
- Setup > Request Manager > Request > Parts
Data Model
Part Model
{
"Id": <GUID>,
"PartNumber": <string>,
"CrossReferenceNumber": <string>,
"Description": <string>,
"Info": <string>,
"PartUnit": <string>,
"PartCategory": <string>,
"IsActive": <boolean>,
"IsCriticalSpare": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
"AssetTypeNames": <Array of string>
}
Part Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: Update the uniquely matching Part.
-
-
PartNumber
-
DataType: string [max. 100 char]
-
Required: false
-
Purpose: Sets the part number.
-
-
CrossReferenceNumber
-
DataType: string [max. 100 char]
-
Required: false
-
Purpose: Sets the CrossReferenceNumber for the Part. Will be set to null if not specified.
-
-
Description
-
DataType: string [max. 2000 char]
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Description for the Part.
-
-
Info
-
DataType: string [max. 2000 char]
-
Required: false
-
Purpose: Sets the Additional Information for the Part. Will be set to null if not specified.
-
-
PartUnit
-
DataType: string [max. 200 char]
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the part’s measuring unit. If the unit does not exist, it will create one.
-
-
PartCategory
-
DataType: string [max. 200 char]
-
Required: false
-
Purpose: Sets the part’s category. If the category does not exist, it will create one.
-
-
IsActive
-
DataType: boolean
-
Required: false
-
Purpose: Sets whether the Part is active. Will be set to true if not specified.
-
-
IsCriticalSpare
-
DataType: boolean
-
Required: false
-
Purpose: Sets whether the Part is a critical spare. Will be set to false if not specified.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Part. Will be set to null if not specified.
-
-
AssetTypeNames
-
DataType: Array of string
-
Required: false
-
Purpose: Sets the Part’s compatible asset types. If empty, all asset types are deemed compatible. Must specify an existing asset type.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Insert or Update
-
Id: Guid for the new Part if ActionType is insert. If updating as a request, it will return the Id of the Part with the requested changes.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Find Part
URI
api/v2/public/parts
Supported Verbs
GET
- Find Parts.
Data Models
Part Model
{
"Id": <GUID>,
"Modified": <date>,
"PartNumber": <string>,
"CrossReferenceNumber": <string>,
"Description": <string>,
"Info": <string>,
"IsActive": <boolean>,
"IsCriticalSpare": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"PartUnitType": {
"Id": <GUID>,
"Name": <string>
},
"PartCategory": {
"Id": <GUID>,
"Name": <string>
},
"PartAssetTypes": [
{
"AssetTypeId": <GUID>,
"AssetTypeName": <string>
},
...
],
"IsRequested": <boolean>
}
Part Model Fields
-
Id
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the part’s Id.
-
-
Modified
-
DataType: Date
-
Filterable: True
-
Purpose: specifies when the last time the part was modified. May be null.
-
-
PartNumber
-
DataType: string [max. 100 char]
-
Filterable: True
-
Purpose: specifies the part’s number. May be null.
-
-
CrossReferenceNumber
-
DataType: string [max. 100 char]
-
Filterable: True
-
Purpose: specifies the part’s cross reference number. May be null.
-
-
Description
-
DataType: string [max. 2000 char]
-
Filterable: True
-
Purpose: specifies the part’s description. Never null.
-
-
Info
-
DataType: string [max. 2000 char]
-
Filterable: True
-
Purpose: provides additional information about the part. May be null.
-
-
PartUnitType
-
DataType: PartUnitType Model (see Part Model above).
-
Filterable: True (by Id only)
-
Purpose: identifies the part’s measuring unit. Never null.
-
-
PartCategory
-
DataType: PartCategory Model (see Part Model above).
-
Filterable: True (by Id and Name)
-
Purpose: identifies the part’s category. May be null.
-
-
IsActive
-
DataType: boolean
-
Filterable: True
-
Purpose: indicates if the part is active. True by default.
-
-
IsCriticalSpare
-
DataType: boolean
-
Filterable: True
-
Purpose: indicates if the part is a critical spare. False by default.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Purpose: specifies the part’s user defined fields. May be null.
-
-
AssetTypes
-
DataType: Array of PartAssetType Model (see Part Model above).
-
Purpose: specifies the part’s compatible asset types. If empty, all asset types are deemed compatible.
-
-
IsRequested
-
DataType: boolean
-
Filterable: True
-
Purpose: indicates if the part is currently requested.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Example Usage
// Get a paginated response of all parts
GET api/v2/public/parts
// Get a specific part by Id
GET api/v2/public/parts/1928a52f-cdd7-4e01-8e0d-4a6822f49f3b
// Get parts with the given part category name
GET api/v2/public/parts?$filter=PartCategory/Name eq 'Gasket'
// Get parts with the given part category Id
GET api/v2/public/parts?$filter=PartCategory/Id eq guid'5958a52f-cdd7-4e01-8e0d-7a6822f49f3e'
// Get parts with the given part unit type Id
GET api/v2/public/parts?$filter=PartUnitType/Id eq guid'2a58a520-cfd7-4e41-8e8d-7a6822f49f3f'
// Get all inactive parts
GET api/v2/public/parts?$filter=IsActive eq false
// Get all critical spares
GET api/v2/public/parts?$filter=IsCriticalSpare eq true
// Get all parts modified after the given date
GET api/v2/public/parts?$filter=Modified ge datetime'2020-05-14T20:30:00+00:00'
// Get all parts which are not currently requested
GET api/v2/public/parts?$filter=IsRequested eq false
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/parts?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Required Permissions
- Setup > Parts > Parts
Return Value
Action Accepted
Returns an array containing the requested Parts in the format of the Part Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Part Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Part Contract
Create/Update Part Contract
URI
api/v1/hsqe/parts/CreateOrUpdatePartContract
Supported Verbs
- POST: insert and update one Part Contract. (API User must get response from POST before insert/update another Part Contract)
Required Parameters
-
Part Contract Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Part Contract Model to be created or updated.
-
Optional Parameters
-
Delete
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: To update and delete an existing part contract (must provide the part contract’s Id in Part Contract Model)
-
Example Usage:
api/v1/hsqe/Vendors/CreateOrUpdatePartContract?delete=true
-
Data Model
Part Contract Model
{
"Id": <GUID>,
"VendorId": <GUID>,
"PartId": <GUID>,
"VendorPartNumber": <string> [max. 100 char],
"Price": <decimal>,
"StartDate": <datetime>,
"EndDate": <datetime>,
"Info": <string>
}
Part Contract Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: update the uniquely matching Part Contract.
-
-
VendorId
-
DataType: Guid
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets part contract’s vendor.
-
-
PartId
-
DataType: Guid
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets part contract’s part.
-
-
VendorPartNumber
-
DataType: string [max. 100 char]
-
Required: false
-
Purpose: Sets part contract’s vendor part number.
-
-
Price
-
DataType: decimal (positive, cannot be over 12 character length)
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets part contract’s price.
-
-
StartDate
-
DataType: datetime
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets part contract’s start date (start date and end date’s period cannot overlap another contract’s period).
-
-
EndDate
-
DataType: datetime
-
Required: false
-
Purpose: Sets part contract’s end date(start date and end date’s period cannot overlap another contract’s period).
-
-
Info
-
DataType: string [max. 2000 char]
-
Required: false
-
Purpose: Sets the part contract’s additional information.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Insert or Update
-
Id: Guid for the new Part Contract if ActionType is insert.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Payroll
Find Payroll
URI
api/v1/Personnel/Payroll/FindPayroll
Supported Verbs
- GET: return a filtered list of payroll data. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/Personnel/Payroll/FindPayroll?page=2
-
Optional Parameters
-
PayrollPeriodId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return payroll data from PayrollPeriodId
-
Example Usage:
api/v1/Personnel/Payroll/FindPayroll?page=2&PayrollPeriodId=15D06AF7-4AEA-11E7-80D9-00155D040945
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"PersonId": <GUID>,
"PayrollPeriodId": <GUID>,
"DivisionId": <GUID>,
"Payroll Group": {
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>
},
"TransactionLines":
[
"Id": <GUID>,
"Rate": <decimal>,
"Quantity": <decimal>,
"Factor": <decimal>,
"Amount": <decimal>,
"StartDate": <date>,
"EndDate": <date>,
"AccountingCodes":
{
<string(ReferenceType)>:
{
"Id": <GUID>,
"AccountingCode": <string>,
"EntityName": <string>,
"ReferenceType": <string>
},
....
}
],
"PersonBankRecords":
[
{
"Id": <GUID>,
"Rate": <decimal>,
"Quantity": <decimal>,
"Factor": <decimal>,
"Amount": <decimal>,
"Date": <date>,
"IsWithdrawal": <boolean>,
"AccountingCodes":
{
<string(ReferenceType)>:
{
"Id": <GUID>,
"AccountingCode": <string>,
"EntityName": <string>,
"ReferenceType": <string>
},
....
}
}
]
}
]
}
}
Bank Balance
URI
api/v1/Personnel/Payroll/BankBalance
Supported Verbs
- GET: return a filtered list of person bank balances. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/Personnel/Payroll/BankBalance?page=2&PayrollPeriodId=6bdb2182-5145-11e7-ae3d-b8ca3ad31bab
-
-
PayrollPeriodId:
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: To specify the payroll period for which balances will be returned.
-
Example Usage:
api/v1/Personnel/Payroll/BankBalance?page=2&PayrollPeriodId=6bdb2182-5145-11e7-ae3d-b8ca3ad31bab
-
Optional Parameters
-
PersonId:
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: To specify the person for which balances will be returned. If omitted, all people will be returned. When filtering to a single person consider querying for page 1 as your results will likely be on that page only.
-
Example Usage:
api/v1/Personnel/Payroll/BankBalance?page=1&PayrollPeriodId=6bdb2182-5145-11e7-ae3d-b8ca3ad31bab&PersonId=2bdb2183-5145-15e7-ae3d-b8ca3ad41bac
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>, // No longer used - unique rows should be determined from BankId + PersonId
"BankId": <GUID>,
"BankName": <string>,
"BankAccountingCode": <string>,
"PersonId": <GUID>,
"Balances": <Array>
[
{
"PayrollClassId": <GUID>,
"EarningCodeId": <GUID>,
"AssetId": <GUID>,
"CostCenterId": <GUID>,
"Rate": <decimal>,
"Factor": <decimal>,
"DivisionId": <GUID>,
"OpeningBalance": <decimal>,
"OpeningQuantity": <decimal>,
"ClosingBalance": <decimal>,
"ClosingQuantity": <decimal>
},
...
]
}
]
}
}
Find Payroll Periods
URI
api/v1/Personnel/PayrollPeriods/FindPayrollPeriods
Supported Verbs
- GET: return a filtered list of payroll periods. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/Personnel/PayrollPeriods/FindPayrollPeriods?page=2
-
Optional Parameters
-
Date:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the payroll periods containing this date
-
Example Usage:
api/v1/Personnel/PayrollPeriods/FindPayrollPeriods?page=2&Date=2017-01-01T00:00:00-00:00
-
-
OnlyForExport:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, only payroll periods that are ready for Export, and have an EndDate before tomorrow’s date at midnight, are returned. For example, if the date at the time is 01/01/2018 13:37, tomorrow at midnight would be 02/01/2018 00:00. Ready for Export means only payroll periods where Exported is null and Posted is not null.
-
Example Usage:
api/v1/Personnel/PayrollPeriods/FindPayrollPeriods?page=2&OnlyForExport=true
-
-
NoPayrollGroupOnly:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, only payroll periods that don’t belong to a payroll group are returned.
-
Note: Cannot be used with PayrollGroupName
-
Example Usage:
api/v1/Personnel/PayrollPeriods/FindPayrollPeriods?page=2&NoPayrollGroupOnly=true
-
-
PayrollGroupName:
-
Data Type: string
-
Parameter Type: query string
-
Purpose: To specify the payroll group for which payroll period will be returned.
-
Note: Cannot be used with NoPayrollGroupOnly
-
Example Usage:
api/v1/Personnel/PayrollPeriods/FindPayrollPeriods?page=1&PayrollGroupName=Wheelhouse
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"StartDate": <date>,
"EndDate": <date>,
"PayrollGroup": {
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>
}
}
]
}
}
Set Payroll Period Exported
URI
api/v1/Personnel/PayrollPeriods/SetPayrollPeriodExported
Supported Verbs
- POST: Mark or unmark a payroll periods’s exported date field
Required Parameters
-
PayrollPeriod Export Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies the Id of the target payroll period and the desired ExportDate
-
Data Model
Payroll Class Model
{
"Id": <GUID>,
"ExportDate": <date>,
"ResetExportDate": <boolean>
}
Payroll Class Object Fields
-
Id
-
Data Type: GUID
-
Required: true
-
Purpose: Identify the payroll period to update
-
-
ExportDate
-
Data Type: date
-
Required: false
-
Purpose: Sets the exported date field on the target payroll period
-
-
ResetExportDate
-
Data Type: boolean
-
Required: false
-
Purpose: If true, sets the exported date field on the target payroll period to NULL
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: “Set Exported”, or “Remove Exported”
-
Id: Guid for the target payroll period
-
ErrorMsgs: Fields that have issues
-
Entity: Name of the field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message(s)
Payroll Class
Create/Update Payroll Class
URI
api/v1/Personnel/PayrollClasses/CreateOrUpdatePayrollClass
Supported Verbs
- POST: insert or update a payroll class.
Required Parameters
-
Payroll Class Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Payroll Class Model to be created or updated.
-
Data Model
Payroll Class Model
{
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>,
"DoArchive": <boolean>
}
Payroll Class Object Fields
-
Id
-
DataType: GUID
-
Required: true when updating
-
Purpose: Identify the payroll class to update
-
-
Name
-
DataType: string [max. 200 char]
-
Required: true
-
Purpose: Sets the Name for the payroll class.
-
-
AccountingCode
-
DataType: string [max. 50 char]
-
Required: false
-
Purpose: Sets the AccountingCode for the payroll class.
-
-
DoArchive
-
DataType: boolean
-
Required: false
-
Purpose: Archive the payroll class.
-
Note: This field will be ignored when creating a new payroll class. Once archived, it can’t be reverted. Any payroll class earning codes will also be archived.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Insert or Update
-
Id: Guid for the new payroll class if ActionType is insert.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Create/Update Payroll Class Earning Code
URI
api/v1/Personnel/PayrollClasses/CreateOrUpdatePayrollClassEarningCode
Supported Verbs
- POST: insert or update a payroll class earning code.
Required Parameters
-
Payroll Class Earning Code Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one payroll class Earning Code Model to be created or updated.
-
Data Model
Payroll Class Earning Code Model
{
"Id": <GUID>,
"PayrollClassId": <GUID>,
"QuantityType": <string>,
"EarningCode": {
"Id": <GUID>,
"Name": <string>
},
"Factor": <decimal>,
"Rate": <decimal>,
"AccrualFactor": <decimal>,
"EffectiveDate": <date>,
"DoArchive": <boolean>
}
Payroll Class Earning Code Object Fields
-
Id
-
DataType: GUID
-
Required: true when updating
-
Purpose: Identify the payroll class earning code to update
-
-
PayrollClassId
-
DataType: GUID
-
Required: true
-
Purpose: Sets the PayrollClassId for the payroll class earning code
-
-
QuantityType
-
DataType: string [max. 20 char]
-
Required: false
-
Purpose: Sets the QuantityType for the Earning Code.
-
Accepted Value: “fixed”, “daily”, “hourly”, “amount”
-
-
EarningCode
-
DataType: JSON Object
-
Required: true
-
Purpose: Sets the EarningCodeId for the payroll class earning code.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
-
-
Factor
-
DataType: decimal
-
Required: true
-
Purpose: Sets the Factor for the payroll class earning code.
-
-
Rate
-
DataType: decimal
-
Required: true
-
Purpose: Sets the Rate for the payroll class earning code.
-
-
AccrualFactor
-
DataType: decimal
-
Required: true
-
Purpose: Sets the AccrualFactor for the payroll class earning code.
-
-
EffectiveDate
-
DataType: date
-
Required: true
-
Purpose: Sets the EffectiveDate for the payroll class earning code.
-
-
DoArchive
-
DataType: boolean
-
Required: false
-
Purpose: Archive the payroll class earning code.
-
Note: This field will be ignored when creating a new payroll class earning code. Once archived, it can’t be reverted.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Insert or Update
-
Id: Guid for the new payroll class if ActionType is insert.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Find Payroll Class
URI
api/v1/Personnel/PayrollClasses/FindPayrollClasses
Supported Verbs
- GET: return a filtered list of payroll classes and its earning codes. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/Personnel/PayrollClasses/FindPayrollClasses?page=2
-
Optional Parameters
-
Name:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return payroll class with Name containing the string
-
Example Usage:
api/v1/Personnel/PayrollClasses/FindPayrollClasses?page=2&Name=Foo
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>,
"EarningCodes" [
{
"Id": <GUID>,
"PayrollClassId": <GUID>,
"QuantityType": <string>,
"EarningCode": {
"Id": <GUID>,
"Name": <string>
},
"Factor": <decimal>,
"Rate": <decimal>,
"AccrualFactor": <decimal>,
"EffectiveDate": <date>
}, ...
]
},
...
]
}
}
Positions
URI
api/v2/public/positions
Supported Verbs
GET
- Find Positions.
Data Models
Position Model
{
"Id": <GUID>,
"Name": <string>
}
Position Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a position.
-
-
Name
-
DataType: string [max. 400 char]
-
Filterable: true
-
Purpose: Specifies the name of a position.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Positions
URI
GET api/v2/public/positions
Example Usage
GET api/v2/public/positions
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/positions?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Positions with Name equal to "Captain" GET api/v2/public/positions?$filter=Name eq 'Captain'
-
Return Value
Action Accepted
Returns an array containing the requested Positions in the format of the Positions Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Position Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
Either one of:
- Setup > People > Positions > Read
- Setup > People > Positions > Edit
Requests
URI
api/v2/public/requests
Supported Verbs
-
GET
:- Get Requests.
-
PATCH
:- Accept or Deny Requests. Note that Only Parent Requests can be accepted or denied. If a new request is created to update an object and there is already an existing request, the old request will be closed as Denied.
- One possible use case for this endpoint is to create an order using the CreateOrder endpoint, save the orderId, lookup the requestId using this endpoint
api/v2/public/requests$filter=RequestEntityId = guid'<guid>' and State eq 'Pending'
. The request can then be accepted by patching {“State”: “Accepted”}.
Data Models
Request Model
{
"Id": <GUID>,
"Type": <string>,
"State": <string>,
"RequestedDate": <date>,
"Modified": <date>,
"RequestedByUserId": <GUID>,
"RequestEntityId": <GUID>,
"OriginalId", <GUID>,
"ParentId", <GUID>,
"ChangeJson": <Json>
}
Request Fields
-
Id
-
DataType: Guid
-
Required: False when getting. True when using Patch to update (unless Id is already specified in the URI).
-
Purpose: To uniquely identify a Request
-
-
State
-
DataType: string
-
Required: True when patching, False when getting
-
Filterable: True
-
Purpose: Identify the State of the Request.
-
Note:
-
State can be one of the follow values and is case sensitive:
-
“Pending”
-
“Accepted”
-
“Denied”
-
-
Example Usage:
GET api/v2/public/requests?$filter=State eq 'Pending'
-
-
Type
-
DataType: string
-
Required: false
-
Filterable: true
-
Purpose: Identify the type of Request.
-
Note: Type can be one of the follow values:
-
“Ship”
-
“Location”
-
“Account”
-
“Order”
-
“Trip”
-
“Job”
-
“Part”
-
-
Example Usage:
GET api/v2/public/requests?$filter=Type eq 'Ship'
-
-
RequestedDate
-
DataType: date
-
Required: false
-
Filterable: true
-
Purpose: Shows when a request was created.
-
-
Modified
-
DataType: date
-
Required: false
-
Filterable: true
-
Purpose: Shows when request was last updated.
-
-
RequestedByUserId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Identify the user who requested the changes.
-
-
RequestEntityId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Identify the Id for the Request object.
-
-
OriginalId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: For update requests, this is the Id of the original object. Null for Create requests
-
-
ParentId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: For requests which have a parent. E.g. A request is made using the CreateOrder endpoint which includes multiple trips. The trips would have their Parent set to the Order’s request.
-
-
ChangeJson
-
DataType: Json
-
Required: false
-
Purpose: Identify the changes in the request.
-
Note: ChangeJson is a Json object of all the changes in a request. It will only contain the fields which are being changed for update Requests. The model here is different to the other models in that it will only contain the Ids for related objects instead of a nested Json Object. These will also have Id at the end of their name. Also note that some of the fields may be named differently from other models. Note that certain fields are named differently as well. Below is a list with the new name as well as type:
-
For Order:
- Area -> AreaId (Location)
- Division -> DivisionId (Division)
- Ship: Cannot be found on this endpoint, must be queried from FindOrders endpoint instead
- CustomerAccount -> CustomerAccountId (Account)
- AgentAccount -> AgentAccountId (Account)
- AwardedToAccount -> AwardedToAccountId (Account)
- UserDefined -> Cannot be found on this endpoint, must be queried from FindOrders endpoint instead
-
For Trip:
- Order -> OrderId
- TripType -> TripTypeId (Trip Type)
- FromLocation -> FromLocationId (Location)
- ToLocation -> ToLocationId (Location)
- EstimatedDuration -> Duration
- CancelledDate -> Cancelled
- NumberRequiredResource -> Cannot be found on this endpoint
- UserDefined -> Cannot be found on this endpoint, must be queried from FindTrips endpoint instead
-
For Job:
- Trip -> TripId (Trip)
- RequiredResourceType -> RequiredResourceTypeId (RequiredResourceType)
- Resource -> ResourceId (Resource)
- Acknowledged -> IsNotified
- UserDefined -> Cannot be found on this endpoint, must be queried from FindJobs endpoint instead
-
For Ship:
- MMSI -> OfficialNumber
- IMONumber -> LRIMOShipNo
- ShipType -> ShipTypeId
- GT -> GrossTonnage
- NT -> NetTonnage
- LOA -> Length
- TEU -> TwentyFootEquivalentUnit
- UserDefined -> Cannot be found on this endpoint, must be queried from FindShips endpoint instead
-
For Location:
- IsRequested -> Cannot be found on this endpoint. Use Requests instead
- UserDefined -> Cannot be found on this endpoint, must be queried from locations endpoint instead
-
For Account:
- Company -> CompanyId (Company)
- Division -> DivisionId (DivisionId)
- IsActive -> Active Note: this field is a datetime instead.
-
Find Requests
URI
GET api/v2/public/requests
or
GET api/v2/public/requests/{Id}
Example usage
// Get a paginated response of all requests
GET api/v2/public/requests
// Get a specific request by Id
GET api/v2/public/requests/<guid>
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/requests?page=2
-
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Pending Requests GET api/v2/public/requests?$filter=State eq 'Pending'
-
Accept/Deny Requests
URI
PATCH api/v2/public/requests
or
PATCH api/v2/public/requests/{Id}
Example Usage
// Accept a request
PATCH api/v2/public/requests
{ "State": "Accepted" }
Required Parameters
-
Data Type: JSON object
-
Parameter Type: request body
-
Purpose: Specifies the State to Patch
-
Note: Id must be specified either in the body or in the url.
Requisition
Update Requisition
URI
api/v1/hsqe/Requisitions/UpdateRequisition
Supported Verbs
- POST: update a requisition.
Required Parameters
-
Requisition Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Requisition Model to be updated.
-
Optional Parameters
-
UpdateInventory
-
Data Type: Boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, if the requisition is set to ‘Received On Asset’, It will update the inventory count (If tenant and user have permission to inventory app).
-
Example Usage:
api/v1/hsqe/Requisitions/UpdateRequisition?UpdateInventory=true
-
Data Model
Requisition Model
{
"Id": <GUID>,
"Name": <string> [max. 100 char],
"Status": <string> ["New", "Confirmed", "Ordered", "Received On Shore", "Received On Asset", "Closed", "Canceled"],
"DueDate": <datetime>,
"Priority": <string> ["Low", "Medium", "High"],
"LinkedItemType": <string> ["Inspection", "Maintenance", "Inventory", "Form", "Task", "Corrective Action"],
"LinkedItemId": <GUID>,
"UserDefined": User Defined Data Model (see [User Defined Fields](#UDF) section for more details)
}
Requisition Object Fields
-
Id
-
DataType: Guid
-
Required: true
-
Purpose: Update the uniquely matching Requisition.
-
-
Name
-
DataType: string [max. 100 char]
-
Required: false
-
Purpose: Sets the Name for the Requisition.
-
-
Status
-
DataType: string [“New”, “Confirmed”, “Ordered”, “Received On Shore”, “Received On Asset”, “Closed”, “Canceled”],
-
Required: false
-
Purpose: Sets all the Line Item within the requisition to one of the status specified.
-
Note: Line Item status will not change if the status is already one of the following: ‘Received On Asset’, ‘Closed’, ‘Canceled’ or ‘Deleted’
-
-
DueDate
-
DataType: datetime
-
Required: false
-
Purpose: Sets the due date for the Requisition.
-
-
Priority
-
DataType: string [“Low”, “Medium”, “High”],
-
Required: false
-
Purpose: Sets the priority for the Requisition.
-
-
LinkedItemType
-
DataType: string [“Inspection”, “Maintenance”, “Inventory”, “Form”, “Task”, “Corrective Action”],
-
Required: false
-
Purpose: Sets the linked item type for the Requisition.
-
Note: If the LinkedItemType is set, then user must provide LinkedItemId and vice versa.
-
-
LinkedItemId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the linked item Id for the Requisition.
-
Note: If the LinkedItemId is set, then user must provide LinkedItemType and vice versa.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Requisition. Will keep the old value if not specified.
-
Return Value
Action Accepted
"Data":
{
"ActionType": <string>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Update
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Update Line Item
URI
api/v1/hsqe/Requisitions/UpdateLineItem
Supported Verbs
- POST: update a single Line Item.
Required Parameters
-
Line Item Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Line Item Model to be updated.
-
Optional Parameters
-
UpdateInventory
-
Data Type: Boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, if the Line Item is set to ‘Received On Asset’, It will update the inventory count (If tenant and user have permission to inventory app).
-
Example Usage:
api/v1/hsqe/Requisitions/UpdateLineItem?UpdateInventory=true
-
Data Model
Line Item Model
{
"Id": <GUID>,
"PartId": <GUID>,
"VesselComponentId": <GUID>,
"Description": <string> [max. 100 char],
"Quantity": <integer> or <decimal>
"EstPrice": <decimal>,
"VendorId": <GUID>,
"Status": <string> ["New", "Confirmed", "Ordered", "Received On Shore", "Received On Asset", "Closed", "Canceled"],
"Type": <string> ["Labor", "Part"],
"UserDefined": User Defined Data Model (see [User Defined Fields](#UDF) section for more details)
}
Line Item Object Fields
-
Id
-
DataType: Guid
-
Required: true
-
Purpose: Update the uniquely matching Line Item.
-
-
PartId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the part id for the Line Item.
-
-
VesselComponentId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the associated vessel component id for the line item.
-
Note: the vessel component should be on the Requisition’s asset.
-
-
Description
-
DataType: string [max. 100 char]
-
Required: false
-
Purpose: Sets the Description for the Line Item.
-
-
Quantity
-
DataType: integer or decimal (See notes),
-
Required: false
-
Purpose: Sets the quantity for the Line Item.
-
Note: If the Line Item type is labor, then the quantity can be decimal, otherwise the quantity have to be integer only.
-
-
EstPrice
-
DataType: decimal
-
Required: false
-
Purpose: Sets the estimated price for the Line Item.
-
-
VendorId
-
DataType: Guid,
-
Required: false
-
Purpose: Sets the vendor id for the Line Item.
-
-
Status
-
DataType: string [“New”, “Confirmed”, “Ordered”, “Received On Shore”, “Received On Asset”, “Closed”, “Canceled”],
-
Required: false
-
Purpose: Sets the Line Item to one of the statuses specified.
-
Note: Line Item status cannot be changed if the status is already one of the following: ‘Received On Asset’, ‘Closed’, ‘Canceled’ or ‘Deleted’
-
-
Type
-
DataType: string [“Labor”, “Part”]
-
Required: false
-
Purpose: Sets the type for the Line Item.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Line Item. Will keep the old value if not specified.
Return Value
Action Accepted
"Data":
{
"ActionType": <string>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Update
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Find Requisitions
URI
api/v1/hsqe/Requisitions/FindRequisitions
Supported Verbs
- GET: return a filtered list of in progress requisitions (unless user find requistion by Id). the data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/hsqe/Requisitions/FindRequisitions?page=2
-
Optional Parameters
-
SearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Requisition with Name containing the string.
-
Example Usage:
api/v1/hsqe/Requisitions/FindRequisitions?page=2&SearchString=Foo
-
-
ExternalNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Requisition with External Number equals to the string.
-
Example Usage:
api/v1/hsqe/Requisitions/FindRequisitions?page=2&ExternalNumber=FX-1000
-
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Requisition with Id equals to the Guid.
-
Note: If Id is set, then the endpoint will ignore other optional parameters.
-
Example Usage:
api/v1/hsqe/Requisitions/FindRequisitions?page=2&Id=00000000-0000-0000-0000-000000000000
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Created": <datetime>,
"DueDate": <datetime>,
"Name": <string>,
"Space": <string>,
"Priority": <string>,
"ExternalNumber": <string>,
"LineItemCount": <integer>,
"Status": <string>,
"DivisionId": <GUID>,
"CreatedById": <GUID>,
"CreatedBy" : {
"FirstName": <string>,
"MiddleName": <string>,
"LastName": <string>
},
"Asset": <string>,
"EstCost": <decimal>,
"LinkedItemType": <string>,
"LinkedItemId": <GUID>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
},
...
]
}
}
Find Line Items
URI
api/v1/hsqe/Requisitions/FindLineItems
Supported Verbs
- GET: return a filtered list of in progress Line Items (unless user find line item by Id). the data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=2
-
Optional Parameters
-
SearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Line Item with description containing the string.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=2&SearchString=Foo
-
-
ExternalNumber:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Requisition with External Number equals to the string.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=2&ExternalNumber=FX-1000
-
-
Status:
-
Data Type: string [“New”, “Confirmed”, “Ordered”, “ReceivedOnShore”, “AwaitingApproval”, “Closed”, “Canceled”, “ReceivedOnAsset”]
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Line Item with status equal to the string.
-
Note: Only in progress statuses will return results.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=1&status=ReceivedOnShore
-
-
AssetId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Line Items whose requisitions are associated with given assetId.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=2&assetId=00000000-0000-0000-0000-000000000000
-
-
RequisitionId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Line Item with RequisitionId equals to the Guid.
-
Note: If RequisitionId is set, then the endpoint will ignore above optional parameters.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=2&RequisitionId=00000000-0000-0000-0000-000000000000
-
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Line Item with Id equals to the Guid.
-
Note: If Id is set, then the endpoint will ignore above optional parameters.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=2&Id=00000000-0000-0000-0000-000000000000
-
-
IncludeResolved:
-
Data Type: Boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: If true, will return in progress line item and also line items whose status is one of Closed, Canceled, or Received On Asset; otherwise, just return in progress line items.
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=1&IncludeResolved=true
-
-
FromDate:
-
Data Type: Date
-
Parameter Type: query string
-
Default Value: When IncludeResolved is true, will default to ToDate - 366 days (or Now - 366 days if ToDate is blank). Otherwise, will default to null.
-
Purpose: When not null, will return LineItems where the ModifiedDate is >= FromDate
-
Example Usage:
api/v1/hsqe/Requisitions/FindLineItems?page=1&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: Date
-
Parameter Type: query string
-
Default Value: When IncludeResolved is true, will default to FromDate + 366 days (or Now if FromDate is blank). Otherwise, will default to null.
-
Purpose: When not null, will return LineItems where the ModifiedDate is <= ToDate.
-
Example Usage
api/v1/hsqe/Requisitions/FindLineItems?page=1&ToDate=2016-03-10T14:23:00-08:00
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Created": <datetime>,
"Description": <string>,
"ExternalNumber": <string>,
"RequisitionId": <GUID>,
"Space": <string>,
"DueDate": <datetime>,
"Priority": <string>,
"VendorName": <string>,
"Quantity": <decimal>,
"EstPrice": <decimal>,
"PartId": <GUID>,
"PartDescription": <string>,
"PartNumber": <string>,
"PartUnit": <string>,
"PartCategory": <string>,
"Status": <string>,
"Type": <string>,
"Asset": <string>,
"CreatedById": <GUID>,
"CreatedBy" : {
"FirstName": <string>,
"MiddleName": <string>,
"LastName": <string>
},
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
},
...
]
}
}
Resources
URI
api/v2/public/resources
Supported Verbs
-
GET
- Find Resources. Assets will also be found as Resources.
-
POST
- Create new Resources. Does not create Assets.
- Add Operating Areas to existing Resources and Assets.
-
PATCH
- Update existing Resources and Assets.
-
DELETE
- Remove Operating Areas from existing Resources and Assets.
Data Models
Resource Model
{
"Id": <GUID>,
"Modified": <datetime>,
"Name": <string>,
"ShortName": <string>,
"ExternalSystemCode": <string>,
"AccountingCode": <string>,
"ResourceType": {
"Id": <GUID>,
"Name": <string>
},
"Division": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"OperatingAreas": <Array>
[
{
"Id": <GUID>,
"Name": <string>
},
...
],
"Owner": {
"Id": <GUID>,
"Name": <string>
},
"Ship": {
"Id": <GUID>,
"Name": <string>,
"IMONumber": <string>
},
"IMONumber": <string>,
"MMSI": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Resource Fields
-
Id
-
DataType: Guid
-
Required: False when using POST to create, True when using PATCH to update (unless Id is already specified in the URI).
-
Purpose: To uniquely identify a Resource and to specify which Resource to apply an operation to.
-
-
Modified
-
DataType: datetime
-
Required: False
-
Purpose: The latest modified date of this resource
-
Filterable: True
-
-
Name
-
DataType: string [max. 200 char]
-
Required: True when using POST to create, False when using PATCH to update.
-
Filterable: True
-
Purpose: Specifies the name of a Resource.
-
-
ShortName
-
DataType: string [max. 100 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies a shortened name for a Resource.
-
-
ExternalSystemCode
-
DataType: string [max. 200 char]
-
Required: False
-
Filterable: True
-
-
AccountingCode
-
DataType: string [max. 50 char]
-
Required: False
-
Filterable: True
-
-
ResourceType
-
DataType: object
-
Required: False
-
Purpose: Defines the Resource Type of the Resource.
-
Filterable: True
-
Fields:
- Id:
<Guid>
: required - Name:
<string>
: read-only
- Id:
-
-
Division
-
DataType: object
-
Required: True when using POST to create, False when using PATCH to update.
-
Purpose: Defines the Division of the Resource.
-
Filterable: True
-
Fields:
- Id:
<Guid>
: required - Name:
<string>
: read-only - ExternalSystemCode:
<string>
: read-only
- Id:
-
-
OperatingArea
-
DataType: Array
-
Required: False
-
Purpose: Defines the Operating Areas for this Resource. Operating Areas are Locations with
IsArea=true
. Operating Areas must not be redundant (for example, an Operating Area that is the root of the locations tree can not be specified at the same time as a location that is a child of that location). -
Filterable: True
-
Fields:
- Id
<GUID>
: required for each Location - Name
<string>
: read-only
- Id
-
-
Owner
-
DataType: object
-
Required: False
-
Purpose: Defines the Owner of the Resource, where Owner is a Company.
-
Filterable: True
-
Fields:
- Id:
<Guid>
: required - Name:
<string>
: read-only
- Id:
-
-
Ship
-
DataType: object
-
Required: False
-
Purpose: Defines the Ship this Resource is associated with.
-
Filterable: True
-
Fields:
- Id:
<Guid>
: required - Name:
<string>
: read-only - IMONumber:
<string>
: read-only
- Id:
-
-
IMONumber
-
DataType: string [max. 100 char]
-
Required: False
-
Purpose: The IMO Number of this resource
-
Filterable: True
-
-
MMSI
-
DataType: string [max. 100 char]
-
Required: False
-
Purpose: The MMSI of this resource
-
Filterable: True
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: False
-
Purpose: Sets the UserDefined for the Resource. Will be set to null if not specified. It is not currently possible to update this field on assets from this endpoint, use the Update Asset endpoint instead.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Resources
URI
GET api/v2/public/resources
or
GET api/v2/public/resources/{Id}
Example Usage
// Get a paginated response of all resources
GET api/v2/public/resources
// Get a specific resource by Id
GET api/v2/public/resources/d21d73fb-bb69-11e8-8102-00155d040945
// Get resources that have been modified since a certain Datetime
GET api/v2/public/resources?$filter=Modified gt datetime'2019-09-05T15:55:24'
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/resources?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Resources with Name equal to "Boat" GET api/v2/public/resources?$filter=Name eq 'Boat' // Get Resources with ShortName equal to "MVQ" GET api/v2/public/resources?$filter=ShortName eq 'MVQ' // Get Resources with Division Name equal to "Helm Operations" GET api/v2/public/resources?$filter=Division/Name eq 'Helm Operations' // Get Resources with OperatingAreas which contain OperatingArea Name equal to "Victoria" GET api/v2/public/resources?$filter=OperatingAreas/any(p:p/Name eq 'Victoria') // Get Resources with ResourceType Name equal to "ASD" GET api/v2/public/resources?$filter=ResourceType/Name eq 'ASD' // Get Resources with ship id equal to "c95a4e7f-67f8-11ec-b9aa-144f8a6a31b3" GET api/v2/public/resources?$filter=Ship/Id eq guid'c95a4e7f-67f8-11ec-b9aa-144f8a6a31b3' // Get Resources with ship IMO number equal to "9321483" GET api/v2/public/resources?$filter=Ship/IMONumber eq '9321483'
-
Required Permissions
One or both of the following:
- Setup > Jobs > Ships > Resources > Read
- Setup > Jobs > Ships > Resources > Edit
Return Value
Action Accepted
Returns an array containing the requested Resources in the format of the Resource Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Resource Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Create Resources
URI
POST api/v2/public/resources
Example Usage
// Create one Resource with two operating areas
POST api/v2/public/resources
{
"Name": "Tug One",
"Division": {
"Id": "8a4cf888-5b12-11e9-9d21-6c8814184910"
},
"OperatingAreas": [
{
"Id": "1edfb9d4-5b12-11e9-9d21-6c8814184910"
},
{
"Id": "7593fd18-5f9c-11e9-9d22-f01faf02f2e9"
}
]
}
Required Parameters
-
Data Type: Resource Model or Array of Resource Model
-
Parameter Type: request body
-
Purpose: Supplies the Resource(s) to be created.
Required Permissions
- Setup > Jobs > Ships > Resources > Edit
Return Value
Action Accepted
Returns an array containing the created Resources.
<Array of Resource Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Update Resources
URIs
Update a Resource
PATCH api/v2/public/resources/
or
PATCH api/v2/public/resources/{Id}
Add an Operating Area to a Resource
POST api/v2/public/resources/{Id}/operatingareas
Remove an Operating Area from a Resource
DELETE api/v2/public/resources/{Id}/operatingareas/{OperatingAreaId}
Required Parameters
-
Id
:-
Data Type: Guid
-
Parameter Type: request path or request body
-
Purpose: To specify which Resource to apply an operation to.
-
Example Usage:
// Update a Resource Name by providing the Id in the request path PATCH api/v2/public/resources/c5e69784-24c5-11e7-82c5-f01faf32a6aa { "Name": "USS Enterprise" } // Update the Name of multiple Resources by providing the Id in the request body PATCH api/v2/public/locations [ { "Id": "c5e69784-24c5-11e7-82c5-f01faf32a6aa", "Name": "Excelsior" }, { "Id": "d21d73fb-bb69-11e8-8102-00155d040945", "Name": "Voyager" } ] // Remove the Owner from a Resource PATCH api/v2/public/resources/c5e69784-24c5-11e7-82c5-f01faf32a6aa { "Owner": null } // Add an Operating Area to an existing Resource POST api/v2/public/resources/c5e69784-24c5-11e7-82c5-f01faf32a6aa/operatingareas { "Id": "c5e69784-24c5-11e7-82c5-f01faf32a6aa" }
-
Optional Parameters
-
OperatingAreaId
:-
Data Type: Guid
-
Parameter Type: request path
-
Purpose: To specify which Resource Operating Area to apply an operation to.
-
Example Usage:
// To remove an Operating Area (with Id of 7694520e-b2de-4dbe-9d6d-fbf8addd8a28) from a Resource DELETE api/v2/public/resources/c5e69784-24c5-11e7-82c5-f01faf32a6aa/operatingareas/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
-
Required Permissions
- Setup > Jobs > Ships > Resources > Edit
Return Value
Action Accepted
Returns an array containing the modified Resources.
<Array of Resource Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Resource Type
URI
api/v2/public/resourcetypes
Supported Verbs
GET
- Find Resource Types.
Data Models
Resource Type Model
{
"Id": <GUID>,
"Name": <string>,
"Parent": {
"Id": <GUID>,
"Name": <string>
}
}
Resource Type Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a resource type.
-
-
Name
-
DataType: string [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of a resource type.
-
-
Parent
-
DataType: object
-
Required: false
-
Purpose: Specifies the parent resource type for this resource type. Null if this resource type has no parent.
-
Fields:
- Id
<GUID>
- Name
<string>
- Id
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Resource Types
URI
GET api/v2/public/resourcetypes
Example Usage
GET api/v2/public/resourcetypes
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/resourcetypes?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Resource Types with Name equal to "Battleship" GET api/v2/public/resourcetypes?$filter=Name eq 'Battleship'
-
Return Value
Action Accepted
Returns an array containing the requested Resource Types in the format of the Resource Types Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Resource Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
Either one of:
- Setup > Jobs > Ships > Resources > Read
- Setup > Jobs > Ships > Resources > Edit
Ship
Create/Update Ship
URI
api/v1/jobs/ships/CreateOrUpdateShip
Supported Verbs
- POST: insert or update a ship.
Required Parameters
-
Ship Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one or more Ship Model to be created or updated.
-
-
matchingField
-
Data Type: String
-
Required: true
-
Data Type: query string
-
Accepted Value: “imo”, “mmsi”, “name”, “callsign”
-
Purpose: matching field will be used to potentially identify the ship to update
-
Example Usage:
api/v1/jobs/ships/CreateOrUpdateShip?matchingField=mmsi
-
Optional Parameters
-
asRequest
-
Data Type: Boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, instead of creating or updating a Ship directly, a Request for those changes will be created.
-
Example Usage:
api/v1/jobs/ships/CreateOrUpdateShip?matchingField=MMSI&asRequest=true
-
Data Model
Ship Model
{
"Name": <string>,
"MMSI": <string>,
"IMONumber": <string>,
"CallSign": <string>,
"Nation": <string>,
"Blocked": <boolean>,
"ShipType": <string>,
"ShipTypeId": <GUID>,
"Beam": <decimal>,
"Deadweight": <decimal>,
"GT": <decimal>,
"Height": <decimal>,
"NT": <decimal>,
"LOA": <decimal>,
"TEU": <decimal>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Ship Object Fields
-
Name
-
DataType: string [max. 150 char]
-
Required: true
-
Purpose: Sets the Name for the Ship.
-
-
MMSI
-
DataType: string [max. 50 char]
-
Required: see Note
-
Purpose: Sets the MMSI for the Ship.
-
-
IMONumber
-
DataType: string [max. 100 char]
-
Required: see Note
-
Purpose: Sets the IMONumber for the Ship.
-
-
CallSign
-
DataType: string [max. 50 char]
-
Required: see Note
-
Purpose: Sets the CallSign for the Ship.
-
-
Nation
-
DataType: string [max. 50 char]
-
Required: false
-
Purpose: Sets the Nation for the Ship.
-
-
Blocked
-
DataType: boolean
-
Required: false
-
Purpose: Sets the Blocked status of the Ship.
-
-
ShipType
-
DataType: string [max. 200 char]
-
Required: false
-
Purpose: Sets the ShipType for the Ship.
-
Note: If the ShipType doesn’t exist in Helm CONNECT, it will be treated as null and won’t update the existing ShipType.
-
-
ShipTypeId
-
DataType:
-
Required: false
-
Purpose: Sets the ShipType for the Ship.
-
Note: If the ShipTypeId doesn’t exist in Helm CONNECT, it will be treated as null and won’t update the existing ShipType. If ShipTypeId and ShipType don’t match, an error will be returned
-
-
Beam
-
DataType: decimal
-
Required: false
-
Purpose: Sets the Beam for the Ship.
-
-
Deadweight
-
DataType: decimal
-
Required: false
-
Purpose: Sets the Deadweight for the Ship.
-
-
Height
-
DataType: decimal
-
Required: false
-
Purpose: Sets the Height for the Ship.
-
-
GT
-
DataType: decimal
-
Required: false
-
Purpose: Sets the GT for the Ship.
-
-
NT
-
DataType: decimal
-
Required: false
-
Purpose: Sets the NT for the Ship.
-
-
TEU
-
DataType: decimal
-
Required: false
-
Purpose: Sets the TEU for the Ship.
-
-
LOA
-
DataType: decimal
-
Required: false
-
Purpose: Sets the LOA for the Ship.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the Ship.
-
Return Value
Action Accepted
"Data":
{
"ShipId": <GUID>,
"ActionType": <string>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
....
]
}
-
ShipId: The new or existing ship’s ID.
-
ActionType: Insert or Update.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
-
Details: Additional information about the error.
Action Rejected
"Data": <Array>
- Data: Error Message
Note: ImoNumber, MMSI, CallSign are not required fields when updating. However, one of them needs to be present when inserting.
Find Ships
URI
api/v1/jobs/ships/FindShips
Supported Verbs
- GET: return a filtered list of Ships. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/ships/FindShips?page=2
-
Optional Parameters
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Ship with given Id
-
Example Usage:
api/v1/jobs/ships/FindShips?page=1&Id=530e6fbb-d304-477a-9a2c-c0d0810f38ff
-
-
IMO:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Ships with given IMO
-
Example Usage:
api/v1/jobs/ships/FindShips?page=1&IMO=1234567
-
-
MMSI:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Ships with given MMSI
-
Example Usage:
api/v1/jobs/ships/FindShips?page=1&MMSI=123456789
-
-
Name:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Ships with given name
-
Example Usage:
api/v1/jobs/ships/FindShips?page=1&Name=ShippyMcShip
-
-
includeRequests:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, requested Ships will also be returned
-
Example Usage
api/v1/jobs/ships/FindShips?page=1&includeRequests=true
-
-
excludeNonRequests:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When true, only requested Ships will be returned
-
Example Usage
api/v1/jobs/ships/FindShips?page=1&includeRequests=true&excludeNonRequests=true
-
-
ChangedSince:
-
Data Type: datetime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return ships that have been modified or created since the datetime.
-
Example Usage
api/v1/jobs/ships/FindShips?page=1&ChangedSince=2016-03-10T14:23:00-08:00
-
-
ShipTypeId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the Ships with given ShipTypeId
-
Example Usage:
api/v1/jobs/ships/FindShips?page=1&ShipTypeId=841ac379-6581-11ea-b618-f01faf08e374
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"MMSI": <string>,
"IMONumber": <string>,
"CallSign": <string>,
"Nation": <string>,
"Blocked": <boolean>,
"ShipType": <string>,
"ShipTypeId": <GUID>,
"Beam": <decimal>,
"Deadweight": <decimal>,
"GT": <decimal>,
"Height": <decimal>,
"NT": <decimal>,
"LOA": <decimal>,
"TEU": <decimal>,
"IsRequest": <boolean>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
....
]
}
Ship Types
URI
api/v2/public/ShipTypes
Supported Verbs
-
GET: Return a filtered list of ShipTypes. The data is returned by page (see below).
-
POST: Insert ShipTypes
-
PATCH: Update existing ShipTypes
Data Models
Ship Type Model
{
"Id": <GUID>,
"Name": <string>,
"AccountingCode": <string>,
"CargoTypeId": <GUID>,
"ParentId": <GUID>,
"Parent":
{
"Id": <GUID>,
"Name": <string>
}
}
Ship Type Fields
-
Id
-
DataType: Guid
-
Required: False when using POST to create, True when using PATCH to update (unless Id is already specified in the URI).
-
Filterable: true
-
Purpose: To uniquely identify a ship type.
-
-
Name
-
DataType: string [max. 400 char]
-
Required: True when using POST to create, False when using PATCH to update.
-
Filterable: true
-
Purpose: Specifies the name of a ship type.
-
-
AccountingCode
-
DataType: string
-
Required: False
-
Filterable: true
-
Purpose: Specifies the accounting code of a ship type.
-
-
CargoTypeId
-
DataType: Guid
-
Required: False
-
Filterable: true
-
Purpose: To uniquely identify a ship type.
-
-
ParentId
-
DataType: Guid
-
Required: False
-
Filterable: true
-
Purpose: To define a parent Id for this ship type.
-
-
Parent
-
DataType: JSON Object (See Data Model for details)
-
Required: False
-
Purpose: To define a parent for this ship type.
-
Fields:
- Id
<GUID>
- Name
<string>
- Id
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Ship Type
URI
GET api/v2/public/shiptypes
or
GET api/v2/public/shiptypes/{Id}
Example Usage
// Get a paginated response of all shiptypes
GET api/v2/public/shiptypes
// Get a specific ship type by Id
GET api/v2/public/shiptypes/69f3ede3-5803-11ea-b615-f01faf08e374
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/shiptypes?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get shiptypes with Name equal to "Cargo" GET api/v2/public/shiptypes?$filter=Name eq 'Cargo'
-
Required Permissions
- Setup > Jobs > Ships > Read
Return Value
Action Accepted
Returns an array containing the requested Ship Type in the format of the ShipType Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of ShipType Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Create Ship Type
URI
POST api/v2/public/shiptypes
Example Usage
// Create one ShipType with a Name and a Parent
POST api/v2/public/shiptypes
{
"Name": "Ship One",
"ParentId": "69f3ede3-5803-11ea-b615-f01faf08e374"
}
Required Parameters
-
Data Type: ShipType Model or Array of ShipType Model
-
Parameter Type: request body
-
Purpose: Supplies the ShipType(s) to be created.
Required Permissions
- Setup > Jobs > Ships > Edit
Return Value
Action Accepted
Returns an array containing the created ShipType.
<Array of ShipType Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Update Ship Type
URIs
Update a ShipType
PATCH api/v2/public/shiptypes/
or
PATCH api/v2/public/shiptypes/{Id}
Required Parameters
-
Id
:-
Data Type: Guid
-
Parameter Type: request path or request body
-
Purpose: To specify which ShipType to apply an operation to.
-
Example Usage:
// Update a ShipType Name by providing the Id in the request path PATCH api/v2/public/shiptypes/c5e69784-24c5-11e7-82c5-f01faf32a6aa { "Name": "Ship Two" } // Update the Name of multiple shiptypes by providing the Id in the request body PATCH api/v2/public/shiptypes [ { "Id": "c5e69784-24c5-11e7-82c5-f01faf32a6aa", "Name": "BattleShip" }, { "Id": "d21d73fb-bb69-11e8-8102-00155d040945", "Name": "Passenger" } ] // Remove the Parent from a ShipType PATCH api/v2/public/shiptypes/c5e69784-24c5-11e7-82c5-f01faf32a6aa { "ParentId": null }
-
Required Permissions
- Setup > Jobs > Ships > Edit
Return Value
Action Accepted
Returns an array containing the modified ShipType.
<Array of ShipType Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Tariff
URI
api/v2/public/tariffs
Supported Verbs
GET
- Find Tariffs.
Data Models
Tariff Model
{
"Id": <GUID>,
"Name": <string>,
"DivisionId": <GUID>,
"Division":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"AreaId": <GUID>,
"Area":
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
}
}
Tariff Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify a tariff.
-
-
Name
-
DataType: string [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of a tariff.
-
-
DivisionId
-
DataType: Guid
-
Required: true
-
Filterable: true
-
Purpose: To specify which Location Division to apply a tariff to.
-
-
Division
-
DataType: JSON Object
-
Purpose: Defines the Division of a tariff
-
Function: Selects the Division that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
-
AreaId
-
DataType: Guid
-
Filterable: true
-
Purpose: To specify which Area to apply a tariff to.
-
-
Area
-
DataType: JSON Object
-
Purpose: Defines the Area of a tariff
-
Function: Selects the Area that uniquely matches one or more of the given fields.
-
Fields:
-
Id
<GUID>
-
Name
<string>
-
ExternalSystemCode
<string>
-
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Required Permissions
- Jobs > Tariffs > Read
Tasks
Create/Update Task
URI
api/v1/hsqe/actionitems/CreateOrUpdateTask
Supported Verbs
- POST: Insert or update a task.
Required Parameters
-
Task Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies one Task Model to be created or updated.
-
Data Model
Task Model
{
"Id": <GUID>,
"AssetId": <GUID>,
"ComponentId": <GUID>,
"LocationId": <GUID>,
"SpaceId": <GUID>,
"CreatedById": <GUID>,
"DeletedById": <GUID>,
"ScheduledById": <GUID>,
"ScheduledDate": <date>,
"DueDate": <date>,
"CompletedDate": <datetime>,
"DeletedDate": <datetime>,
"Description": <string>,
"AssignTo": <string>,
"Severity": <string>,
"ScheduledNote": <string>,
"CompleteNote": <string>,
"DeleteNote": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Tags": <Array>
[
<string>,
....
],
"AssigneeIds": <Array>
[
<GUID>,
....
],
"CompletedByIds": <Array>
[
<GUID>,
....
],
"VendorIds": <Array>
[
<GUID>,
....
],
"PartUsages": <Array>
[
<PartUsageModel>,
....
]
}
PartUsageModel Model
{
"PartId": <GUID>,
"AssetId": <GUID>,
"Quantity": <int>
}
Task Object Fields
-
Id
-
DataType: Guid
-
Required: false when creating new data; true when updating existing data
-
Purpose: update the uniquely matching Task.
-
-
AssetId
-
DataType: Guid
-
Required: true
-
Purpose: Sets the Asset for the task.
-
-
ComponentId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the Component for the task.
-
-
LocationId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the Location for the task.
-
-
SpaceId
-
DataType: Guid
-
Required: true
-
Purpose: Sets the Space for the task.
-
-
CreatedById
-
DataType: Guid
-
Required: true
-
Purpose: Sets the Created Person for the task.
-
-
DeletedById
-
DataType: Guid
-
Required: true when deleting task
-
Purpose: Sets the Deleted Person for the task.
-
-
ScheduledById
-
DataType: Guid
-
Required: true when ScheduledDate is later than DueDate or ScheduledNote is set
-
Purpose: Sets the Scheduled Note Posted Person for the task.
-
-
ScheduledDate
-
DataType: date
-
Required: false
-
Purpose: Sets the Scheduled Date for the task.
-
-
DueDate
-
DataType: date
-
Required: false
-
Purpose: Sets the Due Date for the task.
-
-
CompletedDate
-
DataType: datetime
-
Required: false; Sets to now if not specified when completing task
-
Purpose: Sets the Completed Date for the task.
-
-
DeletedDate
-
DataType: datetime
-
Required: false; Sets to now if not specified when deleting task
-
Purpose: Sets the Deleted Date for the task.
-
-
Description
-
DataType: string [max. 400 char]
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Task Description for the task.
-
-
AssignTo
-
DataType: string [max. 50 char]
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Assign to for the task.
-
Note: AssignTo can be one of the following values and is not case sensitive:
-
“Asset”: will assign this Task to asset
-
“Shore”: will assign this Task to shore
-
“DryDock”: will assign this Task to dry dock
-
-
-
Severity
-
DataType: string [max. 16 char]
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Severity for the task.
-
Note: Severity can be one of the following values and is not case sensitive:
-
“Low”: will mark this Task Severity as low
-
“Medium”: will mark this Task Severity as medium
-
“High”: will mark this Task Severity as high
-
-
-
ScheduledNote
-
DataType: string [max. 2000 char]
-
Required: true when ScheduledDate is later than DueDate or ScheduledById is set
-
Purpose: Sets the ScheduledNote for the task.
-
Note: A prefix ScheduledDate will be added to ScheduledNote.
-
-
CompleteNote
-
DataType: string [max. 2000 char]
-
Required: false
-
Purpose: Sets the Note for completing task.
-
-
DeleteNote
-
DataType: string [max. 2000 char]
-
Required: true when deleting task
-
Purpose: Sets the Note for deleting task.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: Sets the UserDefined for the task. Will be set to null if not specified.
-
-
Tags
-
DataType: array of
<string>
-
Required: false
-
Purpose: Sets the Tags for the task. If the tag does not exist, it will create one.
-
-
AssigneeIds
-
DataType: array of
<GUID>
-
Required: false
-
Purpose: Sets the Assignee for the task.
-
-
CompletedByIds
-
DataType: array of
<GUID>
-
Required: false
-
Purpose: Sets the Completed Person for the task.
-
-
VendorIds
-
DataType: array of
<GUID>
-
Required: false
-
Purpose: Sets the Vendors for the task.
-
-
PartUsages
-
DataType: array of JSON PartUsage Objects (see below)
-
Required: false
-
Purpose: Sets the PartUsages for the task.
-
PartUsage Object Fields
-
PartId
-
DataType: Guid
-
Required: true
-
Purpose: Sets the Part for the task part usages.
-
-
AssetId
-
DataType: Guid
-
Required: true
-
Purpose: Sets the Asset for the task part usages.
-
-
Quantity
-
DataType: int
-
Required: true
-
Purpose: Sets the Quantity for the task part usages.
-
PartUsage Object Fields
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <GUID>,
"ErrorMsgs":
[
{
"Entity": <string>,
"Message": <string>
},
....
]
}
-
ActionType: Insert or Update
-
Id: Guid for the new Task if ActionType is insert.
-
ErrorMsgs: Fields that have issues.
-
Entity: name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Find Task By Id
URI
api/v1/hsqe/actionitems/FindTaskById
Supported Verbs
- GET: return a filtered list of tasks.
Required Parameters
-
TaskId:
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: return task with given TaskId
-
Example Usage:
api/v1/hsqe/actionitems/FindTaskById?TaskId=530e6fbb-d304-477a-9a2c-c0d0810f38ff
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Description": <string>,
"SourceType": <string>,
"AssignTo": <string>,
"Severity": <string>,
"Status": <string>,
"AssetId": <GUID>,
"Asset": <string>,
"ComponentId": <GUID>,
"Component": <string>,
"LocationId": <GUID>,
"Location": <string>,
"SpaceId": <GUID>,
"Space": <string>,
"ScheduledDate": <datetime>,
"DueDate": <datetime>,
"CreatedById": <GUID>,
"CreatedBy": <string>,
"CreatedDate": <datetime>,
"OpenDate": <datetime>,
"CompletedBy": <Array>
[
{
"Id": <GUID>,
"PersonId": <GUID>,
"Name": <string>,
},
....
],
"CompletedDate": <datetime>,
"CompleteNote": <string>,
"DeletedById": <GUID>,
"DeletedBy": <string>,
"DeletedDate": <datetime>,
"DeleteNote": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Tags": <Array>
[
<string>,
....
],
"Assignee": <Array>
[
{
"Id": <GUID>,
"PersonId": <GUID>,
"Name": <string>,
},
....
],
"Vendors": <Array>
[
{
"Id": <GUID>,
"VendorId": <GUID>,
"Name": <string>,
},
....
],
"PartUsages": <Array>
[
{
"Id": <GUID>,
"PartId": <GUID>,
"Part": <string>,
"AssetId": <GUID>,
"Asset": <string>,
"Quantity": <int>,
},
....
],
"ScheduledNotes": <Array>
[
{
"Id": <GUID>,
"Note": <string>,
"PostedById": <GUID>,
"PostedBy": <string>,
"PostedDate": <datetime>,
},
....
],
"LastSyncDate": <datetime>,
"ExternalNumber": <string>
},
...
]
}
}
Find Tasks
URI
api/v1/hsqe/actionitems/FindTasks
Supported Verbs
- GET: return a filtered list of tasks sorted by CreatedDate descending, then Description ascending and Id ascending order. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2
-
Optional Parameters
-
SearchString:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return tasks with Description containing the string
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&SearchString=Foo
-
-
AssetId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return tasks with given AssetId
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&AssetId=530e6fbb-d304-477a-9a2c-c0d0810f38ff
-
-
ComponentId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return tasks with given ComponentId
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&ComponentId=530e6fbb-d304-477a-9a2c-c0d0810f38ff
-
-
OpenTasks:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not set, will return non-deleted tasks. When true, will return open tasks only. Otherwise, will return completed tasks only.
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&OpenTasks=true
-
-
IncludeArchived:
-
Data Type: boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: When false, will return non-deleted tasks only. Otherwise, will return deleted tasks as well.
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&IncludeArchived=true
-
-
DateType:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: CreatedDate
-
Purpose: Indicate which date field to use for FromDate and/or ToDate.
-
Note: The DateType includes five options: CreatedDate, ModifiedDate, CompletedDate, DueDate, ScheduledDate, and LastSyncDate. If not specified, DateType will be CreatedDate.
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&DateType=ModifiedDate&FromDate=2016-03-10T14:23:00-08:00
-
-
FromDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: When SearchString is not blank, will default to ToDate - 366 days (or Now - 366 days if ToDate is blank). Otherwise, will default to null.
-
Purpose: When not null, will return tasks when the date field specified in the DateType is >= FromDate
-
Note: When SearchString, FromDate and ToDate are not blank, FromDate cannot be earlier than ToDate - 366 days.
-
Example Usage:
api/v1/hsqe/actionitems/FindTasks?page=2&FromDate=2016-03-10T14:23:00-08:00
-
-
ToDate:
-
Data Type: date
-
Parameter Type: query string
-
Default Value: When SearchString is not blank, will default to FromDate + 366 days (or Now if FromDate is blank). Otherwise, will default to null.
-
Purpose: When not null, will return tasks when the date field specified in the DateType is <= ToDate.
-
Note: When SearchString, FromDate and ToDate are not blank, ToDate cannot be later than FromDate + 366 days.
-
Example Usage
api/v1/hsqe/actionitems/FindTasks?page=2&ToDate=2016-03-10T14:23:00-08:00
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Description": <string>,
"SourceType": <string>,
"AssignTo": <string>,
"Severity": <string>,
"Status": <string>,
"AssetId": <GUID>,
"Asset": <string>,
"ComponentId": <GUID>,
"Component": <string>,
"LocationId": <GUID>,
"Location": <string>,
"SpaceId": <GUID>,
"Space": <string>,
"ScheduledDate": <datetime>,
"DueDate": <datetime>,
"CreatedById": <GUID>,
"CreatedBy": <string>,
"CreatedDate": <datetime>,
"OpenDate": <datetime>,
"CompletedBy": <Array>
[
{
"Id": <GUID>,
"PersonId": <GUID>,
"Name": <string>,
},
....
],
"CompletedDate": <datetime>,
"CompleteNote": <string>,
"DeletedById": <GUID>,
"DeletedBy": <string>,
"DeletedDate": <datetime>,
"DeleteNote": <string>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"Tags": <Array>
[
<string>,
....
],
"Assignee": <Array>
[
{
"Id": <GUID>,
"PersonId": <GUID>,
"Name": <string>,
},
....
],
"Vendors": <Array>
[
{
"Id": <GUID>,
"VendorId": <GUID>,
"Name": <string>,
},
....
],
"PartUsages": <Array>
[
{
"Id": <GUID>,
"PartId": <GUID>,
"Part": <string>,
"AssetId": <GUID>,
"Asset": <string>,
"Quantity": <int>,
},
....
],
"ScheduledNotes": <Array>
[
{
"Id": <GUID>,
"Note": <string>,
"PostedById": <GUID>,
"PostedBy": <string>,
"PostedDate": <datetime>,
},
....
],
"LastSyncDate": <datetime>,
"ExternalNumber": <string>
},
...
]
}
}
Tax Types
Create/Update Tax Type
URI
api/v1/jobs/TaxTypes/CreateOrUpdateTaxType
Supported Verbs
- POST: insert or update a tax type.
Required Parameters
-
Tax Type Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies a Tax Type Model to be created or updated.
-
Data Model
Tax Type Model
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>,
"AccountingCode": <string>,
"UsesExternalSystem": <boolean>
}
Tax Type Object Fields
-
Id
-
DataType: GUID
-
Required: true when updating
-
Purpose: Identify the Tax Type to update.
-
-
Name
-
DataType: string [max. 400 char]
-
Required: true
-
Purpose: Sets the Name for the Tax Type.
-
-
ExternalSystemCode
-
DataType: string [max. 200 char]
-
Required: false
-
Purpose: Sets the ExternalSystemCode for the Tax Type.
-
-
AccountingCode
-
DataType: string [max. 50 char]
-
Required: false
-
Purpose: Sets the AccountingCode for the Tax Type.
-
-
UsesExternalSystem
-
DataType: boolean
-
Required: false
-
Default Value: false
-
Purpose: Sets the UsesExternalSystem for the TaxType.
-
Return Value
Action Accepted
Data:
{
"ActionType": <string>,
"Id": <Guid>,
"ErrorMsgs": <Array>
[
{
"Entity": <string>,
"Message": <string>,
"Details": <string>
},
...
]
}
-
ActionType: ‘Insert’ or ‘Update’
-
Id: Guid for the new Tax Type.
-
ErrorMsgs: Fields that have issues.
-
Entity: Name of the field.
-
Message: Error message.
-
Details: Additional information about the error.
Action Rejected
"Data": <Array>
- Data: Error message.
Find Tax Types
URI
api/v1/jobs/TaxTypes/FindTaxTypes
Supported Verbs
- GET: return a filtered list of tax types. The data is returned by page (see below).
Required Parameters
-
page:
-
Data Type: integer
-
Parameter Type: query string
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist. -
Example Usage:
api/v1/jobs/TaxTypes/FindTaxTypes?page=1
-
Optional Parameters
-
Name:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return tax types with Name containing the string
-
Example Usage:
api/v1/jobs/TaxTypes/FindTaxTypes?page=1&Name=Foo
-
-
AccountingCode:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return tax types with AccountingCode containing the string
-
Example Usage:
api/v1/jobs/TaxTypes/FindTaxTypes?page=1&AccountingCode=123
-
-
ExternalSystemCode:
-
Data Type: string
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return tax types with ExternalSystemCode containing the string
-
Example Usage:
api/v1/jobs/TaxTypes/FindTaxTypes?page=1&ExternalSystemCode=123
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <integer>,
"Page": <Array>
[
{
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>,
"AccountingCode": <string>,
"UsesExternalSystem": <boolean>
},
...
]
}
}
Action Rejected
"Data": <Array>
- Data: Error message.
Templates
Frequency Field
Helm CONNECT uses later.js for the Frequency
field along with its own
custom additions.
later.js
Used
Helm CONNECT does not use all of the Time Periods later.js
has.
Helm CONNECT uses:
- Time (
t
) - Day of the week (
d
) - Day of the month (
D
) - Month (
M
)
Helm CONNECT Custom Additions
A null
Frequency
field means “On Demand” frequency.
Schedule Effective Date
fd_a
- When the schedule begins as a UNIX timestamp (i.e., the number of milliseconds since 00:00:00 UTC on 1 January 1970).
fd_a_variable
- Controls which date the next date gets calculated from
- Values:
- key does not exist
- Means “Effective Date” (
fd_a
) above
- Means “Effective Date” (
["LastCompleted"]
- Means “Last Completed Date”
- key does not exist
“Repeats every”
rr_D
- Repeat every
x
days
- Repeat every
rr_W
- Repeat every
x
weeks
- Repeat every
rr_M
- Repeat every
x
months
- Repeat every
rr_Y
- Repeat every
x
years
- Repeat every
Examples
null
The Template has a “On Demand” frequency; it can be filled out whenever someone wants to.
{
"schedules": [
{
"t": [43200],
"fd_a": [1609459200000],
"rr_D": [1]
}
],
"exceptions": []
}
Repeat daily at 1200 based on the Effective Date starting from 2021-01-01.
{
"schedules": [
{
"t": [0],
"fd_a": [1609459200000],
"d": [6]
}
],
"exceptions": []
}
Repeat weekly on Friday at 0000 starting from 2021-01-01.
{
"schedules": [
{
"fd_a": [1609459200000],
"rr_W": [3],
"fd_a_variable": ["LastCompleted"]
}
],
"exceptions": []
}
Repeat every 3 weeks from the Last Completed Date starting from 2021-01-01.
{
"schedules": [
{
"t": [43200],
"fd_a": [1609459200000],
"D": [1,15]
}
]
}
Repeat monthly on the 1st and 15th day of the month at 1200 starting from 2021-01-01.
{
"schedules": [
{
"t": [28800, 72000],
"fd_a": [1609459200000],
"D": [1],
"M": [1]
},
{
"t": [28800, 72000],
"fd_a": [1609459200000],
"D": [15],
"M": [6]
}
]
}
Repeat yearly on January 1st and June 15th at 0800 and 2000 starting from 2021-01-01.
Form Templates
URI
api/v2/public/FormTemplates
Supported Verbs
GET
- Find Form Templates.
Data Models
Transaction Model
{
"Id": <GUID>,
"TemplateId": <GUID>,
"Name": <string>,
"Modified": <date>,
"Frequency": <string>,
"AssetId": <GUID>,
"LastCompletedDate": <date>,
"Spaces": [
{
"Id": <GUID>,
"Name": <string>
},...
],
"IsCrewChangeTriggered": <boolean>,
"IsShoreOnly": <boolean>,
"EventTypeId": <GUID>
}
Form Template Fields
-
Id
-
DataType: GUID
-
Purpose: specifies the Form Template’s version Id.
-
-
TemplateId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Form Template’s Id.
-
-
Name
-
DataType: string
-
Filterable: True
-
Purpose: specifies the Form Template’s description. Never null.
-
-
Modified
-
DataType: Date
-
Filterable: True
-
Purpose: specifies when the last time the Form Template was modified. May be null.
-
-
Frequency
-
DataType: string
-
Filterable: False
-
Purpose: specifies the internally used Form Template’s frequency. May be null.
-
-
AssetId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Form Template’s assigned Asset Id. May be null (shore only form).
-
-
LastCompletedDate
-
DataType: Date
-
Filterable: False
-
Purpose: specifies when the last time the Form was last completed. May be null.
-
-
Spaces
-
DataType: Space Model (see Form Template Model above)
-
Purpose: specifies Form Template’s assigned spaces.
-
-
IsShoreOnly
-
DataType: boolean
-
Filterable: True
-
Purpose: specifies if the Form Template is shore only.
-
-
IsCrewChangeTriggered
-
DataType: boolean
-
Filterable: True
-
Purpose: specifies if the Form Template is crew change triggered.
-
-
EventTypeId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies if the Form Template is event triggered and the associated event type’s Id.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Example Usage
// Get a paginated response of all Form Templates
GET api/v2/public/FormTemplates
// Get a specific Form Template by Template Id
GET api/v2/public/FormTemplates?$filter=TemplateId eq guid'2a58a342-cfd7-4e41-8e8d-7a6822f49f3f'
// Get Form Templates with the given Form Template's name
GET api/v2/public/FormTemplates?$filter=Name eq 'Basic Form'
// Get Form Templates with the given Asset Id
GET api/v2/public/FormTemplates?$filter=AssetId eq guid'5958a52f-cdd7-4e01-8e0d-7a6822f49f3e'
// Get all Shore Only Form Templates
GET api/v2/public/FormTemplates?$filter=IsShoreOnly eq true
// Get all Crew Change Triggered Form Templates
GET api/v2/public/FormTemplates?$filter=IsCrewChangeTriggered eq true
// Get Event Triggered Form Templates with the given event type Id
GET api/v2/public/FormTemplates?$filter=EventTypeId eq guid'6158e52f-cdd7-4ee1-8e0d-8a1822f49f2e'
// Get Form Templates with Modified Date greater than 2020-01-01
GET api/v2/public/FormTemplates?$filter=Modified gt datetime'2020-01-01'
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/FormTemplates?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Required Permissions
- API > Form Templates
Return Value
Action Accepted
Returns an array containing the requested Form Templates in the format of the Form Template Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Form Template Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Inspection Templates
URI
api/v2/public/InspectionTemplates
Supported Verbs
GET
- Find Inspection Templates.
Data Models
Transaction Model
{
"Id": <GUID>,
"TemplateId": <GUID>,
"Name": <string>,
"Modified": <date>,
"Frequency": <string>,
"AssetId": <GUID>,
"LastCompletedDate": <date>,
"Spaces": [
{
"Id": <GUID>,
"Name": <string>
},...
],
"ActivityTypes": [
{
"Id": <GUID>,
"Inclusion": <boolean>
},...
]
}
Inspection Template Fields
-
Id
-
DataType: GUID
-
Purpose: specifies the Inspection Template’s version Id.
-
-
TemplateId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Inspection Template’s Id.
-
-
Name
-
DataType: string
-
Filterable: True
-
Purpose: specifies the Inspection Template’s description. Never null.
-
-
Modified
-
DataType: Date
-
Filterable: True
-
Purpose: specifies when the last time the Inspection Template was modified. May be null.
-
-
Frequency
-
DataType: string
-
Filterable: False
-
Purpose: specifies the internally used Inspection Template’s frequency. May be null.
-
-
AssetId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Inspection Template’s assigned Asset Id.
-
-
LastCompletedDate
-
DataType: Date
-
Filterable: False
-
Purpose: specifies when the last time the Inspection Template’s checklist was last completed. May be null.
-
-
Spaces
-
DataType: Space Model (see Inspection Template Model above)
-
Purpose: specifies the Inspection Template’s assigned spaces.
-
-
Activity Types
-
DataType: Activity Types Model (see Inspection Template Model above)
-
Purpose: specifies if the Inspection Template is triggered by activity and its activity type Id.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Example Usage
// Get a paginated response of all Inspection Templates
GET api/v2/public/InspectionTemplates
// Get a specific Inspection Template by Template Id
GET api/v2/public/InspectionTemplates?$filter=TemplateId eq guid'2a58a342-cfd7-4e41-8e8d-7a6822f49f3f'
// Get Inspection Templates with the given Inspection Template's name
GET api/v2/public/InspectionTemplates?$filter=Name eq 'Basic Inspection'
// Get Inspection Templates with the given Asset Id
GET api/v2/public/InspectionTemplates?$filter=AssetId eq guid'5958a52f-cdd7-4e01-8e0d-7a6822f49f3e'
// Get Inspection Templates with Modified Date greater than 2020-01-01
GET api/v2/public/InspectionTemplates?$filter=Modified gt datetime'2020-01-01'
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/InspectionTemplates?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Required Permissions
- API > Inspection Templates
Return Value
Action Accepted
Returns an array containing the requested Inspection Templates in the format of the Inspection Template Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Inspection Template Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Inventory Templates
URI
api/v2/public/InventoryTemplates
Supported Verbs
GET
- Find Inventory Templates.
Data Models
Transaction Model
{
"Id": <GUID>,
"TemplateId": <GUID>,
"Name": <string>,
"Modified": <date>,
"Frequency": <string>,
"AssetId": <GUID>,
"LastCompletedDate": <date>,
"Spaces": [
{
"Id": <GUID>,
"Name": <string>
},...
],
}
Inventory Template Fields
-
Id
-
DataType: GUID
-
Purpose: specifies the Inventory Template’s version Id.
-
-
TemplateId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Inventory Template’s Id.
-
-
Name
-
DataType: string
-
Filterable: True
-
Purpose: specifies the Inventory Template’s description. Never null.
-
-
Modified
-
DataType: Date
-
Filterable: True
-
Purpose: specifies when the last time the Inventory Template was modified. May be null.
-
-
Frequency
-
DataType: string
-
Filterable: False
-
Purpose: specifies the internally used Inventory Template’s frequency. May be null.
-
-
AssetId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Inventory Template’s assigned Asset Id.
-
-
LastCompletedDate
-
DataType: Date
-
Filterable: False
-
Purpose: specifies when the last time the Inventory Template’s checklist was last completed. May be null.
-
-
Spaces
-
DataType: Space Model (see Inventory Template Model above)
-
Purpose: specifies the Inventory Template’s assigned spaces.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Example Usage
// Get a paginated response of all Inventory Templates
GET api/v2/public/InventoryTemplates
// Get a specific Inventory Template by Template Id
GET api/v2/public/InventoryTemplates?$filter=TemplateId eq guid'2a58a342-cfd7-4e41-8e8d-7a6822f49f3f'
// Get Inventory Templates with the given Inventory Template's name
GET api/v2/public/InventoryTemplates?$filter=Name eq 'Basic Inventory'
// Get Inventory Templates with the given Asset Id
GET api/v2/public/InventoryTemplates?$filter=AssetId eq guid'5958a52f-cdd7-4e01-8e0d-7a6822f49f3e'
// Get Inventory Templates with Modified Date greater than 2020-01-01
GET api/v2/public/InventoryTemplates?$filter=Modified gt datetime'2020-01-01'
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/InventoryTemplates?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Required Permissions
- API > Inventory Templates
Return Value
Action Accepted
Returns an array containing the requested Inventory Templates in the format of the Inventory Template Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Inventory Template Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Maintenance Templates
URI
api/v2/public/MaintenanceTemplates
Supported Verbs
GET
- Find Maintenance Templates.
Data Models
Transaction Model
{
"Id": <GUID>,
"TemplateId": <GUID>,
"Name": <string>,
"Modified": <date>,
"Frequency": <string>,
"AssetId": <GUID>,
"LastCompletedDate": <date>,
"Spaces": [
{
"Id": <GUID>,
"Name": <string>
},...
],
"ComponentId": <GUID>,
"ActivityTypes": [
{
"Id": <GUID>,
"Inclusion": <boolean>
},...
],
"ReadingTypes": [
{
"Id": <GUID>,
"Name": <string>,
"FrequencyHours": <integer>,
"EstDailyUsageHours": <integer>
},...
],
"Offsets": [
{
"ReadingTypeId": <GUID>,
"ReadingTypeName": <string>,
"OffsetHours": <integer>
},...
]
}
Maintenance Template Fields
-
Id
-
DataType: GUID
-
Purpose: specifies the Maintenance Template’s version Id.
-
-
TemplateId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Maintenance Template’s Id.
-
-
Name
-
DataType: string
-
Filterable: True
-
Purpose: specifies the Maintenance Template’s description. Never null.
-
-
Modified
-
DataType: Date
-
Filterable: True
-
Purpose: specifies when the last time the Maintenance Template was modified. May be null.
-
-
Frequency
-
DataType: string
-
Filterable: False
-
Purpose: specifies the internally used Maintenance Template’s frequency. May be null.
-
-
AssetId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Maintenance Template’s assigned Asset Id.
-
-
LastCompletedDate
-
DataType: Date
-
Filterable: False
-
Purpose: specifies when the last time the Maintenance Template’s checklist was last completed. May be null.
-
-
Spaces
-
DataType: Space Model (see Maintenance Template Model above)
-
Purpose: specifies the Maintenance Template’s assigned spaces.
-
-
ComponentId
-
DataType: GUID
-
Filterable: True
-
Purpose: specifies the Maintenance Template’s assign Component Id.
-
-
Activity Types
-
DataType: Activity Types Model (see Maintenance Template Model above)
-
Purpose: specifies if the Maintenance Template is triggered by activity and its activity type Id.
-
-
Reading Types
-
DataType: Reading Types Model (see Maintenance Template Model above)
-
Purpose: specifies the Maintenance template’s frequency reading types.
-
-
Offsets
-
DataType: Offsets Model (see Maintenance Template Model above)
-
Purpose: specifies the Maintenance template’s running hours frequency offsets.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Example Usage
// Get a paginated response of all Maintenance Templates
GET api/v2/public/MaintenanceTemplates
// Get a specific Maintenance Template by Template Id
GET api/v2/public/MaintenanceTemplates?$filter=TemplateId eq guid'2a58a342-cfd7-4e41-8e8d-7a6822f49f3f'
// Get Maintenance Templates with the given Maintenance Template's name
GET api/v2/public/MaintenanceTemplates?$filter=Name eq 'Basic Maintenance'
// Get Maintenance Templates with the given Asset Id
GET api/v2/public/MaintenanceTemplates?$filter=AssetId eq guid'5958a52f-cdd7-4e01-8e0d-7a6822f49f3e'
// Get Maintenance Templates with the given Component Id
GET api/v2/public/MaintenanceTemplates?$filter=ComponentId eq guid'6354e5bf-c127-3ea1-2e0d-7a38e2fa9f3e'
// Get Maintenance Templates with Modified Date greater than 2020-01-01
GET api/v2/public/MaintenanceTemplates?$filter=Modified gt datetime'2020-01-01'
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/MaintenanceTemplates?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Required Permissions
- API > Maintenance Templates
Return Value
Action Accepted
Returns an array containing the requested Maintenance Templates in the format of the Maintenance Template Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Maintenance Template Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Transaction (Jobs)
Transactions
URI
api/v2/public/transactions
Supported Verbs
-
GET
- Find Transactions.
-
POST
- Create new manual Transactions.
- Add transaction lines to existing Transactions.
- Add transaction notes to existing Transactions.
-
PATCH
- Update existing Transactions
Data Models
Transaction Model
{
"Id": <GUID>,
"TransactionNumber": <string>,
"Archived": <date>,
"TransactionType": {
"Id": <GUID>,
"Name": <string>,
"IsAP": <boolean>,
"IsAR": <boolean>
},
"Division": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"Area": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"TransactionDate": <date>,
"DraftDate": <date>,
"DueDate": <date>,
"Approved": <date>,
"Submitted": <date>,
"Posted": <date>,
"IsApproved": <boolean>,
"IsSubmitted": <boolean>,
"IsPosted": <boolean>,
"ExternalTransactionNumber": <string>,
"FormattedAddress": <string>,
"BillingEmailAddresses": <string>,
"CustomerPONumber": <string>,
"ParentTransaction": {
"Id": <GUID>,
"TransactionNumber": <string>,
},
"ReversedTransaction": {
"Id": <GUID>,
"TransactionNumber": <string>,
},
"OriginalTransaction": {
"Id": <GUID>,
"TransactionNumber": <string>,
},
"Reversed": <boolean>,
"IsReversal": <boolean>,
"Account": {
"Id": <GUID>,
"AccountNumber": <string>,
"Name": <string>
},
"Company": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"AccountingTerm": {
"Id": <GUID>,
"NumberOfDays": <decimal>,
"TransactionNumber": <string>,
},
"Contract": {
"Id": <GUID>,
"Description": <string>,
},
"CurrencyType": {
"Id": <GUID>,
"Name": <string>,
"ExternalSystemCode": <string>
},
"ExchangeRate": <decimal>,
"ReversalReason": {
"Id": <GUID>,
"Reason": <string>,
},
"OrderNumber": <string>,
"ShipName": <string>,
"InvoiceTemplate": {
"Id": <GUID>,
"Name": <string>
},
"IsManual": <boolean>,
"CreatedByUser": {
"Id": <GUID>,
"LoginEmail": <string>
},
"ModifiedByUser": {
"Id": <GUID>,
"LoginEmail": <string>
},
"ApprovedByUser": {
"Id": <GUID>,
"LoginEmail": <string>
},
"SubmittedByUser": {
"Id": <GUID>,
"LoginEmail": <string>
},
"BillingInterval": {
"Id": <GUID>,
"StartDate": <date>,
"EndDate": <date>
},
"Note": <string>,
"Modified": <date>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"TransactionNotes": [
{
"Id": <GUID>,
"Message": <string>,
"MessageDate": <date>
},
...
],
"TransactionLines": [
{
"Id": <GUID>,
"Rate": <decimal>,
"Quantity": <decimal>,
"Amount": <decimal>,
"HeaderDescription": <string>,
"DetailDescription": <string>,
"DetailDate": <date>,
"BillingTypeId": <GUID>,
"BillingIntervalId": <GUID>,
"OrderId": <GUID>,
"TripId": <GUID>,
"JobId": <GUID>,
"JobActivityId": <GUID>,
"EventId": <GUID>,
"LastModifiedUser": {
"Id": <GUID>,
"LoginEmail": <string>
},
"RevenueAllocations": [
{
"Id": <GUID>,
"ReferenceTransactionLineId": <GUID>,
"Debit": <decimal>,
"Credit": <decimal>,
"DivisionId": <GUID>,
"BillingIntervalId": <GUID>,
"OrderId": <GUID>,
"TripId": <GUID>,
"JobId": <GUID>,
"JobActivityId": <GUID>,
"ShipTypeId": <GUID>,
"AccountingCodes": []
},
...
]
},
...
]
}
Transaction Fields
-
Id
-
DataType: Guid
-
Required: False when using POST to create, True when using PATCH to update (unless Id is already specified in the URI).
-
Purpose: To uniquely identify a Transaction and to specify which Transaction to apply an operation to.
-
-
TransactionNumber
-
DataType: string [max. 100 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the transaction number of a Transaction.
-
-
TransactionType
-
DataType: JSON Object
-
Required: True
-
Filterable: True
-
Purpose: Specifies the type of transaction.
-
Fields:
- Id
<GUID>
: required - Name
<string>
: optional - IsAR
<boolean>
: read-only - Specifies whether this transaction type is accounts receivable. - IsAP
<boolean>
: read-only - Specifies whether this transaction type is accounts payable.
- Id
-
-
Division
-
DataType: JSON object
-
Required: True when using POST to create, false and read-only when using PATCH to update
-
Filterable: True
-
Purpose: Defines the Division which is attached to this transaction.
-
Fields:
- Id
<GUID>
: required - Name
<string>
: read-only - ExternalSystemCode
<string>
: read-only
- Id
-
-
Area
-
DataType: JSON Object
-
Required: True when using POST to create, false and read-only when using PATCH to update
-
Filterable: True
-
Purpose: Sets the Area of the Transaction.
-
Function: Selects the Area that uniquely matches one or more of the given fields.
-
Fields:
- Id
<GUID>
- Name
<string>
- ExternalSystemCode
<string>
- Id
-
-
TransactionDate
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the transaction date on the transaction.
-
-
DraftDate
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the draft date on the transaction.
-
-
DueDate
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the due date on the transaction.
-
-
Approved
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the date the transaction was approved. This is null if the transaction is not approved.
-
-
IsApproved
-
DataType: boolean
-
Required: False
-
Filterable: True
-
Purpose: When filtering, if true will only return Transactions that have been approved. If false will only return Transactions that have not been approved. When posting or patching with true, will approve the transaction and set Approved to the current time of the server. When posting or patching with false, will unapprove and set Approved to null.
-
-
Submitted
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the date the transaction was submitted. This is null if the transaction has not been submitted.
-
-
IsSubmitted
-
DataType: boolean
-
Required: False
-
Filterable: True
-
Purpose: When filtering, if true will only return Transactions that have been submitted. If false will only return Transactions that have not been submitted. When posting or patching, will submit the transaction and set Submitted to the current time of the server. When posting or patching with true, IsApproved must be set to true as well. When posting, if false, will set Submitted to null. Cannot be patched with false.
-
-
Posted
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the date the transaction was posted. This is null if the transaction has not been posted.
-
-
IsPosted
-
DataType: boolean
-
Required: False
-
Filterable: True
-
Purpose: When filtering, if true will only return Transactions that have been posted. If false will only return Transactions that have not been posted. When posting or patching, will post the transaction and set Posted to the current time of the server. When posting or patching with true, IsApproved and IsSubmitted must be set to true as well. Cannot currently unpost transactions.
-
-
ExternalTransactionNumber
-
DataType: string [max. 100 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the external transaction number of the transaction.
-
-
FormattedAddress
-
DataType: string [max. 1000 char]
-
Required: False
-
Filterable: False
-
Purpose: Specifies the formatted address of the transaction.
-
-
BillingEmailAddresses
-
DataType: string [max. 1000 char]
-
Required: False
-
Filterable: False
-
Purpose: Specifies the billing email addresses (comma separated) of the transaction.
-
-
CustomerPONumber
-
DataType: string [max. 100 char]
-
Required: False
-
Filterable: False
-
Purpose: Specifies the customer PO number of the transaction.
-
-
ParentTransaction
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the transaction’s parent transaction
-
Fields:
- Id
<GUID>
- TransactionNumber
<string>
- Id
-
-
ReversedTransaction
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the transaction’s reversed transaction
-
Fields:
- Id
<GUID>
- TransactionNumber
<string>
- Id
-
-
OriginalTransaction
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the transaction’s original transaction
-
Fields:
- Id
<GUID>
- TransactionNumber
<string>
- Id
-
-
Reversed
-
DataType: Boolean
-
Required: False
-
Filterable: True
-
Purpose: Indicates whether the transaction has been reversed.
-
-
IsReversal
-
DataType: Boolean
-
Required: False
-
Filterable: True
-
Purpose: Indicates whether the transaction is the reversal of another transaction.
-
-
Account
-
DataType: JSON Object
-
Required: True when using POST to create, false when using PATCH to update
-
Filterable: True
-
Purpose: Specifies the account associated with the transaction.
-
Fields:
- Id
<GUID>
- AccountNumber
<string>
- Name
<string>
- Id
-
-
Company
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the company associated with account of the transaction.
-
Fields:
- Id
<GUID>
- Name
<string>
- ExternalSystemCode
<string>
- Id
-
-
AccountingTerm
-
DataType: JSON Object
-
Required: False
-
Filterable: False
-
Purpose: Specifies the accounting terms of the transaction.
-
Fields:
- Id
<GUID>
- NumberOfDays
<integer>
- ExternalSystemCode
<string>
- Id
-
-
Contract
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the contract associated with the transaction.
-
Fields:
- Id
<GUID>
- Description
<integer>
- Id
-
-
CurrencyType
-
DataType: JSON Object
-
Required: True when using POST to create, false when using PATCH to update
-
Filterable: True
-
Purpose: Specifies the currency type that the transaction uses.
-
Fields:
- Id
<GUID>
- Name
<string>
- ExternalSystemCode
<string>
- Id
-
-
ExchangeRate
-
DataType: Number
-
Required: False
-
Filterable: False
-
Purpose: Specifies the exchange rate used on the transaction.
-
-
ReversalReason
-
DataType: JSON Object
-
Required: False
-
Filterable: False
-
Purpose: Specifies the reason the transaction was reversed.
-
Fields:
- Id
<GUID>
- Reason
<string>
- Id
-
-
OrderNumber
-
DataType: string [max. 1000 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the order numbers on the transaction, in a comma separated list.
-
-
ShipName
-
DataType: string [max. 150 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies the ship used on the transaction.
-
-
InvoiceTemplate
-
DataType: JSON Object
-
Required: True when using POST to create, false when using PATCH to update
-
Filterable: False
-
Purpose: Specifies the invoice template (invoice style) the transaction uses.
-
Fields:
- Id
<GUID>
- Name
<string>
- Id
-
-
IsManual
-
DataType: boolean
-
Required: False
-
Filterable: True
-
Purpose: Specifies whether the transaction is a manual transaction.
-
-
CreatedByUser
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the user who created the transaction.
-
Fields:
- Id
<GUID>
- LoginEmail
<string>
- Id
-
-
ModifiedByUser
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the user who last modified the transaction.
-
Fields:
- Id
<GUID>
- LoginEmail
<string>
- Id
-
-
ApprovedByUser
-
DataType: JSON Object
-
Required: False
-
Filterable: False
-
Purpose: Specifies the user who approved the transaction.
-
Fields:
- Id
<GUID>
- LoginEmail
<string>
- Id
-
-
SubmittedByUser
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the user who submitted the transaction.
-
Fields:
- Id
<GUID>
- LoginEmail
<string>
- Id
-
-
BillingInterval
-
DataType: JSON Object
-
Required: False
-
Filterable: True
-
Purpose: Specifies the billing interval of the transaction
-
Fields:
- Id
<GUID>
- StartDate
<date>
- EndDate
<date>
- Id
-
-
Note
-
DataType: string [max. 2000 char]
-
Required: False
-
Filterable: False
-
Purpose: Specifies the transaction note on the transaction
-
-
Modified
-
DataType: date
-
Required: False
-
Filterable: True
-
Purpose: Specifies the date the transaction was last modified.
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: False
-
Filterable: False
-
Purpose: Sets the UserDefined for the transaction.
-
-
TransactionNotes
-
DataType: Array
-
Required: False
-
Filterable: False
-
Purpose: Specifies the notes that have been attached to the transaction.
-
Fields:
- Id
<GUID>
- Message
<string>
- MessageDate
<date>
- Id
-
-
TransactionLines
-
DataType: Array
-
Required: True when using POST to create, false when using PATCH to update
-
Filterable: False
-
Purpose: Specifies the transaction lines on the transaction.
-
Fields:
- Id:
<GUID>
- Rate:
<decimal>
- Quantity:
<decimal>
required - Amount:
<decimal>
not required - HeaderDescription:
<string>
not required - DetailDescription:
<string>
required - DetailDate:
<date>
required - BillingTypeId:
<GUID>
not required - BillingIntervalId:
<GUID>
not required - OrderId:
<GUID>
not required if BillingIntervalId is filled in - TripId:
<GUID>
not required - JobId:
<GUID>
not required - JobActivityId:
<GUID>
not required - EventId:
<GUID>
not required - LastModifiedUser:
<JSON>
- Id:
<GUID>
- LoginEmail:
<string>
- Id:
- RevenueAllocations:
<Array>
not required - see below for structure.
- Id:
-
Note: When adding or editing transaction lines, the following restrictions apply:
- You cannot change the billingIntervalId on a transaction line.
- For manual transactions, you cannot set a value for OrderId, TripId, JobId, JobActivityId, or EventId.
- For generated transactions, you can patch/post transaction lines with an orderId/tripId as long as the order or trip already exists somewhere on the transaction.
- The values you enter have to make sense from a hierarchical standpoint. For example, you can’t use a tripId that refers to a trip that’s not on the order. The job (if specified) must exist on the trip, and so on.
-
-
RevenueAllocations
-
DataType: Array
-
Required: False
-
Purpose: Shows the Revenue Allocations for a Transaction Line. Revenue Allocations can be updated, but creation is internal to Helm CONNECT. See Fields and Notes for details.
-
Fields:
- Id:
<GUID>
read-only, required for update - ReferenceTransactionLineId":
<GUID>
read-only - Debit:
<decimal>
one of this or Credit required for update - Credit:
<decimal>
one of this or Debit required for update - DivisionId:
<GUID>
read-only - BillingIntervalId:
<GUID>
read-only - OrderId:
<GUID>
read-only - TripId:
<GUID>
read-only - JobId:
<GUID>
read-only - JobActivityId:
<GUID>
read-only - ShipTypeId:
<GUID>
read-only - AccountingCodes:
<Array>
read-only- Id:
<GUID>
- AccountingCode:
<string>
- EntityName:
<string>
- ReferenceType: `
- Id:
- Id:
-
Notes:
- Id is required to uniquely identify the Revenue Allocation being updated
- Update will fail under any of the following conditions
- Sum of Debit and Credit values accross all Revenue Allocations on a Transaction Line do not equal the Amount on that Line
- Debit and Credit are both non-null on a single Revenue Allocation
- Debit and Credit are both null on a single Revenue Allocation
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Transaction
URI
GET api/v2/public/transactions
or
GET api/v2/public/transactions/{Id}
Example Usage
// Get a paginated response of all transactions
GET api/v2/public/transactions
// Get a specific transaction by Id
GET api/v2/public/transactions/d21d73fb-bb69-11e8-8102-00155d040945
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 25 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/transactions?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Transactions with Number equal to "1234C" GET api/v2/public/transactions?$filter=TransactionNumber eq '1234C' // Get Transactions with Submitted greater than "2019-09-01" GET api/v2/public/transactions?$filter=Submitted gt datetime'2019-09-01' // Get a specific transaction with TransactionType Name equal "Credit Note" GET api/v2/public/transactions?$filter=TransactionType/Name eq 'Credit Note' // Get a specific transaction with CurrencyType Id equal "c26ede07-67f8-11ec-b9aa-144f8a6a31b3" GET api/v2/public/transactions?$filter=CurrencyType/Id eq guid'c26ede07-67f8-11ec-b9aa-144f8a6a31b3' // Get a specific transaction with Account AccountNumber equal "123" GET api/v2/public/transactions?$filter=Account/AccountNumber eq '123'
-
Required Permissions
One or both of the following:
- Jobs > Billing > Read
- Jobs > Billing > Edit
Return Value
Action Accepted
Returns an array containing the requested Transactions in the format of the Transaction Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Transaction Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Create Transaction
URI
POST api/v2/public/transactions
Example Usage
// Create one transaction
POST api/v2/public/transactions
{
"Division": {
"Id": "ba9269cd-c860-11e9-9328-d89ef3f189da"
},
"TransactionType": {
"Id": "ba926642-c860-11e9-9328-d89ef3f189da"
},
"Account": {
"Id": "c11fdfa4-c860-11e9-9328-d89ef3f189da"
},
"CurrencyType": {
"Id": "c11fdf29-c860-11e9-9328-d89ef3f189da"
},
"InvoiceTemplate": {
"Id": "ba92665e-c860-11e9-9328-d89ef3f189da"
},
"TransactionNotes":
[
{
"Message": "This is a test transaction."
}
]
,
"TransactionLines":
[
{
"Rate": 10,
"Quantity": 20,
"DetailDescription": "a",
"DetailDate": "2019-01-01 01:00",
"BillingTypeId": "C11FDF4D-C860-11E9-9328-D89EF3F189DA"
}
]
}
Required Parameters
-
Data Type: Transaction Model or Array of Transaction Model
-
Parameter Type: request body
-
Purpose: Supplies the Transactions(s) to be created.
Required Permissions
- Jobs > Billing > Edit
Return Value
Action Accepted
Returns an array containing the created Transactions.
<Array of Transaction Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Update Transaction
URIs
Update a Transaction
PATCH api/v2/public/transactions/
or
PATCH api/v2/public/transactions/{Id}
Add a Transaction Note to a Transaction
POST api/v2/public/transactions/{Id}/transactionnotes
Add a Transaction Line to a Transaction
POST api/v2/public/transactions/{Id}/transactionlines
Required Parameters
-
Id
:-
Data Type: Guid
-
Parameter Type: request path or request body
-
Purpose: To specify which Transaction to apply an operation to.
-
Example Usage:
// Update the exchange rate of a tranaction by providing the Id in the request path PATCH api/v2/public/transactions/c5e69784-24c5-11e7-82c5-f01faf32a6aa { "ExchangeRate": 1.34 } // Update the exchange rate of multiple Transactions by providing the Id in the request body PATCH api/v2/public/transactions [ { "Id": "c5e69784-24c5-11e7-82c5-f01faf32a6aa", "ExchangeRate": 1.43 }, { "Id": "d21d73fb-bb69-11e8-8102-00155d040945", "ExchangeRate": 1.44 } ] // Add a transaction note to an existing Transaction POST api/v2/public/transactions/c5e69784-24c5-11e7-82c5-f01faf32a6aa/transactionnotes { "Message": "This is a test note.", "MessageDate": "2019-08-30T09:57:00-07:00" } // Update a transaction note on an existing Transaction PATCH api/v2/public/transactions/c5e69784-24c5-11e7-82c5-f01faf32a6aa/transactionnotes { "Id": "4cf24684-cb47-11e9-9328-d89ef3f189da", "Message": "This is a test note.", "MessageDate": "2019-08-30T09:57:00-07:00" } // Add a transaction line to an existing Transaction POST api/v2/public/transactions/c5e69784-24c5-11e7-82c5-f01faf32a6aa/transactionlines { "Rate": 10, "Quantity": 20, "DetailDescription": "a", "DetailDate": "2019-01-01 01:00", "BillingTypeId": "C11FDF4D-C860-11E9-9328-D89EF3F189DA", "OrderId": "459DFEB9-00C3-4526-A1D4-1B83EFE2EA7F" } // Update just the rate on an existing Transaction PATCH api/v2/public/transactions/c5e69784-24c5-11e7-82c5-f01faf32a6aa/transactionlines { "Id": "4cf24684-cb47-11e9-9328-d89ef3f189da", "Rate": 15 }
-
Note: Once a transaction is submitted (the “Submitted” field is filled in with a date) you can no longer update it.
-
Required Permissions
- Jobs > Billing > Edit
Return Value
Action Accepted
Returns an array containing the modified Transactions.
<Array of Transaction Model>
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Transaction Metadata
URI
api/v2/public/transactionmetadata
Supported Verbs
GET
Find Transaction Metadata.
Data Models
Transaction Metadata Model
{
"Id": <GUID>,
"TransactionNumber": <string>,
"Modified": <date>,
"TransactionMetadata": <JSON>
}
Transaction Metadata Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a transaction.
-
-
TransactionNumber
-
DataType: string [max. 100 char]
-
Filterable: true
-
Purpose: Specifies the transaction number of a transaction.
-
-
Modified
-
DataType: date
-
Filterable: true
-
Purpose: Specifies the date the transaction was last modified.
-
-
TransactionMetadata
-
DataType: JSON Object
-
Filterable: false
-
Purpose: Returns a detailed object with the transaction metadata.
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this type of error.
-
-
ErrorMessage
-
DataType: string
-
Purpose: A message which describes what the error means.
-
Find Transaction Metadata
URI
GET api/v2/public/transactionmetadata
Example Usage
GET api/v2/public/transactionmetadata
Required Parameters
- None
Optional Parameters
-
page
:-
Data Type: integer
-
Parameter Type: query string
-
Default Value: 1
-
Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return.
page=1
, would return the first batch of results,page=2
would return the second batch of results, and so on. Each batch contains 10 records except for the last page which will contain less if not enough records exist. -
Example Usage:
GET api/v2/public/transactionmetadata?page=2
-
-
$filter
:-
Data Type: string
-
Parameter Type: query string
-
Default Value: empty
-
Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.
-
Example Usage:
// Get Transaction Metadata with TransactionNumber equal to "00001" GET api/v2/public/transactionmetadata?$filter=TransactionNumber eq '00001'
-
Return Value
Action Accepted
Returns an array containing the requested Transaction Metadata in the format of the Transaction Metadata Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Transaction Metadata Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Jobs > Billing > Read
Transaction Charge
URI
api/v2/public/transactioncharge
Supported Verbs
GET
: Return Transaction Charge Data.
Data Models
Transaction Charge Model
{
"Id": <GUID>,
"TransactionNumber": <string>,
"TransactionLines": [
{
"Id": <GUID>,
"ChargeJson": <JSON>
}
]
}
Transaction Charge Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify a transaction.
-
-
TransactionNumber
-
DataType: string [max. 100 char]
-
Filterable: true
-
Purpose: Specifies the transaction number of a transaction.
-
-
TransactionLines
-
DataType: Array
-
Filterable: false
-
Purpose: Provides the transaction lines on the transaction.
-
Fields:
- Id
<GUID>
- ChargeJson:
<JSON>
the charge data as serialized JSON
- Id
-
Error Model
{
"ErrorCode": <integer>,
"ErrorMessage": <string>
}
Error Model Fields
-
ErrorCode
-
DataType: integer
-
Purpose: An integer that uniquely identifies this
-