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 everything you need to know about setting up, using, and troubleshooting work order operations.

Understanding the Workflow

The Work Order API follows an asynchronous pattern:

1. Submit an export or import request

2. Receive a correlationId

3. Poll for status using the correlationId

4. Retrieve results or diagnose failures

This pattern prevents timeouts on large datasets and allows you to track long-running operations.

---

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:

1. Log into Shoreline

2. Navigate to Account Settings → Integrations → Ingestion API

3. 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:

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 – Date range filters

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, 30–60 seconds for large ones.

---

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

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

Check with:

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	GET	/import/failed/{correlationId}	Failed items

---

Getting Help

If you experience issues:

1. Check logs

2. Verify IDs and filters

3. Re-run a simple export

4. Contact Support with your correlationId

📚 API Docs: Swagger UI