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.

API Authorization

All API HTTP requests must have the following headers attached

API-Key: <key>,
Content-Type: application/json

The key comes from the API key management section of the Users App.

User Defined Fields

Purpose

• Allow users to update existing user defined fields to track information.

Data Model

• A JSON object contains a list of user defined fields. Each user defined field contains a name and value(s).

• Example Usage:

    "UserDefined":
      {
        "Height": 123,
        "Name": "Helm Operation",
        ....
      }
  

User Defined Field Types

• Text

  • DataType: <string>

  • Example Usage:

    "MMSI": "MIDxxxxxx"
  

• Number

  • DataType: <decimal>

  • Example Usage:

    "Gross Tonnage": 134
  

• Bool

  • DataType: <bool>

  • Example Usage:

    "Overdue": true
  

  • Note: If a bool field is defined, but has never had its value set, Helm CONNECT will consider this as false.

• Date

  • DataType: <date>

  • Example Usage:

    "HireDate": "2082-01-16T00:00:00-00:00"
  

  • Note: The time does get saved as provided but will be not visible in Helm CONNECT.

• Date and time

  • DataType: <date>

  • Example Usage:

    "ArriveDateTime": "2017-08-18T00:05:00-07:00"
  

• Select Box

  • DataType: <GUID> or <String>

  • Example Usage:

    "Direction": "West"
  

• Multi Selectbox

  • DataType: <GUID> or <String>

  • Example Usage:

    "OperatingAreas": "4E0D8981-7FA8-6155-54E5-54E5662F795E,4F60597D-68D2-7D66-4F60-62CD62CD624B"
  

  • Note: values are separated by comma(,)

Activities

Create/Update Activity

URI

api/v1/core/activities/CreateOrUpdateActivity

Supported Verbs

• POST: insert or update an Activity.

Required Parameters

• Activity Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Activity Model to be created.

Data Model

Activity Model

  {
    "Id": <Guid>,
    "VesselId": <GUID>,
    "ActivityTypeId": <GUID>,
    "FromLocationId": <Guid>,
    "ToLocationId": <Guid>,
    "PlannedStartDate": <date>,
    "PlannedEndDate": <date>,
    "StartDate": <date>,
    "EndDate": <date>,
    "RecordedByPersonId": <GUID>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
  }

Activity Object Fields

• Id

  • DataType: Guid

  • Required: false when creating new data; true when updating existing data

  • Purpose: Update the uniquely matching Activity

• VesselId

  • DataType: Guid for the Activity’s vessel.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s vessel.

• ActivityTypeId

  • DataType: Guid for the Activity type.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Activity type.

• FromLocationId

  • DataType: Guid for the Activity’s Location From.

  • Required: false

  • Purpose: Sets the Activity’s Location From.

• ToLocationId

  • DataType: Guid for the Activity’s Location To.

  • Required: false

  • Purpose: Sets the Activity’s Location To.

• PlannedStartDate

  • DataType: date

  • Required: Either PlannedStartDate or StartDate is required when creating new data

  • Purpose: Sets the Activity’s planned Start Date. Only one of PlannedStartDate and StartDate may be set.

• PlannedEndDate

  • DataType: date

  • Required: Either PlannedEndDate or EndDate is required when creating new data

  • Purpose: Sets the Activity’s planned End Date. Only one of PlannedEndDate and EndDate may be set.

• StartDate

  • DataType: date

  • Required: Either PlannedStartDate or StartDate is required when creating new data

  • Purpose: Sets the Activity’s actual Start Date. Only one of PlannedStartDate and StartDate may be set.

• EndDate

  • DataType: date

  • Required: Either PlannedEndDate or EndDate is required when creating new data

  • Purpose: Sets the Activity’s actual End Date. Only one of PlannedEndDate and EndDate may be set.

• RecordedByPersonId

  • DataType: Guid for the Activity Recorded By Person.

  • Required: false

  • Purpose: Sets who recorded the Activity.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Activity. Will be set to null if not specified.

Return Value

Action Accepted

  {
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ....
    ]
  }

• Id: Guid for the new Activity.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

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
  

Return Value

