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(,)

Account Type

URI

api/v2/public/AccountTypes

Supported Verbs

• GET
  • Find Account Types.

Data Models

Account Type Model

{
    "Id": <GUID>,
    "Name": <string>,
    "IsCustomer": <boolean>,
    "IsAgent": <boolean>,
    "IsCompetitor": <boolean>
}

Account Type Fields

• Id

  • DataType: Guid

  • Purpose: To uniquely identify an account type.

• Name

  • DataType: string [max. 200 char]

  • Filterable: true

  • Purpose: Specifies the name of an account type.

• IsCustomer

  • DataType: Boolean

  • Required: false

  • Purpose: when true, accounts will be shown in the Customer list on an order.

• IsAgent

  • DataType: Boolean

  • Required: false

  • Purpose: when true, accounts will be shown in the Agent list on an order.

• IsCompetitor

  • DataType: Boolean

  • Required: false

  • Purpose: when true, accounts will be shown in the Awarded To list on an order with the accounts that belong to your own companies.

Error Model

{
    "ErrorCode": <integer>,
    "ErrorMessage": <string>
}

Error Model Fields

• ErrorCode

  • DataType: integer

  • Purpose: An integer that uniquely identifies this type of error.

• ErrorMessage

  • DataType: string

  • Purpose: A message which describes what the error means.

Find Account Types

URI

GET api/v2/public/AccountTypes

Example Usage

GET api/v2/public/AccountTypes

Required Parameters

• None

Optional Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Default Value: 1

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

  • Example Usage:

    GET api/v2/public/AccountTypes?page=2
  

• $filter:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: empty

  • Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.

  • Example Usage:

    // Get Account Types with Name equal to "Agent"
    GET api/v2/public/AccountTypes?$filter=Name eq 'Agent'
    

Return Value

Action Accepted

Returns an array containing the requested Account Types in the format of the Account Types Model.

{
    "Page": <integer>,
    "Next": <URI>,
    "Results": <Array of Account Type Model>
}

Action Rejected

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

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

Required Permissions

Either one of:

• Setup > Jobs > Sales > Read
• Setup > Jobs > Sales > Edit

Activities

Create/Update Activity

URI

api/v1/core/activities/CreateOrUpdateActivity

Supported Verbs

• POST: insert or update an Activity.

Required Parameters

• Activity Model

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

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Activity Model to be created.

Data Model

Activity Model

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

Activity Object Fields

• Id

  • DataType: Guid

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

  • Purpose: Update the uniquely matching Activity

• VesselId

  • DataType: Guid for the Activity’s vessel.

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

  • Purpose: Sets the Activity’s vessel.

• ActivityTypeId

  • DataType: Guid for the Activity type.

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

  • Purpose: Sets the Activity type.

• FromLocationId

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

  • Required: false

  • Purpose: Sets the Activity’s Location From.

• ToLocationId

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

  • Required: false

  • Purpose: Sets the Activity’s Location To.

• PlannedStartDate

  • DataType: date

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

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

• PlannedEndDate

  • DataType: date

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

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

• StartDate

  • DataType: date

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

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

• EndDate

  • DataType: date

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

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

• RecordedByPersonId

  • DataType: Guid for the Activity Recorded By Person.

  • Required: false

  • Purpose: Sets who recorded the Activity.

• UserDefined

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

  • Required: false

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

Return Value

Action Accepted

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

• Id: Guid for the new Activity.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

• Details Additional information about the error.

Action Rejected

  "Data": <Array>

• Data: Error Message

Find Activities

URI

api/v1/core/activities/FindActivities

Supported Verbs

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

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

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

  • Example Usage:

    api/v1/core/activities/FindActivities?page=1
  

Optional Parameters

• Id:

  • Data Type: Guid

  • Parameter Type: query string

  • Default Value: null

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

  • Example Usage:

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

• VesselId:

  • Data Type: Guid

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return Activities with the given VesselId

  • Example Usage:

    api/v1/core/activities/FindActivities?page=1&VesselId=d21d73fb-bb69-11e8-8102-00155d040945
  

• ChangedSince:

  • Data Type: datetime

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return activities that have been modified or created since the datetime.

  • Example Usage

    api/v1/core/activities/FindActivities?page=1&ChangedSince=2016-03-10T14:23:00-08:00
  

Return Value

