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" }
POST /export/reports
Request an export of reports with their full context and metadata. Use filters in the request body to narrow down your export. This endpoint also powers report export through the Shoreline MCP Server.
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. |
|
reportIds |
array |
|
A list of report IDs. Omit to use the date and status filters. |
|
statuses |
array |
|
A list of report statuses. |
|
startDate |
date |
|
UTC timestamp. Reports on or after the given date are included. |
|
endDate |
date |
|
UTC timestamp. Reports on or before the given date are included. |
|
useHoursAndMinutes |
boolean |
|
Return durations as hours and minutes. |
Response
Returns a JSON object with the following properties:
- correlationId: A unique ID for your request.
Retrieve the exported data with GET /export. For each report, the retrieved object contains:
- report: id, number, title, date, status, site (id, name), and template (id, name).
- sections: each with title, name, order, and rows.
- activities: each with activityId, inclusionStatus (INCLUDED or EXCLUDED), section, position, reportId, reportNumber, and reportTitle.
Example
Request
curl -X 'POST' \ 'https://ex.shoreline.no/public/v1/export/reports' \ -H 'accept: application/json' \ -H 'Authorization: Bearer {API_KEY}' \ -H 'Content-Type: application/json' \ -d '{ "projectId": "{PROJECT_ID}", "reportIds": [ "R1", "R2", "R3" ], "statuses": [ "{STATUS}" ], "startDate": "2023-05-02T12:04:53.313Z", "endDate": "2023-05-02T12:04:53.313Z", "useHoursAndMinutes": true }'
Response
{ "correlationId": "1234567a-890b-123c-d45e-678f901234567" }
POST /integration-ids
Assign an Integration ID to a record so it can be matched to the same record in an external system, such as an ERP or CMMS. Identify the target record either by its Shoreline ID (mongoId) or by its existing external ID.
Body parameters
|
Parameter |
Type |
Required |
Description |
|---|---|---|---|
|
projectId |
string |
x |
Unique project ID. Found under Account Settings > Integrations > Ingestion API. |
|
objectType |
enum |
x |
The type of object. One of ACTIVITIES, ADVERSE_EVENTS, INVENTORY, INVENTORY_GROUP, PERSONNEL, WORK_ORDERS, WORK_ORDER_TASKS, or TEAMS. |
|
integrationId |
string |
x |
The reference value to store on the record. |
|
mongoId |
string |
|
The Shoreline ID of the target record. Provide either mongoId or externalId. |
|
externalId |
string |
|
The target record's existing external ID. Provide either mongoId or externalId. |
Response
Returns a JSON object confirming the assignment (the object type and the affected record's ID).
Example
Request
curl -X 'POST' \ 'https://ex.shoreline.no/public/v1/integration-ids' \ -H 'accept: application/json' \ -H 'Authorization: Bearer {API_KEY}' \ -H 'Content-Type: application/json' \ -d '{ "projectId": "{PROJECT_ID}", "objectType": "WORK_ORDERS", "integrationId": "ERP-WO-12345", "externalId": "WO-1" }'
Response
{ "objectType": "WORK_ORDERS", "integrationId": "ERP-WO-12345", "mongoId": "{RECORD_ID}", "projectId": "{PROJECT_ID}" }
Activity category ID in exports
The Activity category ID is now included in the exported data retrieved from GET /export for reports and activity-related exports, so external systems can map activity categories to their own records. No new endpoint or parameter is required: the field appears in the retrieved payload for existing export requests.
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.