Description 

The Shoreline Execution API provides a fast, automated way to import and export account data. Use the Execution API to retrieve account settings, edit them, and reimport them. 

The Execution API workflow is as follows: 

  1. Request the relevant account settings through a GET request to the relevant endpoint. Body parameters allow you to filter the response. The request is processed asynchronously, so you will receive a correlationId parameter in the response. 
  2. Copy the correlantionId value. 
  3. Append the correlationId value as a query parameter on the GET /export endpoint to retrieve the data. 
  4. Edit the data. 
  5. Submit the edited JSON through the relevant POST endpoint. 

Base URL 

https://ex.shoreline.no/api/ 

Headers 

Authorization header 

Shoreline authenticates calls with OAuth2 HTTP bearer tokens. 

When you make an API call, use an Authorization HTTP header to provide your API key, with a Bearer prefix. For example: Authorization: Bearer {API_KEY} 

You can retrieve an API key using the POST /authenticate endpoint. 

Contact your account administrator if you require API access. 

Endpoints 

POST /authenticate 

Use basic auth to authenticate and retrieve a JWT token. Use this token to authenticate your requests. 

Body parameters

ParameterTypeRequiredDescription
usernamestringxYour Shoreline Execution account username
passwordstringxYour Shoreline Execution account password

Response

Returns a JSON object with the following properties: 

  • token: Your API key to validate requests. 

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/authenticate' \ 
  -H 'accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "username": "{USERNAME}", 
  "password": "{PASSWORD}" 
}' 

Response

{ 
  "token": "{API_KEY}" 
} 

POST /export/activities 

Request an export of activities. Use filters in the request body to narrow down your export. 

Body parameters 

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrlstring
URL for sending the account data to once the request is completed.
workPackagesarray
A list of work package IDs.
workOrdersarray
A list of work order IDs.
sitesarray
A list of site IDs.
assetsarray
A list of assets IDs.
namesarray
A list of activity names.
activitiesarray
A list of activity IDs.
startDatedate
UTC timestamp. Activities that start on or after the start date are included.
endDatedate
UTC timestamp. Activities that end on or after the end date are included.
statusesenum
An array of activity statuses. Either PLANNED, DISPATCHED, or COMPLETED.
changedSincedate
UTC timestamp. Activities modified since the given date are included.

Response

Returns a JSON object with the following properties:

  • correlationId: A unique ID for your request.

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/activities' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}" 

  "workPackages": [ 

    "WP1", 

    "WP2", 

    "WP3" 

  ], 

  "workOrders": [ 

    "WO1", 

    "WO2", 

    "WO3" 

  ], 

  "sites": [ 

    "S1", 

    "S2", 

    "S3" 

  ], 

  "assets": [ 

    "A1", 

    "A2", 

    "A3" 

  ], 

  "changedSince": "2023-05-02T12:04:53.313Z" 
}' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

GET /import/status 

Request the status of an import. 

Query parameters 

ParameterTypeRequiredDescription
correlationIdstringxA unique ID for your import request. Returned in the request response. 

Response

Returns a JSON object detailing the import status of your activities. 

Example

Request

curl -X 'GET' \ 
  'https://ex.shoreline.no/public/v1/import/status?correlationId={CORRELATION_ID}' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' 

Response

{ 
  "correlationId": "{CORRELATION_ID}", 
  "total": 1, 
  "processed": 1, 
  "created": 0, 
  "updated": 0, 
  "failed": 1, 
  "deleted": 0, 
  "messages": [ 
    "Failed to process row 1: No site found with ID: S01, make sure the site ID is correct." 
  ] 
} 

GET /import/result

Request the result of an import. 

Query parameters 

ParameterTypeRequiredDescription
correlationIdstringxA unique ID for your import request. Returned in the request response.

Response

Returns a JSON object comprising 3 arrays: created, updated, and failed.

Example

Request

curl -X 'GET' \ 
  'https://ex.shoreline.no/public/v1/import/result?correlationId={CORRELATION_ID}' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' 

Response

