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 name of an activity type.

• Type

  • DataType: String

  • Filterable: true

  • Purpose: Indicates the type of the activity type; for example, “Primary”, “RunningFrom”, “RunningTo”, or “Downtime”.

• Tags

  • DataType: Array

  • Purpose: Specifies the tags this activity type has.

  • Fields:

    • Id <Guid>
    • Name <String>

• 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>,
    "Modified": <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>,
        "Modified": <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 OfficalQuantityUnitIdOverride.

• 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.

• Modified

  • DataType: DateTime

  • Filterable: true

  • Required: false

  • Purpose: The DateTime the order was modified.

• 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>,
    "Modified": <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>,
            "Modified": <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.

• Comments

  • DataType: String

  • Filterable: false

  • Required: false

  • Purpose: Additional notes (operational / special instructions/etc) related to a barging trip.

• TripNumber

  • DataType: String

  • 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: Timestamp of when the barging trip record was initially created in the system.

• Modified

  • DataType: DateTime

  • Filterable: true

  • Required: false

  • Purpose: The DateTime the trip was modified.

• 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>,
          "GracePeriod": <String>,
          "CurrentCertification":
              {
                  "Id": <Guid>,
                  "Obtained": <DateTime>,
                  "Expires": <DateTime>,
                  "ReferenceNumber": <String>,
                  "Updated": <DateTime>,
                  "GracePeriodEnd": <DateTime>,
                  "Attachments": [
                      {
                          "Name": <String>
                      }, ...
                  ]
              },
          "HistoricalCertifications": [
              {
                  "Id": <Guid>,
                  "Obtained": <DateTime>,
                  "Expires": <DateTime>,
                  "ReferenceNumber": <String>,
                  "Updated": <DateTime>,
                  "GracePeriodEnd": <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. The unique identifier of the person associated with the certification.

• 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

Commodity

Create/Update/Delete Commodity

URI

api/v2/public/commodities

Supported Verbs

• GET

  • Find Commodities

• POST

  • Create new Commodities

• PATCH

  • Update existing Commodities

• DELETE

  • Archive existing Commodities

Data Models

Commodity Model

{
    "Id": <Guid>,
    "Name": <String>,
    "ShortName": <String>,
    "CommodityType": <Commodity Type Model>,
    "DefaultAmountUnit": <Part Unit Type Model>,
    "ExternalSystemCode": <String>,
    "Archived": <DateTime>
}

Commodity Fields

• Id

  • Data Type: Guid

  • Required: False when using POST to create. True when using PATCH to update

  • Purpose: To uniquely identify a commodity and to specify which commodity to apply an operation to.

• Name

  • Data Type: String

  • Required: True when using POST to create; otherwise, False.

  • Filterable: True

  • Purpose: Specifies the commodity’s name.

• ShortName

  • Data Type: String

  • Required: True when using POST to create; otherwise, False.

  • Filterable: True

  • Purpose: Specifies the commodity’s short name.

• CommodityType

  • Data Type: Commodity Type Model

  • Required: True (just required Commodity Type’s Id) when using POST to create; otherwise, False.

  • Filterable: True

  • Purpose: Specifies the commodity’s commodity type.

• DefaultAmountUnit

  • Data Type: Part Unit Type Model

  • Required: True (just required Part Unit Type’s Id) when using POST to create; otherwise, False.

  • Filterable: True

  • Purpose: Specifies the commodity’s default amount unit.

• ExternalSystemCode

  • Data Type: String

  • Required: False.

  • Filterable: True

  • Purpose: Specifies the commodity’s external system code.

• Archived

  • Data Type: DateTime

  • Required: False.

  • Filterable: True

  • Purpose: Specifies whether the Commodity is archived.

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 Commodities

URIs

GET api/v2/public/commodities

or

GET api/v2/public/commodities/{Id}

Example Usage

// Gets a paged result of commodities
GET api/v2/public/commodities

// Gets a single commodity
GET api/v2/public/commodities/0CDF2BFE-8E8C-11EC-BA42-E4B97AD5B443

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/commodities?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 commodities with the name
    GET api/v2/public/commodities?$filter=Name eq 'Commodity Name'
    

Return Value

Action Accepted

Returns an array containing the requested commodities in the format of commodity model.

{
    "Page": <Integer>,
    "Next": <Uri>,
    "Results": <Array of Commodity Model>
}

Action Rejected

{
  "Errors": <Array of Error Model>
}

• Errors: Collection of Error Model (See Data Models for details)

Create Commodity

URI

POST api/v2/public/commodities

Example Usage

// Add a single commodity
POST api/v2/public/commodities
{
    "Name": "Grains",
    "ShortName: "G",
    "CommodityType":
    {
        "Id": "9ab7d52a-8dcd-11ec-ba42-e4b97ad5b443" 
    },
    "DefaultAmountUnit": 
    {
        "Id": "9ab7d52b-8dcd-11ec-ba42-e4b97ad5b443"
    },
    "ExternalSystemCode": "X-4123"
}

// Add multiple commodities.
POST api/v2/public/commodities
[
    {
        "Name": "Grains",
        "ShortName: "G",
        "CommodityType":
        {
            "Id": "9ab7d52a-8dcd-11ec-ba42-e4b97ad5b443" 
        },
        "DefaultAmountUnit": 
        {
            "Id": "9ab7d52b-8dcd-11ec-ba42-e4b97ad5b443"
        },
        "ExternalSystemCode": "X-4123"
    },
    {
        "Name": "Sand",
        "ShortName: "s",
        "CommodityType":
        {
            "Id": "9ab7d52a-8dcd-11ec-ba42-e4b97ad5b443" 
        },
        "DefaultAmountUnit": 
        {
            "Id": "9ab7d52b-8dcd-11ec-ba42-e4b97ad5b443"
        },
        "ExternalSystemCode": "X-5233"
    }
]

Required Parameters

• Data Type: Commodity Model or Array of Commodity Model

• Parameters Type: request body

• Purpose: Supplies Commodity(s) to be created.