Routing Configuration and Run APIs

This feature introduces public REST APIs for routing configuration and routing runs, enabling integrations to automate routing operations. In update 26D, the Routing APIs expand public REST access to routing configuration and execution data through new Configuration Provider endpoints. The update also adds public Configuration Filter endpoints that support routing plan configuration, import, validation, and automation workflows. Together, these APIs support integration, routing investigations, automation scenarios, and future AI-assisted routing workflows.

Supported operations

These operations are supported:

  • Routing profile and plan management
  • Bucket assignment
  • Routing plan import and export
  • Routing runs
  • Routing run rollback
  • Routing run reports

Update 26D introduces public endpoints under the following prefixes:

  • /api/field-service/routing/v1 for routing profiles, routing plans, routing runs, rollback, and reports.
  • /api/field-service/configuration/v1 for Configuration Filters used by routing plan configuration and validation.

The Routing API was introduced in 26B. In 26D, it expands with additional endpoints for routing profiles, plans, runs, reports, bucket assignments, and rollback. Several 26B report and routing plan import/export endpoints that used custom-actions paths are deprecated in favor of the new 26D endpoints.

Configuration filter endpoints

Method Endpoint Description

GET

/api/field-service/configuration/v1/filters

Retrieves a list of filters with optional filtering, sorting, and pagination.

GET

/api/field-service/configuration/v1/filters/{label}

Retrieves a single filter by label.

PUT

/api/field-service/configuration/v1/filters/{label}

Creates or replaces a filter.

DELETE

/api/field-service/configuration/v1/filters/{label}

Deletes a filter when it has no blocking dependencies.

Routing profile and assignment endpoints

Method Endpoint Description

GET

/api/field-service/routing/v1/routingProfiles

Retrieves routing profiles. This endpoint is available from 26B.

GET

/api/field-service/routing/v1/routingProfiles/{profileLabel}

Retrieves a routing profile name and label.

POST

/api/field-service/routing/v1/routingProfiles

Creates a routing profile.

PATCH

/api/field-service/routing/v1/routingProfiles/{profileLabel}

Updates the routing profile label, name, and active state.

GET

/api/field-service/routing/v1/routingProfiles/{profileLabel}/buckets

Retrieves the buckets assigned to a routing profile. This endpoint is available from 26B.

PUT

/api/field-service/routing/v1/routingProfiles/{profileLabel}/buckets/{resourceExternalId}

Assigns the routing profile to the specified bucket.

DELETE

/api/field-service/routing/v1/routingProfiles/{profileLabel}/buckets/{resourceExternalId}

Removes the routing profile assignment from the specified bucket.

Routing plan endpoints

Method Endpoint Description

GET

/api/field-service/routing/v1/routingProfiles/{profileLabel}/plans

Returns the routing plan labels for a routing profile.

GET

/api/field-service/routing/v1/routingProfiles/{profileLabel}/plans/{planLabel}

Exports a routing plan as JSON. This replaces the deprecated 26B custom-actions export endpoint in public documentation.

POST

/api/field-service/routing/v1/routingProfiles/{profileLabel}/plans

Imports a routing plan into a routing profile. If a plan with the same label exists, the endpoint returns a conflict.

PUT

/api/field-service/routing/v1/routingProfiles/{profileLabel}/plans/{planLabel}

Imports or updates a routing plan in a routing profile. If the plan exists, it is updated rather than rejected as a duplicate.

Routing run and report endpoints

Method Endpoint Description

POST

/api/field-service/routing/v1/routingRuns

Starts a routing run for the specified profile, plan, resource, and date.

GET

/api/field-service/routing/v1/routingRuns/{runId}

Returns the routing run status for the specified run ID.

POST

/api/field-service/routing/v1/routingRuns/{runId}/custom-actions/rollback

Rolls back the specified routing run, or undoes rollback when applicable.

GET

/api/field-service/routing/v1/routingRuns/{resourceExternalId}/date/{date}

Returns the routing run summaries for a resource and date.

GET

/api/field-service/routing/v1/routingRuns/{resourceExternalId}/date/{date}/report/notAssigned

Returns a paged collection of activities not assigned by routing runs for a resource and date.

GET

/api/field-service/routing/v1/routingRuns/{runId}/report

Retrieves the routing run summary and report category links.

GET

/api/field-service/routing/v1/routingRuns/{runId}/report/assigned

Retrieves assigned activities for a routing run report.

GET

/api/field-service/routing/v1/routingRuns/{runId}/report/notAssigned

Retrieves the activities not assigned for a routing run report.

GET

/api/field-service/routing/v1/routingRuns/{runId}/report/reassigned

Retrieves the reassigned activities for a routing run report.

GET

/api/field-service/routing/v1/routingRuns/{runId}/report/reordered

