Assignments

When you are ready to commit to a provider, you Assign them. This is the contract step.

Strategies

• Direct Assignment: You know the provider (user_id).
• From Request: You routed the work, and are accepting a provider's application.

Assignment Flow

Assign a Provider

POST /workorders/{id}/assignee?clientPayTermsAccepted=true

{
  "user": { "id": 12345 }
}

Assignment Response

{
  "id": 1001,
  "status": "Assigned",
  "assignee": {
    "id": 12345,
    "first_name": "John",
    "last_name": "Smith",
    "rating": 4.8
  }
}

Unassign a Provider

Remove the current provider from the work order.

DELETE /workorders/{id}/assignee

Provider Requests

When you route a work order, providers can Request it. You can view and manage these requests.

List Requests

GET /workorders/{id}/requests

{
  "results": [
    {
      "id": 501,
      "user": { "id": 12345, "name": "John Smith" },
      "status": "pending",
      "counter_offer": null,
      "created": { "utc": "2026-01-15 10:00:00" }
    }
  ]
}

Accept a Request

POST /workorders/{id}/requests/{request_id}/accept

Deny a Request

DELETE /workorders/{id}/requests/{request_id}

Counter-Offers

Providers can submit a counter-offer with different pay terms.

{
  "id": 501,
  "user": { "id": 12345 },
  "counter_offer": {
    "pay": {
      "type": "fixed",
      "base": { "amount": 175.00 }
    },
    "note": "Travel distance is significant"
  }
}

Provider Swaps

When a work order is assigned to a service company, that company's admin may want one of their own technicians to do the work. They raise a swap request naming the proposed provider, and you decide whether to allow it.

Pending swaps appear in the swaps collection on the work order:

{
  "swaps": {
    "results": [
      {
        "id": 456,
        "status": "pending",
        "actions": ["accept", "deny"],
        "from": { "id": 12345, "name": "John Smith" },
        "to": { "id": 67890, "name": "Dana Lee" },
        "requestor": { "id": 12345, "name": "John Smith" }
      }
    ]
  }
}

Approve or Deny a Swap

PUT /workorders/{id}/swaps/{swap_id}

curl -X PUT "https://api.fieldnation.com/api/rest/v2/workorders/458212/swaps/456?access_token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "accepted" }'

curl -X PUT "https://api.fieldnation.com/api/rest/v2/workorders/458212/swaps/456?access_token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "denied" }'

Both return the full updated work order. Read back the swaps collection to confirm the decision was applied — the swap moves from pending to accepted or denied.

Assignment History

View all past assignments for a work order.

GET /workorders/{id}/assignments

{
  "results": [
    {
      "id": 1,
      "user": { "id": 12345, "name": "John Smith" },
      "status": "completed",
      "assigned_at": { "utc": "2026-01-15 10:00:00" }
    }
  ]
}

Related

• Workflow Lifecycle - Full state management
• Providers - Finding providers