Working with work orders in the data API

Overview

The Shoreline Public API allows you to export and import work orders programmatically, enabling seamless integration with external systems. This guide covers how to set up, use, and troubleshoot work order operations via the Shoreline Public API.

Understanding the Workflow

The Work Order API follows an asynchronous pattern:

Submit an export or import request
Receive a correlationId
Poll for status using the correlationId
Retrieve results or diagnose failures

This pattern prevents HTTP timeouts on large datasets and allows you to track long-running operations. Every export and import request immediately returns a correlationId — a unique identifier you use in subsequent calls to check status and retrieve results.

Prerequisites

1. API Access & Authentication

Before working with work orders, ensure you have:

API access enabled for your account (contact your admin or Customer Success Manager if needed)
Valid Shoreline credentials (username and password)
Your organization's base URL (e.g., https://ex.[your-subdomain].shoreline.no/api/)

2. Project ID

Most work order operations require a valid projectId. To find yours:

Log into Shoreline
Navigate to Account Settings → Integrations → Ingestion API
Copy your Project ID

Step 1: Authentication

Obtaining Your API Token

POST https://ex.[your-subdomain].shoreline.no/api/authenticate
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using Your Token

Include the token in all subsequent requests:

Include the token in all subsequent requests. Tokens expire after a period of inactivity — if you receive a 401 Unauthorized response on a previously working request, re-authenticate to obtain a fresh token.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

⚠️ Common Mistake: Forgetting the Bearer prefix will result in 401 Unauthorized errors.

Step 2: Exporting Work Orders

Basic Export

POST https://ex.[your-subdomain].shoreline.no/api/export/workorders
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
Accept: application/json

{
  "projectId": "your-project-id"
}

Advanced Filtering

{
  "projectId": "your-project-id",
  "workOrders": ["WO-001", "WO-002"],
  "workPackages": ["pkg-123"],
  "sites": ["site-456"],
  "status": ["Open", "In Progress"],
  "changedSince": "2025-01-01T00:00:00Z"
}

Available Filters:

workOrders – Array of specific work order IDs
workPackages – Array of work package IDs
sites – Array of site IDs
status – Array of status values
changedSince – ISO 8601 UTC timestamp
startDate / endDate – ISO 8601 UTC timestamps that filter work orders by their scheduled or due date range

Response

{
  "correlationId": "abc-123-def-456"
}

Step 3: Checking Export Status

GET https://ex.[your-subdomain].shoreline.no/api/import/status?correlationId=abc-123-def-456
Authorization: Bearer {YOUR_TOKEN}
Accept: application/json

Response:

{
  "status": "Completed",
  "totalItems": 150,
  "processedItems": 150,
  "failedItems": 0
}

Status Values:

Pending
Processing
Completed
Failed

💡 Best Practice: Poll every 5–10 seconds for small datasets and every 30–60 seconds for large ones. Stop polling once the status reaches Completed or Failed to avoid unnecessary API calls.

Step 4: Retrieving Export Results

GET https://ex.[your-subdomain].shoreline.no/api/import/result/{correlationId}
Authorization: Bearer {YOUR_TOKEN}
Accept: application/json

Response:

{
  "workOrders": [
    {
      "id": "WO-001",
      "title": "Inspect Equipment A",
      "status": "Open",
      "workPackageId": "pkg-123",
      "siteId": "site-456",
      "assignedTo": "user@company.com",
      "dueDate": "2025-12-31T23:59:59Z",
      "createdDate": "2025-01-15T10:00:00Z",
      "modifiedDate": "2025-01-20T14:30:00Z",
      "customFields": {
        "priority": "High",
        "category": "Maintenance"
      }
    }
  ]
}

Step 5: Importing Work Orders

⚠️ Important: Use the import endpoint POST /api/import/workorders for this request. Sending import data to the export endpoint will not create or update work orders.

POST https://ex.[your-subdomain].shoreline.no/api/export/workorders
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
Accept: application/json

{
  "projectId": "your-project-id",
  "workOrders": [
    {
      "id": "WO-NEW-001",
      "title": "New Equipment Inspection",
      "status": "Open",
      "workPackageId": "pkg-123",
      "siteId": "site-456",
      "dueDate": "2025-12-31T23:59:59Z"
    }
  ]
}

Response:

{
  "correlationId": "xyz-789-uvw-012"
}

Common Issues & Troubleshooting

401 Unauthorized

❌ Missing Bearer prefix → ✅ Add it
❌ Expired token → ✅ Re-authenticate
❌ Wrong credentials → ✅ Check login
❌ API access disabled → ✅ Contact admin

400 Bad Request

❌ Missing projectId
❌ Malformed JSON
❌ Wrong date format (YYYY-MM-DDTHH:MM:SSZ)
❌ Missing headers

Empty Export Results

❌ Filters too strict or wrong projectId
✅ Try removing filters or adjusting date

Import Failures

If the status response shows a failedItems count greater than 0, retrieve the details of failed records using:

GET https://ex.[your-subdomain].shoreline.no/api/import/failed/{correlationId}

Best Practices

Error Handling (JavaScript Example)

try {
  const response = await post('/export/workorders', { projectId });
  saveCorrelationId(response.correlationId);
} catch (error) {
  if (error.status === 401) await refreshToken();
}

Polling Strategy

while (true) {
  const status = await getStatus(correlationId);
  if (status === 'Completed') return getResults(correlationId);
  if (status === 'Failed') throw new Error('Import failed');
  await sleep(10000);
}

Incremental Sync

post('/export/workorders', { projectId, changedSince: lastSync });

Integration Checklist

✅ API access enabled
✅ Project ID stored
✅ Token refresh implemented
✅ Bearer headers set
✅ JSON headers set
✅ Correlation IDs stored
✅ Status polling implemented
✅ Error handling in place

Quick Reference

Operation	Method	Endpoint	Returns
Authenticate	POST	`/authenticate`	`{ token }`
Export work orders	POST	`/export/workorders`	`{ correlationId }`
Check status	GET	`/import/status?correlationId=...`	Status
Get results	GET	`/import/result/{correlationId}`	Work orders
Get failures
Import work orders	POST	`/import/workorders`	`{ correlationId }`	GET	`/import/failed/{correlationId}`	Failed items

Getting Help

If you experience issues:

Check your application logs and the API response body for error messages
Verify IDs and filters
Re-run a simple export
Contact Support with your correlationId

📚 API Docs: Swagger UI — Note: this link uses a preview environment. Replace ex.preview with your organization's subdomain (e.g., https://ex.[your-subdomain].shoreline.no/public/documentation/swagger-ui/index.html#/) to access your environment's full API reference.