{ 
  "created": [], 
  "updated": [], 
  "failed": [ 
    { 
      "index": 0, 
      "activity": { 
        "id": "ACT-EXT-ID-1", 
        "siteId": "S01", 
        "assetId": "EXT-AS-ID-WTG-01", 
        "subassemblyId": "", 
        "componentId": "", 
        "startDate": "02/02/2023", 
        "startTime": "08:15", 
        "endDate": "04/04/2023", 
        "endTime": "08:15", 
        "activityCategory": "Service", 
        "type": "", 
        "status": "DISPATCHED", 
        "workPackageId": "WO-PKG-1", 
        "additionalClientWork": "true", 
        "voNumber": "", 
        "voAgreedWith": "", 
        "voSigned": "", 
        "workOrderId": "wO1", 
        "teams": "Service team 1,Service team 2", 
        "personnelIds": "P1,P2,P3", 
        "manpower": "Service team 1:2,Service team 2:1,Service team 3:3", 
        "internalRemarks": "activity created for inspection of wtg", 
        "externalRemarks": "activity created for inspection of wind turbine generator", 
        "dropOffTransportId": "", 
        "pickupTransportId": "", 
        "isLocked": "" 
      }, 
      "message": "Failed to process row 0: No site found with ID: S01, make sure the site ID is correct." 
    } 
  ] 

GET /import/failed

Query parameters

ParameterTypeRequiredDescription
correlationIdstringxA unique ID for your import request. Returned in the request response. 

Response

Returns a JSON object containing the activities that failed to import. If all activities successfully imported, the response will be empty. 

Example

Request

curl -X 'GET' \ 
  'https://ex.shoreline.no/public/v1/import/activities/failed?correlationId={CORRELATION_ID}' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' 

Response

[ 
  { 
    "id": "ACT-Example8383838775", 
    "siteId": "Example site", 
    "assetId": "A01", 
    "subassemblyId": "", 
    "componentId": "", 
    "startDate": "13/03/2024", 
    "startTime": "13:04", 
    "endDate": "28/03/2024", 
    "endTime": "13:04", 
    "activityCategory": "Office work", 
    "type": "", 
    "status": "DISPATCHED", 
    "workPackageId": "", 
    "additionalClientWork": "", 
    "voNumber": "", 
    "voAgreedWith": "", 
    "voSigned": "", 
    "workOrderId": "", 
    "teams": "", 
    "personnelIds": "", 
    "manpower": "", 
    "internalRemarks": "", 
    "externalRemarks": "", 
    "dropOffTransportId": "", 
    "pickupTransportId": "", 
    "isLocked": "" 
  } 
] 

POST /import/activities 

Import activities to a project. Provide activity details in JSON format in the request body.

Query parameters 

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.

Body parameters

ParameterTypeRequiredDescription
idstringxA unique activity ID.
siteIdstringxThe site ID to which the activity relates.
assetIdstring
The asset ID to which the activity relates.
startDatedate
UTC timestamp. When the activity begins.
endDatedate
UTC timestamp. When the activity ends.
activityCategorystring
The activity category to which the activity belongs.
statusenum
An array of activity statuses. Either PLANNED, DISPATCHED, or COMPLETED.
workPackageIdstring
The work package to which the activity belongs.
additionalClientWorkboolean
Boolean value for activity entity.
workOrderIdstring
The work order ID to which the activity belongs.
teamsarray
A list of team names to which the activity relates.
personnelIdsarray
A list of personnel IDs to which the activity relates.
manpowerjson

JSON object for the teams (string) and manpower (integer). 

The key is the team name; the value is the manpower. For example, { “Team 1”: 5, “Team 2”: 10 }

internalRemarksstring
Any internal comments related to the activity.
externalRemarksstring
Any external comments related to the activity.

Response

Returns a JSON object with the following properties: 

  • correlationId: A unique ID for your request. 

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/import/activities?projectId={PROJECT_ID}' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '[ 
  { 
    "id": "ACT-example12345", 
    "siteId": "Example site", 
    "assetId": "G01", 
    "startDate": "2024-03-13T13:04:12Z", 
    "endDate": "2024-03-28T13:04:12Z", 
    "activityCategory": "Office work", 
    "status": "DISPATCHED" 
  } 
]' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

POST /import/activities/file 

Import activities to a project using a file. Provide activity details in JSON format in the request body.

Query parameters 

ParameterTypeRequiredDescription
correlationIdstringxA unique ID for your import request. Returned in the request response. 

Body parameters

ParameterTypeRequiredDescription
filefilexA JSON file of the activities you want to import

Response

Returns a JSON object with the following properties: 

  • correlationId: A unique ID for your request. 

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/import/activities/file?projectId={PROJECT_ID}' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: multipart/form-data' \ 
  -F 'file=@{FILE_NAME}.json;type=application/json' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

POST /export/activity-categories 

Request an export of activity categories. Use filters in the request body to narrow down your export. 

Body parameters 

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API
callbackUrlstring
URL for sending the account data to once the request is completed.
activityCategoriesarray
A list of activity category IDs.
namesarray
A list of activity names.
workPackagesarray
A list of work package IDs.
changedSincedate
UTC timestamp. Activities modified since the given date are included.

Response

Returns a JSON object with the following properties: 

  • correlationId: A unique ID for your request. 

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/activity-categories' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}", 
  "activityCategories": [ 
    "ACC001", 
    "ACC002", 
    "ACC003" 
  ], 
  "names": [ 
    "Toolbox check", 
    "Additional Work", 
    "Painting Installation" 
  ], 
  "workPackages": [ 
    "WP1", 
    "WP2", 
    "WP3" 
  ], 
  "changedSince": "2023-05-02T12:04:53.313Z" 
}'

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