With no results

  {
    "Data": 
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data": 
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <Guid>,
          "VesselId": <GUID>,
          "ActivityTypeId": <GUID>,
          "FromLocationId": <Guid>,
          "ToLocationId": <Guid>,
          "PlannedStartDate": <date>,
          "PlannedEndDate": <date>,
          "StartDate": <date>,
          "EndDate": <date>,
          "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
        },
        ...
      ]
    }
  }

Archive Activity

URI

api/v1/core/activities/ArchiveActivity

Supported Verbs

• POST: Archive an activity.

Required Parameters

• Archive Activity Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Activity Id to be archived.

Data Model

Archive Activity Model

  {
    "Id": <Guid>
  }

Archive Activity Object Fields

• Id

  • DataType: Guid

  • Required: true

  • Purpose: Archives the uniquely matching Activity

Return Value

Action Accepted

  {
    "Action Type": "Archive",
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ...
    ]
  }

• ActionType: Will always be ‘Archive’.

• Id: Guid for the Activity.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

Action Rejected

  "Data": <Array>

• Data: Error Message

Create/Update Job Activity

URI

api/v1/jobs/activities/CreateOrUpdateJobActivity

Supported Verbs

• POST: insert or update a job activity.

Required Parameters

• Job Activity Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Job Activity Model to be created.

Data Model

Job Activity Model

  {
    "Id": <Guid>,
    "JobId": <GUID>,
    "ActivityTypeId": <GUID>,
    "FromLocationId": <Guid>,
    "ToLocationId": <Guid>,
    "PlannedStartDate": <date>,
    "PlannedEndDate": <date>,
    "StartDate": <date>,
    "EndDate": <date>,
    "IsStartDateAutomatic": <boolean>,
    "IsEndDateAutomatic": <boolean>,
    "RecordedByPersonId": <GUID>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
  }

Job Activity Object Fields

• Id

  • DataType: Guid

  • Required: false when creating new data; true when updating existing data

  • Purpose: Update the uniquely matching Job Activity

• JobId

  • DataType: Guid for the Activity’s job.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s job.

• ActivityTypeId

  • DataType: Guid for the Activity type.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Activity type.

• FromLocationId

  • DataType: Guid for the Activity’s Location From.

  • Required: true when creating new data; false when updating existing data

  • 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: true when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s Location To. You can only change the To Location of the last job activity.

• PlannedStartDate

  • DataType: date

  • Required: Either PlannedStartDate or StartDate is required when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s planned Start Date. Only one of PlannedStartDate and StartDate may be set. If there are pre-existing job activities, the Start Date must match the End Date of the last pre-existing job activity.

• PlannedEndDate

  • DataType: date

  • Required: Either PlannedEndDate or EndDate is required when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s planned End Date. Only one of PlannedEndDate and EndDate may be set.

• StartDate

  • DataType: date

  • Required: Either PlannedStartDate or StartDate is required when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s actual Start Date. Only one of PlannedStartDate and StartDate may be set. If there are pre-existing job activities, the Start Date must match the End Date of the last pre-existing job activity. You can only change the Start Date of the first job activity.

• EndDate

  • DataType: date

  • Required: Either PlannedEndDate or EndDate is required when creating new data; false when updating existing data

  • Purpose: Sets the Activity’s actual End Date. Only of one PlannedEndDate and EndDate may be set. You can only change the End Date of the last job activity.

• IsStartDateAutomatic

  • DataType: boolean

  • Required: false

  • Purpose: Sets the Activity’s IsEndDateAutomatic

• IsEndDateAutomatic

  • DataType: boolean

  • Required: false

  • Purpose: Sets the Activity’s IsEndDateAutomatic

• RecordedByPersonId

  • DataType: Guid for the Recorded By Person

  • Required: false

  • Purpose: Sets the Activity’s RecordedByPerson.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Activity. Will be set to null if not specified.

Return Value

Action Accepted

  {
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ....
    ]
  }

• Id: Guid for the new Job Activity.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

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 100 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
  

Return Value

