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 URL
The API URL consists of 2 parts.
- company domain: your tenant URL
- api path: path to a resource
The API can be accessed using this format:
https://<company domain>/<api path>
Example Usage:
https://company_name.helmconnect.com/api/v2/public/parts
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:
<Boolean>
-
Example Usage:
"Overdue": true
- Note: If a Boolean field is defined, but has never had its value set, Helm CONNECT will consider this as
false
.
-
-
Date
-
DataType:
<DateTime>
-
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:
<DateTime>
-
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": <DateTime>,
"PlannedEndDate": <DateTime>,
"StartDate": <DateTime>,
"EndDate": <DateTime>,
"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: DateTime
-
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: DateTime
-
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: DateTime
-
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: DateTime
-
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": <DateTime>,
"PlannedEndDate": <DateTime>,
"StartDate": <DateTime>,
"EndDate": <DateTime>,
"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": <DateTime>,
"PlannedEndDate": <DateTime>,
"StartDate": <DateTime>,
"EndDate": <DateTime>,
"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: DateTime
-
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: DateTime
-
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: DateTime
-
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: DateTime
-
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": <DateTime>,
"PlannedEndDate": <DateTime>,
"StartDate": <DateTime>,
"EndDate": <DateTime>,
"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>,
},
...
],
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
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 accounting code 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: Specifies the tags this activity type has.
-
Fields:
- Id
<Guid>
- Name
<String>
- Id
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: The UserDefined fields for the Activity 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 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
Asset Profiles
URI
api/v2/public/assetprofiles
Supported Verbs
-
GET
- Find Asset Profiles.
-
POST
- Create new Asset Profiles.
-
PATCH
- Update existing Asset Profiles.
-
DELETE
- Archive existing Asset Profiles.
Example Usage
// Get a paginated response of all asset profiles
GET api/v2/public/assetprofiles
// Get a specific asset profile by Id
GET api/v2/public/assetprofiles/d21d73fb-bb69-11e8-8102-00155d040945
// Add a single asset profile
POST api/v2/public/assetprofiles
{
"Name": "New Profile",
"Type": "PRIMARY_ASSET"
}
// Update Name of asset profile. Type is unpatchable
PATCH api/v2/public/assetprofiles
{
"Id": "7694520e-b2de-4dbe-9d6d-fbf8addd8a28",
"Name": "New Profile 2"
}
PATCH api/v2/public/assetprofiles/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
{
"Name": "New Profile 2"
}
// Delete an asset profile
DELETE api/v2/public/assetprofiles/7694520e-b2de-4dbe-9d6d-fbf8addd8a28
Data Models
Asset Profile Model
{
"Id": <Guid>,
"Name": <String>,
"Type": <String>,
}
Asset Profile 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 an AssetProfile and to specify which AssetProfile to apply an operation to.
-
-
Name
-
DataType: String [max. 100 char]
-
Required: True when using POST to create, False when using PATCH to update.
-
Filterable: True
-
Purpose: Specifies the name of an AssetProfile.
-
-
Type
-
DataType: String [max. 50 char]
-
Required: True when using POST to create. Cannot use PATCH to update this field.
-
Filterable: True
-
Purpose: Specifies the AssetProfile type. Options are ‘PRIMARY_ASSET’ and ‘ATTACHED_ASSET’.
-
-
Archived
-
DataType: DateTime
-
Required: False
-
Filterable: False
-
Purpose: Specifies whether the AssetProfile is archived.
-
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.
-
Asset Types
URI
api/v2/public/assettypes
Supported Verbs
-
GET
- Find Asset Types.
-
POST
- Create new Asset Types.
-
PATCH
- Update existing Asset Types.
Data Models
Asset Type Model
{
"Id": <Guid>,
"Name": <String>,
"ShortName": <String>,
"IsActive": <Boolean>,
"Archived": <DateTime>
}
Asset 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).
-
Purpose: To uniquely identify an AssetType and to specify which AssetType 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 an AssetType.
-
-
ShortName
-
DataType: String [max. 100 char]
-
Required: False
-
Filterable: True
-
Purpose: Specifies a shortened name for an AssetType.
-
-
IsActive
-
DataType: Boolean
-
Required: False
-
Filterable: True
-
Purpose: Specifies whether the AssetType is active. Will be set to true if not specified.
-
-
Archived
-
DataType: DateTime
-
Required: False
-
Filterable: False
-
Purpose: Specifies whether the AssetType is archived.
-
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.
-
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>,
"AssetProfileId": <Guid>,
"TimeZone": <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.
-
-
AssetProfileId
-
DataType: Guid
-
Required: false
-
Purpose: Sets the AssetProfileId for the Asset.
-
-
TimeZone
-
DataType: String [max. 50 char]
-
Required: false
-
Purpose: Sets the TimeZone 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
-
-
AssetProfileId:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: Will return the assets with AssetProfileId that matches the given Guid.
-
Example Usage:
api/v1/core/assets/FindAssets?page=1&AssetProfileId=11869509-53B4-11ED-A27C-B03CDCEB4BB8
-
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>,
"AssetProfileId": <Guid>,
"AssetProfileName": <String>,
"TimeZone": <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>,
"OfficialQuantityOverride": <Decimal>,
"OfficialQuantityUnitIdOverride": <Guid>,
"OfficialQuantityUnitId": <Guid>,
"OfficialQuantity": <Decimal>,
"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>,
},
"LoadOrder": <Integer>,
"DropOrder": <Integer>,
"AssignedTankermen": <Array>
[
{
"Id": <Guid>,
"Name": <String>
},
...
],
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
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 DateTime.
-
-
LoadEndDate
-
DataType: DateTime
-
Filterable: true
-
Required: false
-
Purpose: The order’s load end DateTime.
-
-
RequestedStartDate
-
DataType: DateTime
-
Required: false
-
Purpose: The order’s requested start DateTime.
-
-
UnloadStartDate
-
DataType: DateTime
-
Required: false
-
Purpose: The order’s unload start DateTime.
-
-
UnloadEndDate
-
DataType: DateTime
-
Required: false
-
Purpose: The order’s unload end DateTime.
-
-
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.
-
-
OfficialQuantityOverride
-
DataType: Decimal
-
Required: false
-
Purpose: The order’s actual quantity using the units specified in OfficialQuantityUnitIdOverride.
-
-
OfficialQuantityUnitIdOverride
-
DataType: Guid
-
Required: false
-
Purpose: The type of units used in the OfficialQuantity field. References Barging Units.
-
-
OfficialQuantityUnitId
-
DataType: Guid
-
Required: false
-
Purpose: The type of units used in the OfficalQuantity field. References Billing Units.
-
-
OfficialQuantity
-
DataType: Decimal
-
Required: false
-
Purpose: The order’s quantity using the units specified in OfficialQuantityUnitId.
-
-
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 DateTime.
-
-
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 DateTime 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>
-
BeginDate
<DateTime>
-
EndDate
<DateTime>
-
Comments
<String>
-
TripNumber
<String>
-
BeginLocationId
<Guid>
-
EndLocationId
<Guid>
-
TripTypeId
<Guid>
-
Tugs
<Array of Guid>
-
Created
<DateTime>
-
-
-
LoadOrder
-
DataType: Integer
-
Required: false
-
Purpose: The order’s load order.
-
-
DropOrder
-
DataType: Integer
-
Required: false
-
Purpose: The order’s drop order.
-
-
AssignedTankermen
-
DataType: Array of JSON Objects
-
Required: true
-
Purpose: The assigned tankermen for this order.
-
Fields:
-
Id
<Guid>
-
Name
<String>
-
-
-
UserDefined
-
DataType: User Defined Data Model (see User User Defined Fields for more details)
-
Filterable: false
-
Purpose: Sets the UserDefined for the order. 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 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>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"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.
-
-
BeginDate
-
DataType: DateTime
-
Filterable: true
-
Required: false
-
Purpose: The begin DateTime of the trip.
-
-
EndDate
-
DataType: Guid
-
Filterable: true
-
Required: false
-
Purpose: The end DateTime 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.
-
-
UserDefined
-
DataType: User Defined Data Model (see User User Defined Fields for more details)
-
Filterable: false
-
Required: false
-
Purpose: Sets the UserDefined for the barging trip. Will be set to null if not specified.
-
-
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
Certifications
Find Certifications
URI
api/v1/hsqe/certifications/FindCertifications
Supported Verbs
- GET: Return a filtered list of Certification Types and their current and historical Certifications. 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/hsqe/certifications/FindCertifications?page=2
-
-
personId: (required if no assetId given)
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: Filters the result set to only include Certifications that match the Person with the given personId.
-
Example Usage:
api/v1/hsqe/certifications/FindCertifications?page=2&personId=430e6fbb-d304-477a-9a2c-c0d0810f38ff
-
-
assetId: (required if no personId given)
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: Filters the result set to only include Certifications that match the Asset with the given assetId.
-
Example Usage:
api/v1/hsqe/certifications/FindCertifications?page=2&assetId=530e6fbb-d304-477a-9a2c-c0d0810f38ff
-
Return Value
With no results
{
"Data":
{
"TotalCount": 0,
"Page": []
}
}
With results
{
"Data":
{
"TotalCount": <Integer>,
"Page": <Array>
[
{
"TypeId": <Guid>,
"Type": <String>,
"TargetId": <Guid>,
"Target": <String>,
"PositionId": <Guid>,
"AssetTypeId": <Guid>,
"RequiredToOperate": <Boolean>,
"DocumentRequired": <Boolean>,
"RequireExpiration": <Boolean>,
"Category": <String>,
"CurrentCertification":
{
"Id": <Guid>,
"Obtained": <DateTime>,
"Expires": <DateTime>,
"ReferenceNumber": <String>,
"Updated": <DateTime>,
"Attachments": [
{
"Name": <String>
}, ...
]
},
"HistoricalCertifications": [
{
"Id": <Guid>,
"Obtained": <DateTime>,
"Expires": <DateTime>,
"ReferenceNumber": <String>,
"Updated": <DateTime>,
"Attachments": [
{
"Name": <String>
}, ...
]
}, ...
],
},
...
]
}
}
Create/Update Certification
URI
api/v1/hsqe/certifications/CreateCertification
Supported Verbs
- POST: Insert or update a certification for a Person or Asset.
Required Parameters
-
Certificate Model
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies Certificate Model to be created or updated.
-
Data Model
Certificate Model
{
"TypeId": <Guid>,
"AssetId": <Guid>,
"PersonId": <Guid>,
"Obtained": <DateTime>,
"Expires": <DateTime>,
"ReferenceNumber": <String>
}
Certification Object Fields
-
TypeId
-
DataType: Guid
-
Required: true
-
Purpose: Sets the Type on the Certificate being inserted.
-
-
AssetId
-
DataType: Guid
-
Required: true, if no PersonId supplied, otherwise false
-
Purpose: Sets the Target for the Certificate.
-
-
PersonId
-
DataType: Guid
-
Required: true, if no AssetId supplied, otherwise false
-
Purpose: Sets the Target for the Certificate.
-
-
Obtained
-
DataType: DateTime
-
Required: true
-
Purpose: Sets the Obtained DateTime for the Certificate.
-
-
Expires
-
DataType: DateTime
-
Required: true, when the Certification Type has RequireExpiration set to true
-
Purpose: Sets the Expires DateTime for the Certificate.
-
-
ReferenceNumber
-
DataType: String
-
Required: false
-
Purpose: Sets the ReferenceNumber for the Certificate.
-
Return Value
Action Accepted
Data:
{
"ActionType": <String>,
"Id": <Guid>,
"ErrorMsgs":
[
{
"Entity": <String>,
"Message": <String>
},
....
]
}
-
ActionType: Insert
-
Id: Guid for the new Certificate.
-
ErrorMsgs: Fields that have issues.
-
Entity: Name of the Field
-
Message: Error message
Action Rejected
"Data": <Array>
- Data: Error Message
Add Certification Attachment
URI
api/v1/hsqe/certifications/AddCertificationAttachment
Supported Verbs
- POST: attach a certification attachment.
Required Parameters
-
CertificationId
-
Data Type: Guid
-
Parameter Type: query string
-
Purpose: Identify which certification should get this attachment
-
Example Usage:
api/v1/hsqe/certifications/AddCertificationAttachment?certificationId=446f1bf2-917d-456a-9059-7a42981278f7
-
-
Data
-
Data Type: Blob
-
Parameter Type: Request Content
-
Purpose: Binary format of the attachment
-
-
FileName
-
Data Type: String
-
Parameter Type: Request Headers
-
Required: true, when updating, otherwise false
-
Example:
Content-Disposition: attachment; filename="fileName.pdf"
-
Return Value
Action Accepted
Data:
{
"ActionType": "Insert"
}
Action Rejected
"Message": Error Message
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
<Boolean>
-
IsActive
<Boolean>
-
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>
},
....
]
},
....
]
},
....
]
},
....
]
}
}
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": <DateTime>,
"ComponentTypeId": <Guid>,
"ComponentTypeName": <String>,
"EssentialSystem": <Boolean>,
"MakeId": <Guid>,
"MakeName": <String>,
"ModelId": <Guid>,
"ModelName": <String>,
"Modified": <DateTime>,
"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: DateTime
-
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: DateTime
-
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)
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>,
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
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: Specifies the account.
-
Fields:
- Id
<Guid>
- AccountNumber
<String>
- Name
<String>
- Id
-
-
EffectiveDate
-
DataType:
<DateTime>
-
Filterable: true
-
Purpose: Sets the EffectiveDate for the contract.
-
-
ExpiryDate
-
DataType:
<DateTime>
-
Filterable: true
-
Purpose: Sets the ExpiryDate for the contract.
-
-
UserDefined
-
DataType: User Defined Data Model (see User User Defined Fields for more details)
-
Filterable: false
-
Purpose: Sets the UserDefined for the contract. 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.
-
Required Permissions
- Jobs > Contracts > Read
Corrective Action Types
URI
api/v2/public/correctiveactiontypes
Supported Verbs
GET
- Find Corrective Action Types.
Data Models
Corrective Action Type Model
{
"Id": <Guid>,
"Name": <String>
}
Corrective Action Type Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify a corrective action type.
-
-
Name
-
DataType: String [max. 100 char]
-
Filterable: true
-
Purpose: Specifies the name of a corrective action 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 Corrective Action Types
URI
GET api/v2/public/correctiveactiontypes
or
GET api/v2/public/correctiveactiontypes/{Id}
Example Usage
// Get a paginated response of all corrective action types
GET api/v2/public/correctiveactiontypes
// Get a specific corrective action type by Id
GET api/v2/public/correctiveactiontypes/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/correctiveactiontypes?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 Corrective Action Type with Id equal to "459fcf24-b07e-11ec-ba44-e4b97ad5b443" GET api/v2/public/correctiveactiontypes?$filter=Id eq Guid'459fcf24-b07e-11ec-ba44-e4b97ad5b443' // Get Corrective Action Types with Name equal to "CA Type" GET api/v2/public/correctiveactiontypes?$filter=Name eq 'CA Type'
-
Return Value
Action Accepted
Returns an array containing the requested Corrective Action Types in the format of the Corrective Action Types Model.
{
"Page": <Integer>,
"Next": <Uri>,
"Results": <Array of Corrective Action Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Setup > Compliance > CorrectiveActionTypes
Corrective Actions
Corrective Actions
URI
api/v2/public/CorrectiveActions
Supported Verbs
GET
- Get Corrective Actions.
Data Models
Corrective Action Model
{
"Id": <Guid>,
"Description": <String>,
"SourceType": <String>,
"Source": <String>,
"ExternalNumber": <String>,
"AssignTo": <String>,
"Severity": <String>,
"Status": <String>,
"AssetId": <Guid>,
"Asset": <String>,
"ComponentId": <Guid>,
"Component": <String>,
"LocationId": <Guid>,
"Location": <String>,
"SpaceId": <Guid>,
"Space": <String>,
"CreatedDate": <DateTime>,
"ModifiedDate": <DateTime>,
"OpenDate": <DateTime>,
"DueDate": <DateTime>,
"CompletedDate": <DateTime>,
"ApprovedDate": <DateTime>,
"DeclinedDate": <DateTime>,
"CreatedById": <Guid>,
"CreatedBy": <String>,
"DeclinedById": <Guid>,
"DeclinedBy": <String>,
"ApprovedById": <Guid>,
"ApprovedBy": <String>,
"CompleteNote": {
"Id": <Guid>,
"Note": <String>,
"PostedById": <Guid>,
"PostedBy": <String>,
"Posted": <DateTime>,
"Updated": <DateTime>,
"Archived": <DateTime>,
},
"DeclinedNote": {
"Id": <Guid>,
"Note": <String>,
"PostedById": <Guid>,
"PostedBy": <String>,
"Posted": <DateTime>,
"Updated": <DateTime>,
"Archived": <DateTime>,
},
"ApprovedNote": {
"Id": <Guid>,
"Note": <String>,
"PostedById": <Guid>,
"PostedBy": <String>,
"Posted": <DateTime>,
"Updated": <DateTime>,
"Archived": <DateTime>,
},
"UserDefined": User Defined Data Model (see User Defined Fields section for more details),
"CorrectiveActionTypeId": <Guid>,
"CorrectiveActionType": <String>,
"Tags": [
{
"Id": <Guid>,
"Tag": <String>,
"Archived": <DateTime>,
},...
],
"CompletedBy": [
{
"Id": <Guid>,
"Name": <String>,
"Archived": <DateTime>,
},...
],
"Assignees": [
{
"Id": <Guid>,
"Name": <String>,
"Archived": <DateTime>,
},...
],
"Vendors": [
{
"Id": <Guid>,
"Name": <String>,
"Archived": <DateTime>,
},...
],
"Attachments": [
{
"Id": <Guid>,
"FileName": <String>,
"FileSize": <Integer>,
"AttachedDate": <DateTime>,
"Archived": <DateTime>,
},...
],
"Notes": [
{
"Id": <Guid>,
"Note": <String>,
"PostedById": <Guid>,
"PostedBy": <String>,
"Posted": <DateTime>,
"Updated": <DateTime>,
"Archived": <DateTime>,
},...
],
"Finding": <String>
}
Corrective Action Fields
-
Id
-
DataType: Guid
-
Purpose: Specifies the Corrective Action’s Id.
-
-
Description
-
DataType: String [max. 400 char]
-
Filterable: True
-
Purpose: Specifies the Corrective Action’s description.
-
-
SourceType
-
DataType: String [max. 50 char]
-
Filterable: True
-
Purpose: Specifies the source of the Corrective Action.
-
Note: SourceType can be one of the following values and is case sensitive:
-
“CorrectiveAction”: The corrective action was created ad-hoc
-
“ExternalAudit”: The corrective action was generated from an external audit
-
“InternalAudit”: The corrective action was generated from an internal audit
-
“Form”: The corrective action was generated from a form
-
-
Source
-
DataType: String [max. 100 char]
-
Filterable: False
-
Purpose: Specifies the name of the entity which the Corrective Action was generated from.
-
-
ExternalNumber
-
DataType: String [max. 100 char]
-
Filterable: True
-
Purpose: Specifies the Corrective Action’s External Number
-
-
AssignTo
-
DataType: String [max. 50 char]
-
Filterable: True
-
Purpose: Specifies the Corrective Action’s selected Assign To option.
-
Note: AssignTo can be one of the following values and is case sensitive:
-
“Asset”
-
“Shore”
-
“DryDock”
-
-
-
Severity
-
DataType: String [max. 16 char]
-
Filterable: True
-
Purpose: Specifies the Corrective Action’s Severity.
-
Note: Severity can be one of the following values and is case sensitive:
-
“Low”
-
“Medium”
-
“High”
-
-
-
Status
-
DataType: String [max. 50 char]
-
Filterable: True
-
Purpose: Specifies the Corrective Action’s status. Corrective Action in planned status will not be included in results.
-
Note: Status can be one of the following values and is case sensitive:
-
“Open”
-
“Declined”
-
“AwaitingApproval”
-
“Closed”
-
-
-
AssetId
-
DataType: Guid
-
Filterable: True
-
Purpose: Specifies the Asset for the Corrective Action.
-
-
Asset
-
DataType: String [max. 400 char]
-
Filterable: True
-
Purpose: Specifies the name of the Corrective Action’s Asset.
-
-
ComponentId
-
DataType: Guid
-
Filterable: True
-
Purpose: Specifies the Component for the Corrective Action.
-
-
Component
-
DataType: String [max. 400 char]
-
Filterable: True
-
Purpose: Specifies the name of the Corrective Action’s Component.
-
-
SpaceId
-
DataType: Guid
-
Filterable: True
-
Purpose: Specifies the Space for the Corrective Action. Never null
-
-
Space
-
DataType: String [max. 200 char]
-
Filterable: True
-
Purpose: Specifies the name of the Corrective Action’s Space.
-
-
CreatedDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies when the Corrective Action was created.
-
-
ModifiedDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies when the last time the Corrective Action was modified. May be null.
-
-
OpenDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies when the Corrective Action was opened.
-
-
DueDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies the due date set for the Corrective Action.
-
-
CompletedDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies the date set on Corrective Action’s last completion.
-
-
ApprovedDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies the date set on Corrective Action’s last approval.
-
-
DeclinedDate
-
DataType: Datetime
-
Filterable: True
-
Purpose: Specifies the date set on Corrective Action’s last decline.
-
-
CreatedById
-
DataType: Guid
-
Filterable: True
-
Purpose: Specifies who the Corrective Action was created by. Never null
-
-
CreatedBy
-
DataType: String
-
Filterable: False
-
Purpose: Specifies the name of the person who created the Corrective Action.
-
-
DeclinedById
-
DataType: Guid
-
Filterable: False
-
Purpose: Specifies who the Corrective Action was declined by most recently.
-
-
DeclinedBy
-
DataType: String
-
Filterable: False
-
Purpose: Specifies the name of the person who declined the Corrective Action most recently.
-
-
ApprovedById
-
DataType: Guid
-
Filterable: False
-
Purpose: Specifies who the Corrective Action was approved by most recently.
-
-
ApprovedBy
-
DataType: String
-
Filterable: False
-
Purpose: Specifies the name of the person who approved the Corrective Action most recently.
-
-
CompleteNote
-
DataType: JSON Object
-
Purpose: Specifies the completion note on a Corrective Action. The posted by is associated with the first person selected in CompletedBy.
-
Fields:
- Id:
<Guid>
- Note:
<String>
- PostedById:
<Guid>
: filterable - PostedBy:
<String>
- Posted:
<DateTime>
: filterable - Updated:
<DateTime>
: filterable - Archived:
<DateTime>
- Id:
-
-
DeclinedNote
-
DataType: JSON Object
-
Filterable: True
-
Purpose: Specifies the most recent decline note on a Corrective Action
-
Fields:
- Id:
<Guid>
- Note:
<String>
- PostedById:
<Guid>
: filterable - PostedBy:
<String>
- Posted:
<DateTime>
: filterable - Updated:
<DateTime>
: filterable - Archived:
<DateTime>
- Id:
-
-
ApprovedNote
-
DataType: JSON Object
-
Filterable: True
-
Purpose: Specifies the most recent approval note on a Corrective Action
-
Fields:
- Id:
<Guid>
- Note:
<String>
- PostedById:
<Guid>
: filterable - PostedBy:
<String>
- Posted:
<DateTime>
: filterable - Updated:
<DateTime>
: filterable - Archived:
<DateTime>
- Id:
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: False
-
Filterable: False
-
Purpose: Sets the UserDefined for the Corrective Action
-
-
Tags
-
DataType: Array of Object
-
Filterable: True
-
Purpose: Specifies the tags on the Corrective Action
-
Fields:
- Id:
<Guid>
- Tag:
<String>
: filterable - Archived:
<DateTime>
- Id:
-
-
CompletedBy
-
DataType: Array of Object
-
Filterable: False
-
Purpose: Specifies the people who completed the Corrective Action most recently
-
Fields:
- Id:
<Guid>
- Name:
<String>
- Archived:
<DateTime>
- Id:
-
-
Assignees
-
DataType: Array of Object
-
Filterable: False
-
Purpose: Specifies the people who were assigned to the Corrective Action
-
Fields:
- Id:
<Guid>
- Name:
<String>
- Archived:
<DateTime>
- Id:
-
-
Vendors
-
DataType: Array of Object
-
Filterable: True
-
Purpose: Specifies the vendors who were assigned to the Corrective Action
-
Fields:
- Id:
<Guid>
- Name:
<String>
: filterable - Archived:
<DateTime>
- Id:
-
-
Attachments
-
DataType: Array of Object
-
Filterable: False
-
Purpose: Specifies the attachments on the Corrective Action
-
Fields:
- Id:
<Guid>
- FileName:
<String>
- FileSize:
<Integer>
- AttachedDate:
<DateTime>
- Archived:
<DateTime>
- Id:
-
-
Notes
-
DataType: Array of Object
-
Filterable: True
-
Purpose: Specifies notes on the Corrective Action excluding completion, decline, and approval notes.
-
Fields:
- Id:
<Guid>
- Note:
<String>
- PostedById:
<Guid>
: filterable - PostedBy:
<String>
- Posted:
<DateTime>
: filterable - Updated:
<DateTime>
: filterable - Archived:
<DateTime>
- Id:
-
-
Finding
-
DataType: String [max. 2000 char]
-
Filterable: False
-
Purpose: Specifies the description of the Audit finding if the Corrective Action came from an Audit.
-
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 published Corrective Actions
GET api/v2/public/CorrectiveActions
// Get a specific Corrective Action by DeclinedById
GET api/v2/public/CorrectiveActions?$filter=DeclinedById eq Guid'2a58a342-cfd7-4e41-8e8d-7a6822f49f3f'
// Get Corrective Action with the given Corrective Action's description
GET api/v2/public/CorrectiveActions?$filter=Description eq 'Basic CA'
// Get Corrective Action with a specific Tag
GET api/V2/public/CorrectiveActions?$filter=Tags/any(t:t/Tag eq 'TagName')
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/CorrectiveActions?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 > CorrectiveActions
Return Value
Action Accepted
Returns an array containing the requested Corrective Actions in the format of the Corrective Action Model.
{
"Page": <Integer>,
"Next": <Uri>,
"Results": <Array of Corrective Action 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": <DateTime>,
"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:
<DateTime>
-
Required: true
-
Purpose: Selects the DateTime of the exchange rate you want to create or update. If an exchange rate already exists for this DateTime it will be updated; otherwise a new exchange rate will be created. This parameter accepts a fully specified DateTime 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 DateTime 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 DateTime.
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": <DateTime>
}
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:
<DateTime>
-
Required: true
-
Purpose: Selects the DateTime of the exchange rate(s) you want to delete. All exchange rates that exist for this DateTime will be deleted. If no exchange rates exist for this DateTime then nothing will be deleted and no error will be returned. This parameter accepts a fully specified DateTime 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
-
-
ApplyUserDivisionFilter:
-
Data Type: Boolean
-
Parameter Type: query string
-
Default Value: false
-
Purpose: Will filter out Divisions the user doesn’t have permission to.
-
Example Usage:
api/v1/jobs/Divisions/FindDivisions?page=1&ApplyUserDivisionFilter=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>,
"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
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)
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": <DateTime>,
"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: DateTime
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event DateTime.
-
-
EventTypeId
-
DataType: Guid for the Event type
-
Required: true when creating new data; false when updating existing data
-
Purpose: Sets the Event type. PickUp and DropOff events are invalid for core events. Only PickUp/DropOff events may contain these event types.
-
-
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: false
-
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: DateTime
-
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: DateTime
-
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": <DateTime>,
"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": <DateTime>,
"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. PickUp and DropOff events are invalid for Trip events. Only PickUp/DropOff events may contain these event types.
-
-
Description
-
DataType: String
-
Required: false
-
Purpose: Sets the description for the Trip Event.
-
-
EventDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the Trip Event’s DateTime.
-
-
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": <DateTime>,
"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": <DateTime>,
"EventDate": <DateTime>,
"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. PickUp and DropOff events are invalid for Trip events. Only PickUp/DropOff events may contain these event types.
-
-
Description
-
DataType: String [max. 1000 char]
-
Required: false
-
Purpose: Sets the description for the Job Event.
-
-
PlannedEventDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the Job Event’s planned DateTime. Only one of PlannedEventDate and EventDate may be set.
-
-
EventDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the Job Event’s DateTime. 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": <DateTime>,
"EventDate": <DateTime>,
"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>,
"AccountingCode": <String>,
"Type": <String>,
"Spaces": <Array>
[
{
"Id": <Guid>,
"Name": <String>,
},
...
],
"Tags": <Array>
[
{
"Id": <Guid>,
"Name": <String>,
},
...
],
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
}
Event Type Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify an event type.
-
-
Name
-
DataType: String [max. 200 char]
-
Filterable: true
-
Purpose: Specifies the name of an event type.
-
-
AccountingCode
-
DataType: String [max. 50 char]
-
Filterable: true
-
Purpose: Specifies the accounting code of an event type.
-
-
Type
-
DataType: String
-
Filterable: true
-
Purpose: Indicates the type of the event type; for example, “DropOff” or “PickUp”.
-
-
Spaces
-
DataType: Array
-
Purpose: Specifies the spaces this event type is visible in.
-
Fields:
- Id
<Guid>
- Name
<String>
- Id
-
-
Tags
-
DataType: Array
-
Purpose: Specifies the tags this event type has.
-
Fields:
- Id
<Guid>
- Name
<String>
- Id
-
-
UserDefined
-
DataType: User Defined Data Model (see User Defined Fields section for more details)
-
Required: false
-
Purpose: The UserDefined fields for the Event 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 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 Id equal to "459fcf24-b07e-11ec-ba44-e4b97ad5b443" GET api/v2/public/eventtypes?$filter=Id eq Guid'459fcf24-b07e-11ec-ba44-e4b97ad5b443' // 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": <DateTime>,
"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": <Boolean>,
"Required": <Boolean>,
"RequiredOn" <Integer>,
"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: DateTime
-
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.
-
-
RequiredOn
-
DataType: Integer
-
Purpose: Specifies when the UI should require a value for the field. 0 represents not required, 1 represents always required, 2 represents required on completion, 3 represents required on billing.
-
-
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: DateTime
-
Parameter Type: query string
-
Default Value: unspecified
-
Purpose: filters results by created or last modified DateTime.
-
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": <DateTime>,
"EndDate": <DateTime>,
"PlannedStartDate": <DateTime>,
"PlannedEndDate": <DateTime>,
"RunningFrom": <Decimal>,
"CancelledDate": <DateTime>,
"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: DateTime
-
Required: false
-
Purpose: Sets the StartDate of the Job.
-
-
EndDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the EndDate of the Job.
-
-
PlannedStartDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the PlannedStartDate of the Job.
-
-
PlannedEndDate
-
DataType: DateTime
-
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: DateTime
-
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": <DateTime>,
"EndDate": <DateTime>,
"PlannedStartDate": <DateTime>,
"PlannedEndDate": <DateTime>,
"RunningFrom": <Decimal>,
"CancelledDate": <DateTime>,
"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: DateTime
-
Required: false
-
Purpose: Sets the StartDate of the Job.
-
-
EndDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the EndDate of the Job.
-
-
PlannedStartDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the PlannedStartDate of the Job.
-
-
PlannedEndDate
-
DataType: DateTime
-
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: DateTime
-
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: DateTime
-
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: DateTime
-
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: DateTime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Jobs that have been created or modified since the DateTime.
-
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": <DateTime>,
"EndDate": <DateTime>,
"PlannedStartDate": <DateTime>,
"PlannedEndDate": <DateTime>,
"CancelledDate": <DateTime>,
"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>,
"Areas": <Array> [
{
"Id": <Guid>,
"Name": <String>,
"ExternalSystemCode": <String>,
"ParentId": <Guid>
}
]
}
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: Specifies 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: Specifies 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: Specifies 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 DateTime of this location
-
Filterable: True
-
-
Areas
-
DataType: Array
-
Required: False. Providing it for any request is an error.
-
Filterable: True
-
Purpose: Defines the Areas which are Parent Locations of this Location, and the Location itself if it is an Area. This field is read-only and it is an error to attempt to set it to any value; set Parent and Divisions instead.
-
Fields:
- Id
<Guid>
- Name
<String>
- ExternalSystemCode
<String>
- ParentId
<Guid>
- 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 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": <DateTime>,
"ReceivedDate": <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": <DateTime>,
"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": <DateTime>,
"StartDate": <DateTime>,
"EndDate": <DateTime>,
"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": <DateTime>,
"EndDate": <DateTime>,
"PlannedStartDate": <DateTime>,
"PlannedEndDate": <DateTime>,
"RunningFrom": <Decimal>,
"CancelledDate": <DateTime>,
"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: DateTime
-
Required: false
-
Purpose: Sets the OrderDate of the Order.
-
-
ReceivedDate
-
DataType: date
-
Required: false
-
Purpose: Sets the ReceivedDate 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
<DateTime>
-
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 DateTime 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: DateTime
-
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: DateTime
-
Required: false
-
Purpose: Sets the StartDate of the Trip.
-
-
EndDate
-
DataType: DateTime
-
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 [max. 30]
-
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: DateTime
-
Required: false
-
Purpose: Sets the StartDate of the Job.
-
-
EndDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the EndDate of the Job.
-
-
PlannedStartDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the PlannedStartDate of the Job.
-
-
PlannedEndDate
-
DataType: DateTime
-
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: DateTime
-
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": <DateTime>, "NoteType": <String> } ], "Trips": <Array> [ { "Id": <Guid>, .... }, { "TripType": { "Id": <Guid>, "Name": <String> }, "FromLocation": { "Id": <Guid>, "ExternalSystemCode": <String> }, "ToLocation": { "Id": <Guid>, "ExternalSystemCode": <String> }, "Status": <String>, "RequestedDate": <DateTime>, "StartDate": <DateTime>, "EndDate": <DateTime>, "IsRequestedDateFirm": <Boolean>, "EstimatedDuration": <Decimal> "CancelledDate": <DateTime>, "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: DateTime
-
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: DateTime
-
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: DateTime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return Orders that have been created or modified since the DateTime.
-
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": <DateTime>,
"ArchivedDate": <DateTime>,
"Modified": <DateTime>,
"ReceivedDate": <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": <DateTime>,
"EndDate": <DateTime>,
"RequestedDate": <DateTime>,
"IsRequestedDateFirm": <Boolean>,
"EstimatedDuration": <Decimal>,
"Status": <String>,
"ArchivedDate": <DateTime>,
"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": <DateTime>,
"EndDate": <DateTime>,
"PlannedStartDate": <DateTime>,
"PlannedEndDate": <DateTime>,
"CancelledDate": <DateTime>,
"IsNoCharge": <Boolean>,
"ArchivedDate": <DateTime>,
"IsRequest": <Boolean>
"UserDefined": User Defined Data Model (see User Defined Fields section for more details)
},
....
]
},
....
],
"OrderNotes": <Array>
[
{
"Id": <Guid>,
"Message": <String>,
"MessageDate": <DateTime>,
"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": <DateTime>,
"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: DateTime
-
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 DateTime
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 DateTime (start DateTime and end DateTime’s period cannot overlap another contract’s period).
-
-
EndDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets part contract’s end DateTime(start DateTime and end DateTime’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": <DateTime>,
"EndDate": <DateTime>,
"AccountingCodes":
{
<String(ReferenceType)>:
{
"Id": <Guid>,
"AccountingCode": <String>,
"EntityName": <String>,
"ReferenceType": <String>
},
....
}
],
"PersonBankRecords":
[
{
"Id": <Guid>,
"Rate": <Decimal>,
"Quantity": <Decimal>,
"Factor": <Decimal>,
"Amount": <Decimal>,
"Date": <DateTime>,
"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: DateTime
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return the payroll periods containing this DateTime
-
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 DateTime at midnight, are returned. For example, if the DateTime 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": <DateTime>,
"EndDate": <DateTime>,
"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 DateTime 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": <DateTime>,
"ResetExportDate": <Boolean>
}
Payroll Class Object Fields
-
Id
-
Data Type: Guid
-
Required: true
-
Purpose: Identify the payroll period to update
-
-
ExportDate
-
Data Type: DateTime
-
Required: false
-
Purpose: Sets the exported DateTime field on the target payroll period
-
-
ResetExportDate
-
Data Type: Boolean
-
Required: false
-
Purpose: If true, sets the exported DateTime 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": <DateTime>,
"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: DateTime
-
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
-
-
Id:
-
Data Type: Guid
-
Parameter Type: query string
-
Default Value: null
-
Purpose: When not null, will return payroll class with provided Id
-
Example Usage:
api/v1/Personnel/PayrollClasses/FindPayrollClasses?page=1&Id=4ce80ef4-195c-11ed-b9d9-9828a6140862
-
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": <DateTime>
}, ...
]
},
...
]
}
}
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
Reading Type
URI
api/v2/public/readingtypes
Supported Verbs
GET
:- Get Reading Types.
Data Models
Reading Types Model
{
"Id": <GUID>,
"Name": <string>,
"DisplayName": <string>,
"Unit ": <string>,
"IsCumulative": <bool>,
}
Reading Types Fields
-
Id
-
DataType: Guid
-
Purpose: To uniquely identify a reading type.
-
-
Name
-
DataType: string [max. 400 char]
-
Filterable: true
-
Purpose: Specifies the name of a reading type.
-
-
Display Name
-
DataType: string [max. 20 char]
-
Filterable: true
-
Purpose: Specifies the display name of a reading type.
-
-
Unit
-
DataType: string [max. 10 char]
-
Filterable: true
-
Purpose: Specifies the unit of a reading type.
-
-
IsCumulative
-
DataType: boolean
-
Filterable: true
-
Purpose: Specifies the reading type is cumulative.
-
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 Reading Types
URI
GET api/v2/public/readingtypes
Example Usage
GET api/v2/public/readingtypes
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/readingtypes?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 Reading Types with Name equal to "Area" GET api/v2/public/readingtypes?$filter=Name eq 'Area'
-
Return Value
Action Accepted
Returns an array containing the requested Reading Types in the format of the Reading Types Model.
{
"Page": <integer>,
"Next": <URI>,
"Results": <Array of Reading Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Readings
URI
api/v2/public/readings
Supported Verbs
GET
:- Get Readings.
Data Models
Readings Model
{
"Id": <GUID>,
"AssetId": <GUID>,
"ComponentId": <GUID>,
"IsCumulative": <bool>,
"VesselComponentId": <GUID>,
"Source": <String>,
"SourceId": <GUID>,
"EntryDateTime": <date>,
"Submitted": <date>,
"RecordedByPersonId": <GUID>,
"ReadingTypeId": <GUID>,
"Value", <Decimal>,
"Modified": <date>
}
Readings Fields
-
Id
-
DataType: Guid
-
Required: False
-
Filterable: true
-
Purpose: To uniquely identify a Readings
-
-
AssetId
-
DataType: Guid
-
Required: False
-
Filterable: true
-
Purpose: Specifies the Readings’ assigned Asset Id
-
-
ComponentId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Readings’ assigned Component Id
-
-
IsCumulative
-
DataType: boolean
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Readings is cumulative or not.
-
-
VesselComponentId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Readings’ assigned Vessel Component Id
-
-
Source
-
DataType: String
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Readings’s origin:
External
,Legacy
(from old checklist),Maintenance
(from maintenance checklist)
-
-
SourceId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Readings’s maintenance checklist Id (if available)
-
-
EntryDateTime
-
DataType: Date
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Reading Checklist’s inspected date and time
-
-
Submitted
-
DataType: Date
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Reading Checklist’s submitted date and time
-
-
RecordedByPersonId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Reading Checklist’s Recorded By Person’s Id
-
-
ReadingTypeId
-
DataType: Guid
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Reading’s Reading Type Id
-
-
Value
-
DataType: Decimal
-
Required: false
-
Filterable: true
-
Purpose: Specifies the Reading’s Value
-
-
Modified
-
DataType: Date
-
Required: false
-
Filterable: true
-
Purpose: Shows when Reading was last updated.
-
Find Readings
URI
GET api/v2/public/readings
or
GET api/v2/public/readings/{Id}
Example usage
// Get a paginated response of all requests
GET api/v2/public/readings
// Get a specific request by Id
GET api/v2/public/readings/<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/readings?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/readings?$filter=VesselComponentId eq guid'4a58a342-cfd7-4e41-8e8d-7a6822f49f3f'
-
Post Readings
URI
api/v1/hsqe/CreateReadings
Supported Verbs
- POST: insert readings.
Required Parameters
-
CreateReadingsModel
-
Data Type: JSON Object (See Data Model for details)
-
Parameter Type: request body
-
Default Value: none
-
Purpose: Supplies the Reading information to be created.
-
Data Model
Create Readings Model
{
"AssetId": <GUID>,
"RecordedByPersonId": <GUID>,
"EntryDateTime": <date>,
"Readings": <Array>
[
{
"VesselComponentId": <GUID>,
"ReadingTypeId": <GUID>,
"Value": <decimal>,
"PropagateReading": <boolean>
}
],
}
Create Readings Object Fields
-
AssetId
-
DataType: Guid
-
Required: True
-
Purpose: Sets the Asset Id for the Readings.
-
-
RecordedByPersonId
-
DataType: Guid
-
Required: False (If not supplied, it will use current User’s Id)
-
Purpose: Sets the Recorded By Person’s Id for the Readings.
-
-
EntryDateTime
-
DataType: Date
-
Required: False (If not supplied, it will use current server date)
-
Purpose: Sets the Entry Date Time for the Readings.
-
-
Readings
-
DataType: JSON Object
-
Required: true
-
Purpose: Sets Readings
-
Fields:
-
VesselComponentId
<GUID>
-
ReadingTypeId
<GUID>
-
Value `<decimal>`
-
PropagateReading
<boolean>
-
-
Note:
- PropagateReading will default to false
-
Return Value
With no results
{
"Data":
{
"LogMessages": <Array>
[
{
"Message": <string>,
"Entity": <string>,
"Details": <string>
},
....
]
}
}
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": <DateTime>,
"Modified": <DateTime>,
"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: DateTime
-
Required: false
-
Filterable: true
-
Purpose: Shows when a request was created.
-
-
Modified
-
DataType: DateTime
-
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 DateTime 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](#UDF) 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 DateTime 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: Specifies 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: Specifies 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: Specifies 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: Specifies 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: Specifies 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: Specifies 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: Specifies 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
Task Types
URI
api/v2/public/tasktypes
Supported Verbs
GET
- Find Task Types.
Data Models
Task Type Model
{
"Id": <Guid>,
"Name": <String>
}
Task Type Fields
-
Id
-
DataType: Guid
-
Filterable: true
-
Purpose: To uniquely identify a task type.
-
-
Name
-
DataType: String [max. 100 char]
-
Filterable: true
-
Purpose: Specifies the name of a task 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 Task Types
URI
GET api/v2/public/tasktypes
or
GET api/v2/public/tasktypes/{Id}
Example Usage
// Get a paginated response of all task types
GET api/v2/public/tasktypes
// Get a specific task type by Id
GET api/v2/public/tasktypes/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/tasktypes?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 Task Types with Id equal to "459fcf24-b07e-11ec-ba44-e4b97ad5b443" GET api/v2/public/tasktypes?$filter=Id eq Guid'459fcf24-b07e-11ec-ba44-e4b97ad5b443' // Get Task Types with Name equal to "Task Type" GET api/v2/public/tasktypes?$filter=Name eq 'Task Type'
-
Return Value
Action Accepted
Returns an array containing the requested Task Types in the format of the Task Types Model.
{
"Page": <Integer>,
"Next": <Uri>,
"Results": <Array of Task Type Model>
}
Action Rejected
{
"Errors": <Array of Error Model>
}
- Errors: Collection of Error Model (See Data Models for details)
Required Permissions
- Setup > Maintenance > TaskTypes
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>,
"TaskTypeId": <Guid>,
"ScheduledDate": <DateTime>,
"DueDate": <DateTime>,
"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.
-
-
TaskTypeId
-
DataType: Guid
-
Required: false
-
Purpose: Indicates the Task Type linked to the task.
-
-
ScheduledDate
-
DataType: DateTime
-
Required: false
-
Purpose: Sets the Scheduled Date for the task.
-
-
DueDate
-
DataType: DateTime
-
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>,
"TaskTypeId": <Guid>,
"TaskType": <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 DateTime 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: DateTime
-
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 DateTime 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: DateTime
-
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 DateTime 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>,
"TaskTypeId": <Guid>,
"TaskType": <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>
},