Public API reference
Public API reference
Description
The public API provides a fast, automated way to import and export account data. Use the public API to retrieve account settings, edit them, and reimport them.
The public 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
correlationIdparameter in the response. - Copy the
correlantionIdvalue. - Append the
correlationIdvalue as a query parameter on theGET /exportendpoint to retrieve the data. - Edit the data.
- Submit the edited JSON through the relevant
POSTendpoint.
Base URL
https://ex.[you-subdomain].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 account username |
| password | string | x | Your Shoreline 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.