With no results

  {
    "Data": 
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data": 
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <GUID>,
          "JobId": <GUID>,
          "ActivityTypeId": <GUID>,
          "FromLocationId": <GUID>,
          "ToLocationId": <GUID>,
          "PlannedStartDate": <date>,
          "PlannedEndDate": <date>,
          "StartDate": <date>,
          "EndDate": <date>,
          "IsStartDateAutomatic": <boolean>,
          "IsEndDateAutomatic": <boolean>,
          "RecordedByPersonId": <GUID>,
          "UserDefined": UserDefinedDataModel (see User Defined Fields section for more details)
        },
        ...
      ]
    }
  }

Assets

Update Asset

URI

api/v1/core/assets/CreateOrUpdateAsset

Supported Verbs

• POST: update an asset

Required Parameters

• Asset Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Asset Model to be updated.

Data Model

Asset Model

  {
    "Id": <GUID>,
    "Name": <string>,
    "ShortName": <string>,
    "AccountingCode": <string>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
  }

Asset Object Fields

• Id

  • DataType: GUID

  • Required: true

  • Purpose: Identify the asset to update

• Name

  • DataType: string [max. 400 char]

  • Required: false

  • Purpose: Sets the Name for the Asset.

• ShortName

  • DataType: string [max. 100 char]

  • Required: false

  • Purpose: Sets the ShortName for the Asset.

• AccountingCode

  • DataType: string [max. 50 char]

  • Required: false

  • Purpose: Sets the AccountingCode for the Asset.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined fields for the Asset.

Return Value

Action Accepted

  {
    "Data":
    {
      "ActionType": <string>,
      "Id": <GUID>
    }
  }

• ActionType: Insert (Not implemented) or Update

• Id: Guid of the updated Asset

Find Assets

URI

api/v1/core/assets/FindAssets

Supported Verbs

• GET: return a filtered list of Assets. The data is returned by page (see below).

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return. page=1, would return the first batch of results, page=2 would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist.

  • Example Usage:

    api/v1/core/assets/FindAssets?page=1
  

Optional Parameters

• Name:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the assets with a Name that contains the given string.

  • Example Usage:

    api/v1/core/assets/FindAssets?page=1&Name=Frigate
  

• ShortName:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the assets with a ShortName that contains the given string.

  • Example Usage:

    api/v1/core/assets/FindAssets?page=1&ShortName=HM
  

• AccountingCode:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the assets with AccountingCode that contains the given string.

  • Example Usage:

    api/v1/core/assets/FindAssets?page=1&AccountingCode=142
  

Return Value

With no results

  {
    "Data":
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data":
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <GUID>,
          "Name": <string>,
          "ShortName": <string>,
          "AccountingCode": <string>,
          "VesselTypeNames": <string>,
          "UserDefined": User Defined Data Model (see User Defined Fields section for more details),
        }
        ...
      ]
    }
  }

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)
  },
  ....
]

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 Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Company. Will be set to null if not specified.

Return Value

With errors

  {
    "Data": 
    [
      {
        "Name": <string>,
        "Errors":
        [
          {
            "Message": <string>,
            "Entity": <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)
      },
      "Division":
      {
        "Id": <GUID>,
        "Name": <string>,
        "ExternalSystemCode": <string>
      },
      "AccountNumber": <string>,
      "AccountType": <string>,
      "IsAR": <boolean>,
      "IsAP": <boolean>,
      "IsBlocked": <boolean>,
      "IsActive": <boolean>
    },
    ....
  ]

Account Object Fields

• Id

  • DataType: Guid

  • Required: false when creating new data; true when updating existing data

  • Purpose: update the uniquely matching Account.

• Name

  • DataType: string

  • Required: true

  • Purpose: Sets the Name for the Account.

• Company

  • DataType: JSON Object

  • Required: true

  • Purpose: Sets the Company of the Account.

  • Function: Selects the Company that uniquely matches the given Id, Name, Shortname and ExternalSystemCode

  • Fields:

    • Id <GUID>

    • Name <string>

    • ShortName <string>

    • ExternalSystemCode <string>

    • IsMyCompany <bool>

    • IsActive <bool>

    • UserDefined <string>

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

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

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>,
      "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.

• 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
  

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>,
              "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>
                    },
                    ....
                  ]
                },
                ....
              ]
            },
            ....
          ]
        },
        ....
      ]
    }
  }

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