GET /export

Retrieve the result of an export request.

Query parameters

ParameterTypeRequiredDescription
correlationIdstringxExport request ID.

Response

Returns a JSON object with relevant object properties. 

Example

Request

curl -X 'GET' \ 
  'https://ex.shoreline.no/public/export?correlationId={CORRELATION_ID}' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' 

Response

[ 
  { 
    "startDate": "2024-01-18T09:25:06.259Z", 
    "endDate": "2024-01-18T09:50:00.000Z", 
    "createdAt": "2024-01-18T09:33:14.391Z", 
    "updatedAt": "2024-01-18T09:34:56.767Z", 
    "teams": [], 
    "name": "Office work", 
    "activityCategory": "Office work", 
    "personnelIds": [], 
    "status": "PLANNED", 
    "type": "NONE", 
    "siteId": "{SITE_ID}", 
    "id": "{PROJECT_ID}", 
    "externalRemarks": "" 
  }, 
  { 
    "startDate": "2024-01-25T07:00:00.000Z", 
    "endDate": "2024-01-25T14:00:00.000Z", 
    "createdAt": "2024-01-25T12:51:49.881Z", 
    "updatedAt": "2024-01-25T12:51:49.881Z", 
    "teams": [], 
    "name": "Office work", 
    "activityCategory": "Office work", 
    "personnelIds": [ 
      "1" 
    ], 
    "status": "DISPATCHED", 
    "type": "NONE", 
    "siteId": "{SITE_ID}", 
    "id": "{ACTIVITY_ID}", 
    "externalRemarks": "" 
  }, 
  { 
    "startDate": "2024-01-25T07:00:00.000Z", 
    "endDate": "2024-01-25T15:00:00.000Z", 
    "createdAt": "2024-01-25T12:52:14.914Z", 
    "updatedAt": "2024-01-25T12:52:14.914Z", 
    "teams": [], 
    "name": "Store keeping", 
    "activityCategory": "Store keeping", 
    "personnelIds": [ 
      "1" 
    ], 
    "status": "DISPATCHED", 
    "type": "NONE", 
    "siteId": "{SITE_ID}", 
    "id": "{ACTIVITY_ID}", 
    "externalRemarks": "" 
  }, 
  { 
    "startDate": "2024-01-25T07:00:00.000Z", 
    "endDate": "2024-01-25T16:00:00.000Z", 
    "createdAt": "2024-01-25T12:52:33.666Z", 
    "updatedAt": "2024-01-26T12:23:14.130Z", 
    "teams": [], 
    "name": "Toolbox talk", 
    "activityCategory": "Toolbox talk", 
    "personnelIds": [ 
      "1" 
    ], 
    "status": "DISPATCHED", 
    "type": "NONE", 
    "siteId": "DB", 
    "workPackageId": "{WORK_PACKAGE_ID}", 
    "id": "{ACTIVITY_ID}", 
    "externalRemarks": "" 
  } 
] 

POST /export/personnel

Request an export of personnel. User filters in the request to narrow down your export.

Body parameters

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrlstring
URL for sending the account data to once the request is completed.
namesarray
A list of personnel names.
emailsarray
A list of personnel email addresses.
rolesarray
A list of personnel roles.
departmentsarray
A list of department names.
teamsarray
A list of team names.
workPackagesarray
A list of work package IDs.
changedSincedate
UTC timestamp. Activities modified since the given date are included.

Response

Returns a JSON object with the following properties:

  • correlationId: A unique ID for your request.

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/personnel' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}, 
  "changedSince": "2023-05-02T12:04:53.313Z" 
}' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

POST /export/timesheets

Request an export of timesheets. Use filters in the request body to narrow down your export. 