With no results

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

With results

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

Archive Activity

URI

api/v1/core/activities/ArchiveActivity

Supported Verbs

• POST: Archive an activity.

Required Parameters

• Archive Activity Model

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

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Activity Id to be archived.

Data Model

Archive Activity Model

  {
    "Id": <Guid>
  }

Archive Activity Object Fields

• Id

  • DataType: Guid

  • Required: true

  • Purpose: Archives the uniquely matching Activity

Return Value

Action Accepted

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

• ActionType: Will always be ‘Archive’.

• Id: Guid for the Activity.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

Action Rejected

  "Data": <Array>

• Data: Error Message

Create/Update Job Activity

URI

api/v1/jobs/activities/CreateOrUpdateJobActivity

Supported Verbs

• POST: insert or update a job activity.

Required Parameters

• Job Activity Model

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

  • Parameter Type: request body

  • Default Value: none

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

Data Model

Job Activity Model

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

Job Activity Object Fields

• Id

  • DataType: Guid

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

  • Purpose: Update the uniquely matching Job Activity

• JobId

  • DataType: Guid for the Activity’s job.

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

  • Purpose: Sets the Activity’s job.

• ActivityTypeId

  • DataType: Guid for the Activity type.

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

  • Purpose: Sets the Activity type.

• FromLocationId

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

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

• 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
  

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

Activity Type

URI

api/v2/public/ActivityTypes

Supported Verbs

• GET
  • Find Activity Types.

Data Models

Activity Type Model

{
    "Id": <GUID>,
    "Name": <string>,
    "AccountingCode": <string>,
    "Type": <string>,
    "Tags": <Array>
    [
        {
            "Id": <GUID>,
            "Name": <string>,
        },
        ...
    ]
}

Activity Type Fields

• Id

  • DataType: Guid

  • Purpose: To uniquely identify an activity type.

• Name

  • DataType: string [max. 200 char]

  • Filterable: true

  • Purpose: Specifies the name of an activity type.

• AccountingCode

  • DataType: string [max. 50 char]

  • Filterable: true

  • Purpose: Specifies the name of an activity type.

• Type

  • DataType: string

  • Filterable: true

  • Purpose: If not null, indicates whether the activity type is “Primary”, “RunningFrom”, or “RunningTo”.

• Tags

  • DataType: Array

  • Purpose: Defines the tags this activity type has.

  • Fields:

    • Id <GUID>
    • Name <string>

Error Model

{
    "ErrorCode": <integer>,
    "ErrorMessage": <string>
}

Error Model Fields

• ErrorCode

  • DataType: integer

  • Purpose: An integer that uniquely identifies this type of error.

• ErrorMessage

  • DataType: string

  • Purpose: A message which describes what the error means.

Find Activity Types

URI

GET api/v2/public/ActivityTypes

or

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

Example Usage

// Get a paginated response of all activity types
GET api/v2/public/ActivityTypes

// Get a specific activity type by Id
GET api/v2/public/ActivityTypes/d21d73fb-bb69-11e8-8102-00155d040945

Required Parameters

• None

Optional Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Default Value: 1

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

  • Example Usage:

    GET api/v2/public/ActivityTypes?page=2
  

• $filter:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: empty

  • Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.

  • Example Usage:

    // Get Activity Types with Name equal to "Sailing"
    GET api/v2/public/ActivityTypes?$filter=Name eq 'Sailing'
    

Return Value

Action Accepted

Returns an array containing the requested Activity Types in the format of the Activity Types Model.

{
    "Page": <integer>,
    "Next": <URI>,
    "Results": <Array of Activity Type Model>
}

Action Rejected

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

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

Required Permissions

• Setup > Events > Activity Types

Assets

Update Asset

URI

api/v1/core/assets/CreateOrUpdateAsset

Supported Verbs

• POST: update an asset

Required Parameters

• Asset Model

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

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Asset Model to be updated.

Data Model

Asset Model

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

Asset Object Fields

• Id

  • DataType: GUID

  • Required: true

  • Purpose: Identify the asset to update

• Name

  • DataType: string [max. 400 char]

  • Required: false

  • Purpose: Sets the Name for the Asset.

• ShortName

  • DataType: string [max. 100 char]

  • Required: false

  • Purpose: Sets the ShortName for the Asset.