• 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 created or updated.

Data Model

Currency Exchange Rate Model

  {
    "CurrencyType":
    {
      "Id": <GUID>,
      "Name": <string>,
    },
    "EffectiveDate": <date>,
    "ExchangeRate": <decimal>
  }

User Object Fields

• CurrencyType

  • DataType: JSON Object

  • Required: true

  • Purpose: Selects the currency type whose exchange rate will be altered.

  • Function: Selects the CurrencyTypeId that uniquely matches one or more of the given fields.

  • Fields:

    • Id <GUID>

    • Name <string> [max. 200 char]

• EffectiveDate

  • DataType: <date>

  • Required: true

  • Purpose: Selects the date of the exchange rate you want to create or update. If an exchange rate already exists for this date it will be updated; otherwise a new exchange rate will be created. This parameter accepts a fully specified date but only the year, month and day will be used; the time and timezone will not be used.

• ExchangeRate

  • DataType: <decimal>

  • Required: true

  • Purpose: Sets the Exchange Rate for the currency type and date specified.

Return Value

Action Accepted

  "Data":
  {
    "CurrencyTypeId": <Guid>,
    "LogMessages":
    [
      {
        "Entity": <string>,
        "Message": <string>
      },
      ....
    ]
  }

• CurrencyTypeId: Guid for the currency type that exchange rates were added/updated for.

• LogMessages: This will describe any failures that occurred when trying to find the matching entity. For example, if the CurrencyType could not be determined from your POST.

Action Rejected

  "Data": <Array>

• Data: Log Messages

Delete Currency Exchange Rate

URI

api/v1/jobs/billing/DeleteCurrencyExchangeRate

Supported Verbs

• POST: delete currency exchange rate(s) on a given date.

Required Parameters

• User Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Currency Exchange Rate Model to be deleted.

Data Model

Currency Exchange Rate Model

  {
    "CurrencyType":
    {
      "Id": <GUID>,
      "Name": <string>,
    },
    "EffectiveDate": <date>
  }

User Object Fields

• CurrencyType

  • DataType: JSON Object

  • Required: true

  • Purpose: Selects the currency type whose exchange rate(s) may be deleted.

  • Function: Selects the CurrencyTypeId that uniquely matches one or more of the given fields.

  • Fields:

    • Id <GUID>

    • Name <string> [max. 200 char]

• EffectiveDate

  • DataType: <date>

  • Required: true

  • Purpose: Selects the date of the exchange rate(s) you want to delete. All exchange rates that exist for this date will be deleted. If no exchange rates exist for this date then nothing will be deleted and no error will be returned. This parameter accepts a fully specified date but only the year, month and day will be used; the time and timezone will not be used.

Return Value

Action Accepted

  "Data":
  {
    "CurrencyTypeId": <Guid>,
    "ExchangeRatesDeleted": <integer>,
    "LogMessages":
    [
      {
        "Entity": <string>,
        "Message": <string>
      },
      ....
    ]
  }

• 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
  

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>,
          "DivisionType":
          {
            "Id": <GUID>,
            "Name": <string>  
          },
        },
        ...
      ]
    }
  }

Earning Code

Create/Update Earning Code

URI

api/v1/Personnel/EarningCodes/CreateOrUpdateEarningCode

Supported Verbs

• POST: insert or update an earning code.

Required Parameters

• Earning Code Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Earning Code Model to be created or updated.

Data Model

Earning Code Model

  {
    "Id": <GUID>,
    "Name": <string>,
    "AccountingCode": <string>,
    "QuantityType": <string>,
    "DoArchive": <boolean>
  }

Earning Code Object Fields

• Id

  • DataType: GUID

  • Required: true when updating

  • Purpose: Identify the earning code to update

• Name

  • DataType: string [max. 200 char]

  • Required: true

  • Purpose: Sets the Name for the Earning Code.

• AccountingCode

  • DataType: string [max. 50 char]

  • Required: false

  • Purpose: Sets the AccountingCode for the Earning Code.

• QuantityType

  • DataType: string [max. 20 char]

  • Required: false

  • Purpose: Sets the QuantityType for the Earning Code.

  • Accepted Value: “fixed”, “daily”, “hourly”, “amount”