Body parameters

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackURLstring
URL for sending the account data to once the request is completed.
timesheetsarray
A list of timesheet IDs.
namesarray
A list of timesheet names.
statusesenum
An array of timesheet status, either DRAFT, PENDING, SIGNED, or REJECTED.
dateFromdate
UTC timestamp. Timesheets created on or after the given date are included.
dateTodate
UTC timestamp. Timesheets create on or before the given date are included.
submittedByarray
A list of personnel IDs who submitted the timesheets.
approvedByarray
A list of personnel IDs who approved the timesheets.
changedSincedate
UTC timestamp. Timesheets modified since the given date are included.
timeEntriesarray
A list of time entry IDs.
activitiesarray
A list of activity IDs.
workPackagesarray
A list of work packages IDs.
personnelarray
A list of personnel IDs.

Response

Returns a JSON object with the following properties:

  • correlationId: A unique ID for your request.

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/timesheets' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}", 
  "statuses": [ 
    "DRAFT" 
  ] 
}' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

Post /export/work-order-sequences

Request an export of work order sequences. Use filters in the request body to narrow down your export. 

Body parameters

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrlstring
URL for sending the account data to once the request is completed.
workOrderSequencesarray
A list of work order sequence IDs.
namesarray
A list of work order sequence names.
changedSincedate
UTC timestamp. Work oder sequences modified since the given date are included.

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/work-order-sequences' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}", 
  "workOrderSequences": [ 
    "WO-SEQ-1", 
    "WO-SEQ-2", 
    "WO-SEQ-3" 
  ], 
  "changedSince": "2023-05-02T12:04:53.313Z" 
}' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

POST /export/work-orders

Request an export of work orders. Use filters in the request body to narrow down your export. 

Body parameters

ParameterTypeRequiredDescription
projectIDstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrlstring
URL for sending the account data to once the request is completed.
workOrdersarray
A list of work order IDs.
namesarray
A list of work order names.
typesarray
A list of work order types.
prioritiesarray
A list of work order priorities.
workPackagesarray
A list of work package IDs.
workOrderSequencesarray
A list of work order sequence IDs.
changedSincedate
UTC timestamp. Work orders modified since the given date are included.

Response

Returns a JSON object with the following properties: 

  • correlationId: A unique ID for your request. 

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/work-orders' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}", 
  "workOrders": [ 
    "WO-1", 
    "WO-2", 
    "WO-3" 
  ], 
  "names": [ 
    "Name 1", 
    "Name 2", 
    "Name 3" 
  ], 
  "types": [ 
    "Commissioning", 
    "Decommissioning" 
  ], 
  "changedSince": "2023-05-02T12:04:53.313Z" 
}' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

POST /export/work-packages

Request an export of work packages. User filters in the request body to narrow down your export.

Body parameters

ParameterTypeRequiredDescription
projectIdstringxUnique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrlstring
URL for sending the account data to once the request is completed.
workPackagesarray
A list of work package IDs.
namesarray
A list of work package names.
typesarray
A list of work package types.
statusenum
An array of work package statuses. Either NONE, PLANNED, CONFIRMED, FINISHED, or CANCELED.
countriesarray
A list of countries.
assetTypesarray
A list of asset type names.
startDatedate
UTC timestamp. Work packages that begin on or after the given date are included.
endDatedate
UTC timestamp. Work packages that end on or before the given date are included.
changedSincedate
UTC timestamp. Work packages modified since the given date are included. 

Response

Returns a JSON object with the following properties:

  • correlationId: A unique ID for your request.

Example

Request

curl -X 'POST' \ 
  'https://ex.shoreline.no/public/v1/export/work-packages' \ 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer {API_KEY}' \ 
  -H 'Content-Type: application/json' \ 
  -d '{ 
  "projectId": "{PROJECT_ID}", 
  "workPackages": [ 
    "WP1", 
    "WP2", 
    "WP3" 
  ], 
  "names": [ 
    "Name 1", 
    "Name 2", 
    "Name 3" 
  ], 
  "statuses": [ 
    "NONE" 
  ], 
  "countries": [ 
    "Denmark", 
    "Germany" 
  ], 
  "assetTypes": [ 
    "Wind Turbine Foundation", 
    "Cable", 
    "Generator" 
  ], 
  "startDate": "2023-05-02T12:04:53.313Z", 
  "endDate": "2023-05-02T12:04:53.313Z", 
  "changedSince": "2023-05-02T12:04:53.313Z" 
}' 

Response

{ 
  "correlationId": "1234567a-890b-123c-d45e-678f901234567" 
} 

Errors

If the request is not successful, the API returns JSON containing the relevant error code. Shoreline uses the following error codes: 

  • 400 Bad Request: The request was malformed or missing required parameters. 
  • 401 Unauthorized: The API key provided was invalid or missing. 
  • 404 Not Found: The requested resource was not found. 
  • 500 Internal Server Error: An unexpected error occurred on the server.