• AccountingCode

  • DataType: string [max. 50 char]

  • Required: false

  • Purpose: Sets the AccountingCode for the Asset.

• UserDefined

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

  • Required: false

  • Purpose: Sets the UserDefined fields for the Asset.

Return Value

Action Accepted

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

• ActionType: Insert (Not implemented) or Update

• Id: Guid of the updated Asset

Find Assets

URI

api/v1/core/assets/FindAssets

Supported Verbs

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

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

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

  • Example Usage:

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

Optional Parameters

• Name:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

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

  • Example Usage:

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

• ShortName:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

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

  • Example Usage:

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

• AccountingCode:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

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

  • Example Usage:

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

Return Value

With no results

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

With results

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

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 User Defined Fields 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>,
            "Details": <string>
          },
          ....
        ]
      }
    ]
  }

Without errors

  {
    "Data":
    {
      "Created": <Integer>,
      "Updated": <Integer>
    }
  }

• Created: The number of Companies created.

• Updated: The number of Companies updated.

Create/Update Account

URI

api/v1/jobs/companies/CreateOrUpdateCompanyAccount

Supported Verbs

• POST: insert and update one or more Company accounts.

Required Parameters

• Account Model

  • Data Type: Array of JSON Objects (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one or more Account Model to be created or update.

Optional Parameters

• addNewCompany

  • Data Type: boolean

  • Parameter Type: query string

  • Default Value: false

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

  • Note: Company’s Name is required when creating New Company

  • Example Usage:

    api/v1/jobs/companies/CreateOrUpdateCompanyAccount?addNewCompany=true
  

• asRequest

  • Data Type: boolean

  • Parameter Type: query string

  • Default Value: false

  • Purpose: When true, instead of creating or updating an Account directly, a Request for those changes will be created. This creates new request Accounts which are referenced by the Requests that were created. Requested accounts will have the RequestedOn field set to the current datetime.

  • Example Usage:

    api/v1/jobs/companies/CreateOrUpdateCompanyAccount?asRequest=true
  

Data Model

Account Model

  [
    {
      "Id": <GUID>,
      "Name": <string>,
      "Company":
      {
        "Id": <GUID>,
        "Name": <string>,
        "ShortName": <string>,
        "ExternalSystemCode": <string>,
        "IsMyCompany": <boolean>,
        "IsActive": <boolean>,
        "UserDefined":User Defined Data Model (see User Defined Fields section for more details)
      },
      "Division":
      {
        "Id": <GUID>,
        "Name": <string>,
        "ExternalSystemCode": <string>
      },
      "AccountNumber": <string>,
      "AccountType": <string>,
      "AccountTypeId": <GUID>,
      "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.

• AccountTypeId

  • DataType: Guid

  • Required: true when AccountType is not set

  • Purpose: Sets the AccountTypeId for the Account.

• IsAR

  • DataType: boolean

  • Required: false

  • Default value: true

  • Purpose: Sets the IsAR for the Account.

• IsAP

  • DataType: boolean

  • Required: false

  • Default value: false

  • Purpose: Sets the IsAP for the Account.

• IsBlocked

  • DataType: boolean

  • Required: false

  • Default value: false

  • Purpose: Sets the IsBlocked for the Account.

• IsActive

  • DataType: boolean

  • Required: false

  • Default value: true

  • Purpose: Sets the IsActive for the Account.

Return Value

With errors

  {
    "Data":
    [
      {
        "Name": <Array>,
        "Errors":
        [
          {
            "Entity": <string>
          },
          ....
        ]
      }
    ]
  }

Without errors

  {
    "Data":
    {
      "Created": <Integer>,
      "Updated": <Integer>,
      "CompanyCreated": <Integer>
    }
  }

• Created: The number of Company Accounts created.

• Updated: The number of Company Accounts updated.

• CompanyCreated: The number of Companies created.

Create/Update Account Address

URI

api/v1/jobs/companies/CreateOrUpdateAccountAddress

Supported Verbs

• POST: insert and update one or more Account Addresses.

Required Parameters

• Account Address Model

  • Data Type: Array of JSON Objects (See Data Model for details)

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one or more Account Address Model to be created or updated.

Data Model

Account Address Model

  [
    {
      "Id": <GUID>,
      "Account":
      {
        "Id": <GUID>,
        "Name": <string>,
        "AccountNumber": <string>
      },
      "Name": <string>,
      "Address": <string>,
      "City": <string>,
      "Zipcode": <string>,
      "State": <string>,
      "Country": <string>,
      "Email": <string>,
      "ExternalSystemCode": <string>,
      "Areas":
      [
        {
          "Id": <GUID>,
          "Name": <string>,
          "ExternalSystemCode": <string>
        },
        ....
      ]
    },
    ....
  ]

Account Address Object Fields

• Id

  • DataType: Guid

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

  • Purpose: update the uniquely matching Account Address.

• Account

  • DataType: JSON Object

  • Required: true

  • Purpose: Sets the Account of the Account Address.

  • Function: Selects the Account that uniquely matches the given fields.

  • Fields:

    • Id <GUID>

    • Name <string>

    • AccountNumber <string>

• Name

  • DataType: string

  • Required: false

  • Purpose: Sets the Name for the Account Address. Will be set to null if not specified.

• Address

  • DataType: string

  • Required: true

  • Purpose: Sets the Address for the Account Address.

• City

  • DataType: string

  • Required: true

  • Purpose: Sets the City for the Account Address.

• Zipcode

  • DataType: string

  • Required: false

  • Purpose: Sets the Zipcode for the Account Address. Will be set to null if not specified.

• State

  • DataType: string

  • Required: false

  • Purpose: Sets the State for the Account Address. Will be set to null if not specified.

• Country

  • DataType: string

  • Required: true

  • Purpose: Sets the Country for the Account Address.

• Email

  • DataType: string

  • Required: false

  • Purpose: Sets the Email for the Account Address. Will be set to null if not specified.

• ExternalSystemCode

  • DataType: string

  • Required: false

  • Purpose: Sets the ExternalSystemCode for the Account Address. Will be set to null if not specified.

• Areas

  • DataType: Array of JSON Objects

  • Required: false

  • Purpose: Sets the Areas for the Account Address. Will be set to null if not specified.

  • Fields:

    • Id <GUID>

    • Name <string>

    • AccountNumber <string>

Return Value

With errors

  {
    "Data":
    [
      {
        "Name": <Array>,
        "Errors":
        [
          {
            "Entity": <string>
          },
          ....
        ]
      }
    ]
  }

Without errors

  {
    "Data":
    {
      "Created": <Integer>,
      "Updated": <Integer>
    }
  }

• Created: The number of Company Accounts created.

• Updated: The number of Company Accounts updated.

Find Companies

URI

api/v1/jobs/companies/FindCompanies

Supported Verbs

• GET: return a filtered list of Companies, Account, and Account Address. The data is returned by page (see below).

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

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

  • Example Usage:

    api/v1/jobs/companies/FindCompanies?page=2
  

Optional Parameters

• SearchString:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the Companies with Name or ShortName that contains the given string.

  • Example Usage:

    api/v1/jobs/companies/FindCompanies?page=1&SearchString=partOfTheName
  

• CompanyExternalSystemCode:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the Companies with the specified external system code.

  • Example Usage:

    api/v1/jobs/companies/FindCompanies?page=1&CompanyExternalSystemCode=CustomerXYZ
  

• AccountNumber:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the Companies that contain accounts with the specified account number. Any accounts that do not have the specified account number will be omitted.

  • Example Usage:

    api/v1/jobs/companies/FindCompanies?page=1&AccountNumber=Account12345
  

Return Value

With no results

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

With results

  {
    "Data":
    {
      "TotalCount": <integer>,
      "Page": <Array>
      [
        {
          "Id": <GUID>,
          "Name": <string>,
          "ShortName": <string>,
          "ExternalSystemCode": <string>,
          "IsMyCompany": <boolean>,
          "IsActive": <boolean>,
          "UserDefined": User Defined Data Model (see User Defined Fields section for more details),
          "AccountingTerm":
          {
            "Name": <string>,
            "NumberOfDays": <integer>,
            "ExternalSystemCode": <string>
          },
          "Accounts": <Array>
          [
            {
              "Id": <GUID>,
              "Name": <string>,
              "Division":
              {
                "Id": <GUID>,
                "Name": <string>,
                "ExternalSystemCode": <string>
              },
              "AccountNumber": <string>,
              "AccountType": <string>,
              "AccountTypeId": <GUID>,
              "IsAR": <boolean>,
              "IsAP": <boolean>,
              "IsBlocked": <boolean>,
              "IsActive": <boolean>,
              "IsRequested": <boolean>,
              "AccountingTerm":
              {
                "Name": <string>,
                "NumberOfDays": <integer>,
                "ExternalSystemCode": <string>
              },
              "Addresses": <Array>
              [
                {
                  "Id": <GUID>,
                  "Name": <string>,
                  "Address": <string>,
                  "City": <string>,
                  "Zipcode": <string>,
                  "State": <string>,
                  "Country": <string>,
                  "Email": <string>,
                  "Areas":
                  [
                    {
                      "Id": <GUID>,
                      "Name": <string>,
                      "ExternalSystemCode": <string>
                    },
                    ....
                  ]
                },
                ....
              ]
            },
            ....
          ]
        },
        ....
      ]
    }
  }

Currency Exchange Rate

Create/Update Currency Exchange Rate

URI

api/v1/jobs/billing/CreateOrUpdateCurrencyExchangeRate

Supported Verbs

• POST: insert or update a currency exchange rate.

Required Parameters

• Currency Exchange Rate Model

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

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Currency Exchange Rate Model to be created or updated.

Data Model

Currency Exchange Rate Model

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

Currency Exchange Rate Object Fields

• CurrencyType

  • DataType: JSON Object

  • Required: true

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

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

  • Fields:

    • Id <GUID>

    • Name <string> [max. 200 char]

• EffectiveDate

  • DataType: <date>

  • Required: true

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

• ExchangeRate

  • DataType: <decimal>

  • Required: true

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

Return Value

Action Accepted

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

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

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

Action Rejected

  "Data": <Array>

• Data: Log Messages

Delete Currency Exchange Rate

URI

api/v1/jobs/billing/DeleteCurrencyExchangeRate

Supported Verbs

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

Required Parameters

• User Model

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

  • Parameter Type: request body

  • Default Value: none

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

Data Model

Currency Exchange Rate Model

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

User Object Fields

• CurrencyType

  • DataType: JSON Object

  • Required: true

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

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

  • Fields:

    • Id <GUID>

    • Name <string> [max. 200 char]

• EffectiveDate

  • DataType: <date>

  • Required: true

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

Return Value

Action Accepted

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

• CurrencyTypeId: Guid for the currency type that exchange rate(s) may have been deleted for.

• ExchangeRatesDeleted: The number of exchange rates that were deleted.

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

Action Rejected

  "Data": <Array>

• Data: Log Messages

Divisions

Find Divisions

URI

api/v1/jobs/Divisions/FindDivisions

Supported Verbs

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

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

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

  • Example Usage:

    api/v1/jobs/Divisions/FindDivisions?page=2
  

Optional Parameters

• SearchString:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: null

  • Purpose: Will return the Divisions with Name or ShortName that contains the given string.

  • Example Usage:

    api/v1/jobs/Divisions/FindDivisions?page=1&SearchString=partOfTheName
  

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
  

• ChangedSince:

  • Data Type: datetime

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return events that have been modified or created since the datetime.

  • Example Usage

    api/v1/core/events/FindEvents?page=1&ChangedSince=2016-03-10T14:23:00-08:00
  

Return Value

With no results

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

With results

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

Archive Event

URI

api/v1/core/events/ArchiveEvent

Supported Verbs

• POST: Archive an event.

Required Parameters

• Archive Event Model

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

  • Parameter Type: request body

  • Default Value: none

  • Purpose: Supplies one Event Id to be archived.

Data Model

Archive Event Model

  {
    "Id": <Guid>
  }

Archive Event Object Fields

• Id

  • DataType: Guid

  • Required: true

  • Purpose: Archives the uniquely matching Event

Return Value

Action Accepted

  {
    "ActionType": "Archive",
    "Id": <GUID>
  }

• ActionType: Will always be ‘Archive’.

• Id: Guid for the Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

Action Rejected

  "Data": <Array>

• Data: Error Message

Create/Update Trip Event

URI

api/v1/jobs/events/CreateOrUpdateTripEvent

Supported Verbs

• POST: insert or update a trip event.

Required Parameters

• Trip Event Model

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

  • Parameter Type: request body

  • Default Value: none

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

Data Model

Trip Event Model

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

Trip Event Object Fields

• Id

  • DataType: Guid

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

  • Purpose: Update the uniquely matching Trip Event

• TripId

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

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

  • Purpose: Sets the Trip Event’s trip.

• EventTypeId

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

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

  • Purpose: Sets the Event type.

• Description

  • DataType: string

  • Required: false

  • Purpose: Sets the description for the Trip Event.

• EventDate

  • DataType: date

  • Required: false

  • Purpose: Sets the Trip Event’s date.

• LocationId

  • DataType: Guid

  • Required: false

  • Purpose: Sets the Trip Event’s location.

• UserDefined

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

  • Required: false

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

Return Value

Action Accepted

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

• ActionType: ‘Insert’ or ‘Update’.

• Id: Guid for the Trip Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

• Details: Additional information about the error.

Action Rejected

  "Data": <Array>

• Data: Error Message

Find Trip Events

URI

api/v1/jobs/events/FindTripEvents

Supported Verbs

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

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return. page=1, would return the first batch of results, page=2 would return the second batch of results, and so on. Each batch contains 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
  

• ChangedSince:

  • Data Type: datetime

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return Trip Events that have been modified or created since the datetime.

  • Example Usage

    api/v1/jobs/events/FindTripEvents?page=1&ChangedSince=2016-03-10T14:23:00-08:00
  

Return Value

With no results

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

With results

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

Create/Update Job Event

URI

api/v1/jobs/events/CreateOrUpdateJobEvent

Supported Verbs

• POST: insert or update a Job Event.

Required Parameters

• Job Event Model

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

  • Parameter Type: request body

  • Default Value: none

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

Data Model

Job Event Model

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

Job Event Object Fields

• Id

  • DataType: Guid

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

  • Purpose: Update the uniquely matching Job Event

• JobId

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

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

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

• EventTypeId

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

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

  • Purpose: Sets the Event type.

• Description

  • DataType: string [max. 1000 char]

  • Required: false

  • Purpose: Sets the description for the Job Event.

• PlannedEventDate

  • DataType: date

  • Required: false

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

• EventDate

  • DataType: date

  • Required: false

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

• LocationId

  • DataType: Guid for the Location

  • Required: false

  • Purpose: Sets the Job Event’s location.

• RecordedByPersonId

  • DataType: Guid for the Recorded By Person

  • Required: false

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

• UserDefined

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

  • Required: false

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

Return Value

Action Accepted

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

• Id: Guid for the Job Event.

• ErrorMsgs: Fields that have issues.

• Entity: name of the Field

• Message: Error message

• Details: Additional information about the error.

Action Rejected

  "Data": <Array>

• Data: Error Message

Find Job Events

URI

api/v1/jobs/events/FindJobEvents

Supported Verbs

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

Required Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Purpose: Controls the pagination of the returned data. The value of page is the offset of results to return. page=1, would return the first batch of results, page=2 would return the second batch of results, and so on. Each batch contains 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
  

• ChangedSince:

  • Data Type: datetime

  • Parameter Type: query string

  • Default Value: null

  • Purpose: When not null, will return job events that have been modified or created since the datetime.

  • Example Usage

    api/v1/jobs/events/FindJobEvents?page=1&ChangedSince=2016-03-10T14:23:00-08:00
  

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

Event Type

URI

api/v2/public/EventTypes

Supported Verbs

• GET
  • Find Event Types.

Data Models

Event Type Model

{
    "Id": <GUID>,
    "Name": <string>,
    "Spaces": <Array>
    [
        {
            "Id": <GUID>,
            "Name": <string>,
        },
        ...
    ],
    "Tags": <Array>
    [
        {
            "Id": <GUID>,
            "Name": <string>,
        },
        ...
    ]
}

Event Type Fields

• Id

  • DataType: Guid

  • Purpose: To uniquely identify an event type.

• Name

  • DataType: string [max. 200 char]

  • Filterable: true

  • Purpose: Specifies the name of an event type.

• Spaces

  • DataType: Array

  • Purpose: Defines the spaces this event type is visible in.

  • Fields:

    • Id <GUID>
    • Name <string>

• Tags

  • DataType: Array

  • Purpose: Defines the tags this event type has.

  • Fields:

    • Id <GUID>
    • Name <string>

Error Model

{
    "ErrorCode": <integer>,
    "ErrorMessage": <string>
}

Error Model Fields

• ErrorCode

  • DataType: integer

  • Purpose: An integer that uniquely identifies this type of error.

• ErrorMessage

  • DataType: string

  • Purpose: A message which describes what the error means.

Find Event Types

URI

GET api/v2/public/EventTypes

or

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

Example Usage

// Get a paginated response of all event types
GET api/v2/public/EventTypes

// Get a specific event type by Id
GET api/v2/public/EventTypes/d21d73fb-bb69-11e8-8102-00155d040945

Required Parameters

• None

Optional Parameters

• page:

  • Data Type: integer

  • Parameter Type: query string

  • Default Value: 1

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

  • Example Usage:

    GET api/v2/public/EventTypes?page=2
  

• $filter:

  • Data Type: string

  • Parameter Type: query string

  • Default Value: empty

  • Purpose: Controls filtering the returned data. See fields that have “Filterable: true”.

  • Example Usage:

    // Get Event Types with Name equal to "Drill"
    GET api/v2/public/EventTypes?$filter=Name eq 'Drill'
    

Return Value

Action Accepted

Returns an array containing the requested Event Types in the format of the Event Types Model.

{
    "Page": <integer>,
    "Next": <URI>,
    "Results": <Array of Event Type Model>
}

Action Rejected

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

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

Required Permissions

• Setup > Events > Event Types

Emergency Contacts

URI

api/v2/public/EmergencyContacts

Supported Verbs

• GET

  • Find emergency contacts

• POST

  • Create new emergency contacts

• PATCH

  • Update existing emergency contacts

• DELETE

  • Remove existing emergency contacts

Data Models

Emergency Contact Model

{
    "Id": <GUID>,
    "PersonId": <GUID>,
    "Name": <string>,
    "PhoneNumber": <string>,
    "AlternatePhoneNumber": <string>,
    "EmailAddresses": <string>,
    "Relationship": <string>,
    "Address": <string>,
    "City": <string>,
    "Country": <string>,
    "StateOrProvince": <string>,
    "PostalZipCode": <string>,
    "SortOrder": <integer>,
    "UserDefinedFields": User Defined Data Model (see User Defined Fields section for more details)
}

Emergency Contact Fields

• Id

  • Data Type: Guid

  • Required: False when using POST to create. True when using PATCH to update or DELETE to delete (unless Id is already specified in the URI).

  • Purpose: To uniquely identify an Emergency Contact and to specify which Emergency Contact to apply an operation to.

• PersonId

  • Data Type: Guid

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

  • Filterable: True

  • Purpose: Specifies the person this emergency contact is for. Cannot be PATCHed.

• Name

  • Data Type: string [max. 300 char]

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

  • Filterable: True

  • Purpose: Specifies the name of the emergency contact.

• PhoneNumber

  • Data Type: string [max. 50 char]

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

  • Filterable: True

  • Purpose: Specifies the primary phone number of the emergency contact.

• AlternatePhoneNumber

  • Data Type: string [max. 50 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies an alternative phone number of the emergency contact.

• EmailAddresses

  • Data Type: string [max. 1000 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies a comma-separated list of email addresses of the emergency contact. The maximum length includes comma characters.

• Relationship

  • Data Type: string [max. 200 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the relationship of the emergency contact to the person. Eg: Wife, girlfriend, husband, mother, etc.

• Address

  • Data Type: string [max. 1000 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the address line of the emergency contact. Eg: 1600 Pennsylvania Avenue NW.

• City

  • Data Type: string [max. 200 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the city the emergency contact lives in.

• Country

  • Data Type: string [max. 200 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the country the emergency contact lives in.

• StateOrProvince

  • Data Type: string [max. 200 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the state or province the emergency contact lives in.

• PostalZipCode

  • Data Type: string [max. 20 char]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the postal or zip code of the emergency contact.

• SortOrder

  • Data Type: integer [min: 0]

  • Required: False

  • Filterable: True

  • Purpose: Specifies the order of the emergency contact in the list of contacts for the person. If there is a collision between two contact’s SortOrder, then the updated one is used. If both are updated, they are processed in the order sent in the request body. The contact is appended if the SortOrder is too large.

  • Default Value: 0

• UserDefinedFields

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

  • Required: False

  • Purpose: Specifies the User Defined Fields of the emergency contact.

  • Default Value: null