• DoArchive

  • DataType: boolean

  • Required: false

  • Purpose: Archive the Earning Code.

  • Note: This field will be ignored when creating a new earning code. Once archived, it can’t be reverted.

Return Value

Action Accepted

  Data:
  {
    "ActionType": <string>,
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>,
        "Message": <string>
      },
      ....
    ]
  }

• ActionType: Insert or Update

• Id: Guid for the new earning code if ActionType is insert.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

Action Rejected

  "Data": <Array>

• Data: Error Message

Find Earning Code

URI

api/v1/Personnel/EarningCodes/FindEarningCodes

Supported Verbs

• GET: return a filtered list of earning codes. The data is returned by page (see below).

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return. page=1, would return the first batch of results, page=2 would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist.

  • Example Usage:

    api/v1/Personnel/EarningCodes/FindEarningCodes?page=2
  

Optional Parameters

• Name:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return earning code with Name containing the string

  • Example Usage:

    api/v1/Personnel/EarningCodes/FindEarningCodes?page=2&Name=Foo
  

Return Value

With no results

  {
    "Data":
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data":
    {
      "TotalCount": <integer>,
      "Page":
      [
        {
          "Id": <GUID>,
          "Name": <string>,
          "AccountingCode": <string>,
          "QuantityType": <string>
        },
        ....
      ]
    }
  }

Action Rejected

  "Data": <Array>

• Data: Error Message

Event

Create/Update Event

URI

api/v1/core/events/CreateOrUpdateEvent

Supported Verbs

• POST: insert or update an event.

Required Parameters

• Event Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Event Model to be created.

Data Model

Event Model

  {
    "Id": <GUID>,
    "Description": <string>,
    "EventDate": <date>,
    "EventTypeId": <GUID>,
    "VesselId": <GUID>,
    "SpaceId": <GUID>,
    "LocationId": <GUID>,
    "RecordedByPersonId": <GUID>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
  }

Event Object Fields

• Id

  • DataType: Guid

  • Required: false when creating new data; true when updating existing data

  • Purpose: Update the uniquely matching event.

• Description

  • DataType: string [max. 1000 char]

  • Required: false

  • Purpose: Sets the description for the Event.

• EventDate

  • DataType: date

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Event date.

• EventTypeId

  • DataType: Guid for the Event type

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Event type.

• VesselId

  • DataType: Guid for the Event’s vessel.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Event asset.

• SpaceId

  • DataType: Guid for the Event’s space.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Event space.

• LocationId

  • DataType: Guid for the Event location

  • Required: false

  • Purpose: Sets the Event location.

• RecordedByPersonId

  • DataType: Guid for the Event recorded by person.

  • Required: false

  • Purpose: Sets who recorded the Event.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Event. Will be set to null if not specified.

Return Value

Action Accepted

  Data:
  {
    "ActionType":  <string>,
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ....
    ]
  }

• ActionType: ‘Insert or Update’.

• Id: Guid for the new Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

Action Rejected

  "Data": <Array>

• Data: Error Message

Find Events

URI

api/v1/core/events/FindEvents

Supported Verbs

• GET: return a filtered list of Events. The data is returned by page (see below).

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return. page=1, would return the first batch of results, page=2 would return the second batch of results, and so on. Each batch contains 100 records except for the last page which will contain less if not enough records exist.

  • Example Usage:

    api/v1/core/events/FindEvents?page=1
  

Optional Parameters

• Id:

  • Data Type: Guid

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return the Event with the given Id

  • Example Usage:

    api/v1/core/events/FindEvents?page=1&Id=d21d73fb-bb69-11e8-8102-00155d040945
  

• AssetId:

  • Data Type: Guid

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return the Event with the given Asset Id

  • Example Usage:

    api/v1/core/events/FindEvents?page=1&AssetId=d21d73fb-bb69-11e8-8102-00155d040945
  

Return Value

With no results

  {
    "Data": 
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data": 
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <GUID>,
          "Description": <string>,
          "EventDate": <date>,
          "EventTypeId": <GUID>,
          "AssetId": <GUID>,
          "SpaceId": <GUID>,
          "LocationId": <GUID>,
          "RecordedByPersonId": <GUID>,
          "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
        },
        ...
      ]
    }
  }