Retrieves the reordered activities for a routing run report.

GET

/api/field-service/routing/v1/routingRuns/{runId}/report/unassigned

Retrieves the unassigned activities for a routing run report.

Example: Start a routing run

curl -X POST \

  -H 'Authorization: Bearer <JWT>' \

  -H 'Accept: application/json' \

  -H 'Content-Type: application/json' \

  -d '{

    "profileLabel": "BulkWithImmediate",

    "planLabel": "BulkRouting",

    "resourceExternalId": "bulk_routing_bucket",

    "date": "2025-08-01"

  }' \

  'https://<environment>/api/field-service/routing/v1/routingRuns'

Example: Import a routing plan 

curl -X POST \

  -H 'Authorization: Bearer <JWT>' \

  -H 'Content-Type: application/json' \

  'https://<environment>/api/field-service/routing/v1/routingProfiles/AutoTestGroupActionDeleteOk/plans' \

  -d '{

    "scheduling_plan": {

      "label": "manual_plan",

      "name": "manual plan",

      "type": "manual"

    }

  }'

Business Benefit

  • Modernized public API coverage: Routing operations can be accessed through public microservice endpoints.
  • Improved automation: Customers and integrators can automate routing plan import and export, profile assignment, runs, rollback, and reporting.
  • Better routing investigations: Report endpoints expose assigned, not assigned, reassigned, reordered, and unassigned activity details, making it easier to analyze routing results and failures.
  • AI-ready routing workflows: The public API surface supports future AI-based routing assistants and routing v.Next scenarios.
  • Consistent contracts: Endpoints use standard authentication, SAS permissions, validation, pagination, HATEOAS links where applicable, and predictable errors.

Steps to enable and configure

No special enablement is required for the API itself. Client applications must authenticate and authorize requests using the supported platform mechanisms and the required routing metadata scopes and SAS permissions.

  • Use the public endpoint prefix https://<environment>/api/field-service/routing for Routing API calls.
  • Use the public endpoint prefix https://<environment>/api/field-service/configuration for Configuration Filter API calls.
  • Use OAuth2 bearer tokens, platform basic credentials, or other supported authenticators configured for the environment.
  • For read operations, use metadata routing profile read access and the corresponding SAS read permission for the artifact.
  • For create, update, delete, import, assignment, start, and rollback operations, use metadata routing profile write access and the corresponding SAS permission for the artifact.

Tips and considerations

Authorization and permissions

  • Routing endpoints use metadata_api_routing_profiles authorization.
  • Read operations require read access, for example platform:metadata_api_routing_profiles:read.
  • Write operations require write access, for example platform:metadata_api_routing_profiles:write.
  • SAS artifacts include RoutingProfile, RoutingPlan, RoutingBucketAssignment, RoutingRun, and RoutingRunReport.

Pagination

  • Collection endpoints use limit, offset, totalResults, hasMore, and links according to the service collection contract.
  • Clients should follow next links when present and should not assume all records are returned in a single response.
  • Invalid pagination values return 400 Bad Request.

Routing plan import and export

  • Export returns the routing plan under the scheduling_plan property.
  • Import payloads must be wrapped under scheduling_plan.
  • POST /routingProfiles/{profileLabel}/plans creates a plan and returns conflict when a plan with the same label exists.
  • PUT /routingProfiles/{profileLabel}/plans/{planLabel} creates or replaces a plan and should be used when overwrite behavior is intended.
  • Referenced labels such as filters, message flows, and predecessor plans are validated and resolved during import.

Routing runs and rollback

  • Starting a routing run requires profileLabel, planLabel, resourceExternalId, and date.
  • The route date must use ISO format YYYY-MM-DD and cannot be in the past.
  • Rollback validates run status and date constraints before delegating execution.
  • Application Server business-rule errors, such as an already-started routing plan or a busy system, can be returned as 409 Conflict.

Deprecated 26B paths

  • The 26B plan import/export endpoints under /api/field-service/routing/v2/.../custom-actions are deprecated in 26D and removed from public documentation.
  • The 26B report endpoints under /routingRuns/{runId}/custom-actions/report are deprecated in 26D. Use /routingRuns/{runId}/report and its subresources instead.
  • The 26B date summary path /routingRuns/{resourceExternalId}/{date} is deprecated in 26D. Use /routingRuns/{resourceExternalId}/date/{date}.

Common errors

  • 400 Bad Request is returned for invalid labels, missing required fields, invalid dates, invalid pagination, or invalid request bodies.
  • 401 Unauthorized is returned when authentication is missing or invalid.
  • 404 Not Found is returned when the requested profile, plan, run, resource, or assignment does not exist.
  • 409 Conflict is returned for duplicate routing plans, invalid bucket assignment targets, unsupported rollback state, or Application Server business-rule conflicts.