API reference

Modified on Tue, 28 May 2024 at 02:55 PM

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:

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.
Copy the correlantionId value.
Append the correlationId value as a query parameter on the GET /export endpoint to retrieve the data.
Edit the data.
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

Parameter	Type	Required	Description
username	string	x	Your Shoreline Execution account username
password	string	x	Your 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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrl	string		URL for sending the account data to once the request is completed.
workPackages	array		A list of work package IDs.
workOrders	array		A list of work order IDs.
sites	array		A list of site IDs.
assets	array		A list of assets IDs.
names	array		A list of activity names.
activities	array		A list of activity IDs.
startDate	date		UTC timestamp. Activities that start on or after the start date are included.
endDate	date		UTC timestamp. Activities that end on or after the end date are included.
statuses	enum		An array of activity statuses. Either `PLANNED`, `DISPATCHED`, or `COMPLETED`.
changedSince	date		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

Parameter	Type	Required	Description
correlationId	string	x	A 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

Parameter	Type	Required	Description
correlationId	string	x	A 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

Parameter	Type	Required	Description
correlationId	string	x	A 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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.

Body parameters

Parameter	Type	Required	Description
id	string	x	A unique activity ID.
siteId	string	x	The site ID to which the activity relates.
assetId	string		The asset ID to which the activity relates.
startDate	date		UTC timestamp. When the activity begins.
endDate	date		UTC timestamp. When the activity ends.
activityCategory	string		The activity category to which the activity belongs.
status	enum		An array of activity statuses. Either `PLANNED`, `DISPATCHED`, or `COMPLETED`.
workPackageId	string		The work package to which the activity belongs.
additionalClientWork	boolean		Boolean value for activity entity.
workOrderId	string		The work order ID to which the activity belongs.
teams	array		A list of team names to which the activity relates.
personnelIds	array		A list of personnel IDs to which the activity relates.
manpower	json		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 }`.
internalRemarks	string		Any internal comments related to the activity.
externalRemarks	string		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

Parameter	Type	Required	Description
correlationId	string	x	A unique ID for your import request. Returned in the request response.

Body parameters

Parameter	Type	Required	Description
file	file	x	A 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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrl	string		URL for sending the account data to once the request is completed.
activityCategories	array		A list of activity category IDs.
names	array		A list of activity names.
workPackages	array		A list of work package IDs.
changedSince	date		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

Parameter	Type	Required	Description
correlationId	string	x	Export 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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrl	string		URL for sending the account data to once the request is completed.
names	array		A list of personnel names.
emails	array		A list of personnel email addresses.
roles	array		A list of personnel roles.
departments	array		A list of department names.
teams	array		A list of team names.
workPackages	array		A list of work package IDs.
changedSince	date		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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackURL	string		URL for sending the account data to once the request is completed.
timesheets	array		A list of timesheet IDs.
names	array		A list of timesheet names.
statuses	enum		An array of timesheet status, either `DRAFT`, `PENDING`, `SIGNED`, or `REJECTED`.
dateFrom	date		UTC timestamp. Timesheets created on or after the given date are included.
dateTo	date		UTC timestamp. Timesheets create on or before the given date are included.
submittedBy	array		A list of personnel IDs who submitted the timesheets.
approvedBy	array		A list of personnel IDs who approved the timesheets.
changedSince	date		UTC timestamp. Timesheets modified since the given date are included.
timeEntries	array		A list of time entry IDs.
activities	array		A list of activity IDs.
workPackages	array		A list of work packages IDs.
personnel	array		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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrl	string		URL for sending the account data to once the request is completed.
workOrderSequences	array		A list of work order sequence IDs.
names	array		A list of work order sequence names.
changedSince	date		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

Parameter	Type	Required	Description
projectID	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrl	string		URL for sending the account data to once the request is completed.
workOrders	array		A list of work order IDs.
names	array		A list of work order names.
types	array		A list of work order types.
priorities	array		A list of work order priorities.
workPackages	array		A list of work package IDs.
workOrderSequences	array		A list of work order sequence IDs.
changedSince	date		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

Parameter	Type	Required	Description
projectId	string	x	Unique project ID. Found under Account Settings > Integrations > Ingestion API.
callbackUrl	string		URL for sending the account data to once the request is completed.
workPackages	array		A list of work package IDs.
names	array		A list of work package names.
types	array		A list of work package types.
status	enum		An array of work package statuses. Either `NONE`, `PLANNED`, `CONFIRMED`, `FINISHED`, or `CANCELED`.
countries	array		A list of countries.
assetTypes	array		A list of asset type names.
startDate	date		UTC timestamp. Work packages that begin on or after the given date are included.
endDate	date		UTC timestamp. Work packages that end on or before the given date are included.
changedSince	date		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.