Archive Event

URI

api/v1/core/events/ArchiveEvent

Supported Verbs

• POST: Archive an event.

Required Parameters

• Archive Event Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Event Id to be archived.

Data Model

Archive Event Model

  {
    "Id": <Guid>
  }

Archive Event Object Fields

• Id

  • DataType: Guid

  • Required: true

  • Purpose: Archives the uniquely matching Event

Return Value

Action Accepted

  {
    "Action Type": "Archive",
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ...
    ]
  }

• ActionType: Will always be ‘Archive’.

• Id: Guid for the Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

Action Rejected

  "Data": <Array>

• Data: Error Message

Create/Update Trip Event

URI

api/v1/jobs/events/CreateOrUpdateTripEvent

Supported Verbs

• POST: insert or update a trip event.

Required Parameters

• Trip Event Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Trip Event Model to be created.

Data Model

Trip Event Model

  {
    "Id": <Guid>,
    "TripId": <GUID>,
    "EventTypeId": <GUID>,
    "Description": <string>,
    "EventDate": <date>,
    "LocationId": <GUID>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
  }

Trip Event Object Fields

• Id

  • DataType: Guid

  • Required: false when creating new data; true when updating existing data

  • Purpose: Update the uniquely matching Trip Event

• TripId

  • DataType: Guid for the Trip Event’s trip.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Trip Event’s trip.

• EventTypeId

  • DataType: Guid for the Trip Event’s type.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Event type.

• Description

  • DataType: string

  • Required: false

  • Purpose: Sets the description for the Trip Event.

• EventDate

  • DataType: date

  • Required: false

  • Purpose: Sets the Trip Event’s date.

• LocationId

  • DataType: Guid

  • Required: false

  • Purpose: Sets the Trip Event’s location.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Trip Event. Will be set to null if not specified.

Return Value

Action Accepted

  {
    "Action Type": <string>,
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ....
    ]
  }

• ActionType: ‘Insert’ or ‘Update’.

• Id: Guid for the Trip Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

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 100 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
  

Return Value

With no results

  {
    "Data": 
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data": 
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <GUID>,
          "TripId": <GUID>,
          "EventTypeId": <GUID>,
          "Description": <string>,
          "EventDate": <date>,
          "LocationId": <Guid>,
          "UserDefined": UserDefinedDataModel (see User Defined Fields section for more details)
        },
        ...
      ]
    }
  }

Create/Update Job Event

URI

api/v1/jobs/events/CreateOrUpdateJobEvent

Supported Verbs

• POST: insert or update a Job Event.

Required Parameters

• Job Event Model

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Job Event Model to be created.

Data Model

Job Event Model

  {
    "Id": <Guid>, 
    "JobId": <GUID>, 
    "EventTypeId": <GUID>, 
    "Description": <string>,
    "PlannedEventDate": <date>,
    "EventDate": <date>, 
    "LocationId": <GUID>, 
    "RecordedByPersonId": <GUID>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
  }

Job Event Object Fields

• Id

  • DataType: Guid

  • Required: false when creating new data; true when updating existing data

  • Purpose: Update the uniquely matching Job Event

• JobId

  • DataType: Guid for the Job Events’s job.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Job Event’s job. Not supported for update.

• EventTypeId

  • DataType: Guid for the Job Event’s type.

  • Required: true when creating new data; false when updating existing data

  • Purpose: Sets the Event type.

• Description

  • DataType: string [max. 1000 char]

  • Required: false

  • Purpose: Sets the description for the Job Event.

• PlannedEventDate

  • DataType: date

  • Required: false

  • Purpose: Sets the Job Event’s planned date. Only one of PlannedEventDate and EventDate may be set.

• EventDate

  • DataType: date

  • Required: false

  • Purpose: Sets the Job Event’s date. Only one of PlannedEventDate and EventDate may be set.

• LocationId

  • DataType: Guid for the Location

  • Required: false

  • Purpose: Sets the Job Event’s location.

• RecordedByPersonId

  • DataType: Guid for the Recorded By Person

  • Required: false

  • Purpose: Sets the Job Event’s Recorded By Person.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Job Event. Will be set to null if not specified.

Return Value

Action Accepted

  {
    "Id": <GUID>,
    "ErrorMsgs":
    [
      {
        "Entity": <string>
        "Message": <string>
      },
      ....
    ]
  }

• Id: Guid for the Job Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

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 100 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
  

• 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
  

Return Value

With no results

  {
    "Data": 
    {
      "TotalCount": 0,
      "Page": []
    }
  }

With results

  {
    "Data": 
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <GUID>,
          "JobId": <GUID>,
          "EventTypeId": <GUID>,
          "Description": <string>,
          "PlannedEventDate": <date>,
          "EventDate": <date>,
          "LocationId": <GUID>,
          "RecordedByPersonId": <GUID>,
          "UserDefined": UserDefinedDataModel (see User Defined Fields section for more details)
        },
        ...
      ]
    }
  }

Order

Create Order

URI

api/v1/jobs/orders/CreateOrder

Supported Verbs

• POST: insert an Order and any associated Trips and Jobs.

Required Parameters

• OrderModel

  • Data Type: JSON Object (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies the Order information and Trip(s)/Job(s) information to be created.

Optional Parameters

• addNewShip

  • Data Type: boolean

  • Parameter Type: query string

  • Default Value: false

  • Purpose: When true and if Ship can’t be found, it will create new Ship based on the information provided.

  • Note: Name is required to add the new Ship

  • Example Usage:

    api/v1/Jobs/Orders/CreateOrder?addNewShip=true
  

• asRequest

  • Data Type: boolean

  • Parameter Type: query string

  • Default Value: false

  • Purpose: When true, instead of creating an Order directly, a Request for those changes will be created. Any Trip, Job or Ship that is created as a result will also be created as requests.

  • Example Usage:

    api/v1/Jobs/Orders/CreateOrder?asRequest=true
  

Data Model

Order Model

  {
    "Division":
    {
      "Id": <GUID>,
      "Name": <string>,
      "ExternalSystemCode": <string>
    },
    "Area":
    {
      "Id": <GUID>,
      "Name": <string>,
      "ExternalSystemCode": <string>
    },
    "Ship":
    {
      "Id": <GUID>,
      "ShipTypeId": <GUID>,
      "Name": <string>,
      "IMONumber": <string>,
      "MMSI": <string>,
      "Nation": <string>,
      "CallSign": <string>,
      "Height": <decimal>,
      "Deadweight": <decimal>,
      "GT": <decimal>,
      "LOA": <decimal>,
      "Beam": <decimal>,
      "TEU": <decimal>,
      "NT": <decimal>,
      "UserDefined": User Defined Data Model (see User Defined Fields section for more details)
    },
    "CustomerAccount":
    {
      "Id": <GUID>,
      "Name": <string>,
      "AccountNumber": <string>
    },
    "AgentAccount":
    {
      "Id": <GUID>,
      "Name": <string>,
      "AccountNumber": <string>
    },
    "AwardedToAccount":
    {
      "Id": <GUID>,
      "Name": <string>,
      "AccountNumber": <string>
    },
    "OrderDate": <date>,
    "CustomerPONumber": <string>,
    "VoyageNumber": <string>,
    "IsBillable": <boolean>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details),
    "Trips": <Array>
    [
      <TripModel>,
      ....
    ]
  }

Trip Model

  {
    "TripType":
    {
      "Id": <GUID>,
      "Name": <string>
    },
    "FromLocation":
    {
      "Id": <GUID>,
      "Name": <string>,
      "ExternalSystemCode": <string>
    },
    "ToLocation":
    {
      "Id": <GUID>,
      "Name": <string>,
      "ExternalSystemCode": <string>
    },
    "Status": <string>,
    "RequestedDate": <date>,
    "StartDate": <date>,
    "EndDate": <date>,
    "IsRequestedDateFirm": <boolean>,
    "EstimatedDuration": <decimal>,
    "NumberRequiredResources": <integer>,
    "UserDefined": User Defined Data Model (see User Defined Fields section for more details),
    "Jobs": <Array>
    [
      <JobModel>,
      ....
    ]
  }

Job Model

  {
    "RequiredResourceType":
    {
      "Id": <GUID>,
      "Name": <string>
    },
    "StartDate": <date>,
    "EndDate": <date>,
    "PlannedStartDate": <date>,
    "PlannedEndDate": <date>,
    "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 has IsMyCompany = true.

  • Fields:

    • Id <GUID>

    • Name <string>

    • AccountNumber <string>

• OrderDate

  • DataType: date

  • Required: false

  • Purpose: Sets the OrderDate of the Order.

• VoyageNumber

  • DataType: string

  • Required: false

  • Purpose: Sets the VoyageNumber of the Order.

• 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

• Trips

  • DataType: Array of JSON Trip Objects (see below)

  • Required: true

  • Purpose: Sets the Trips for the Order.

  • Note: Creating an Order must have at least one Trip attached.

Trip Object Fields

• TripType

  • DataType: JSON Object

  • Required: true

  • Purpose: Sets the TripTypeId of the Trip.

  • Function: Selects the TripType that uniquely matches one or more of the given fields.

  • Fields:

    • Id <GUID>

    • Name <string>

• FromLocation

  • DataType: JSON Object

  • Required: false

  • Purpose: Sets the FromLocationId of the Trip.

  • Function: Selects the FromLocation that uniquely matches one or more of the given fields.

  • Fields:

    • Id <GUID>

    • Name <String>

    • ExternalSystemCode <string>

• ToLocation

  • DataType: JSON Object

  • Required: false

  • Purpose: Sets the ToLocationId of the Trip.

  • Function: Selects the ToLocation that uniquely matches one or more of the given fields.

  • Fields:

    • Id <GUID>

    • Name <String>

    • ExternalSystemCode <string>

• Status

  • DataType: string

  • Required: false

  • Purpose: Sets the Status of the Trip.

  • Note: Status can be one of the following values and is case sensitive:

    • Null: will mark this Trip as unconfirmed

    • **"**STATUS_COMPLETE": will mark this Trip as complete

    • “STATUS_CONFIRMED”: will mark this Trip as confirmed

    • “STATUS_CANCELLED”: will mark this Trip as cancelled

• RequestedDate

  • DataType: date

  • Required: false

  • Purpose: Sets the RequestedDate of the Trip.

• IsRequestedDateFirm

  • DataType: boolean

  • Required: false

  • Purpose: Sets the IsRequestedDateFirm of the Trip.

• EstimatedDuration

  • DataType: decimal

  • Required: false

  • Purpose: Sets the Duration of the Trip.

  • Note: This value is stored in minutes.

• StartDate

  • DataType: date

  • Required: false

  • Purpose: Sets the StartDate of the Trip.

• EndDate

  • DataType: date

  • Required: false

  • Purpose: Sets the EndDate of the Trip.

• UserDefined

  • DataType: User Defined Data Model (see User Defined Fields section for more details)

  • Required: false

  • Purpose: Sets the UserDefined for the Trip.

• NumberRequiredResources

  • DataType: Integer

  • Required: false

  • Purpose: Create specified number of Jobs if the Jobs field (see below) is not specified

  • Note: Jobs will have default resource type if client only has one root resource type. Jobs’ startDate and endDate will default to Trip’s startDate and EndDate. Job’s RunningFrom and RunningTo will be defaulted based on the From and To Location.

    When updating, if the number is less than current number. It will remove Job without resources first then remove Job with later time.

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

  • Function: Selects the RequiredResourceType that uniquely matches one or more of the given fields.

  • Fields:

    • Id <GUID>

    • Name <string>

• StartDate

  • DataType: date

  • Required: false

  • Purpose: Sets the StartDate of the Job.

• EndDate

  • DataType: date

  • Required: false

  • Purpose: Sets the EndDate of the Job.

• PlannedStartDate

  • DataType: date

  • Required: false

  • Purpose: Sets the PlannedStartDate of the Job.

• PlannedEndDate

  • DataType: date

  • Required: false

  • Purpose: Sets the PlannedEndDate of the Job.

• 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>
        },
        ....
      ]
    }
  }