SF Prime Service Locate Service
Description
The Locate API (v1) enables clients to submit bulk locate requests and retrieve request results through a standardized interface. The service supports:
- Bulk locate request submission (POST /requests)
- Request inquiry by client request ID, returning request information plus all locates under that request (GET /requests/{imRequestId})
- Request inquiry by client request ID with specified locate IDs, returning request information plus only the requested locate details (GET /requests/{imRequestId}/{imLocateIds})
- Optional callback-based submission flow (POST /callback-requests)
The API is intended for system-to-system integration to reduce manual operational touchpoints in the locate request process.
For standard bulk submission (POST /requests), the service first attempts to process the request within an internal fast-return threshold. If processing completes within that threshold, the response returns the request result immediately. If processing exceeds that threshold, the service continues execution asynchronously and the response is returned with request status Pending. In that case, clients should use the query endpoints with imRequestId to retrieve the eventual result.
imRequestId is the client-defined request identifier and is globally unique in the current implementation (platform-level namespace, not scoped by user). If the same imRequestId is submitted more than once, the request is rejected as a duplicate request. Clients are strongly encouraged to use high-entropy IDs such as UUIDv4, or a composite identifier pattern like client-specific-prefix + clientDefinedId.
Within a single request, each locate item is identified by imLocateId. imLocateId must be unique within that request (imRequestId + imLocateId unique per request). Submitting duplicate imLocateId values in the same request is not allowed because it can cause item-level overwrite; such requests are rejected.
The callback-based submission flow (POST /callback-requests) follows the same business pattern with different field names. Before using this callback interface, clients must contact State Street to onboard/configure SiteID and complete required firewall/network allowlist setup. BulkLocateID is the callback equivalent of imRequestId and must be unique per submission (same platform-level request namespace behavior). Each LocateID is the callback equivalent of imLocateId, and each BulkLocateID + LocateID combination must be unique within the request. After validation and acceptance, final processing results are delivered asynchronously to the registered ReplyURL.
To minimize accidental collisions and reduce predictability, clients are strongly encouraged to generate high-entropy identifiers (for example, UUIDv4) for both imRequestId and BulkLocateID.
Client Benefits
- Higher operational efficiency: Automates request submission and inquiry, reducing manual processing effort.
- Simpler integration: Provides consistent REST endpoints and payload structures for client platform integration.
- Better status transparency: Allows clients to query both bulk request outcomes and selected locate-level details.
- Lower operational risk: Standardized interfaces reduce manual entry errors and process inconsistency.
- Flexible processing model: Supports both polling-based inquiry and callback-based integration patterns.
Data Availability
The API provides two main query views:
- Request + full locate set: Request/result information keyed by imRequestId, including all locates under that request.
- Request + selected locate details: Request/result information plus selected locate records under the same request, filtered by comma-separated imLocateIds.
Availability is processing-dependent:
- If a standard submission completes within the internal fast-return threshold, the initial submission response may already contain the completed result.
- If the initial standard submission response returns Pending, clients should query later by imRequestId until processing is complete.
- For callback submissions, the immediate response only confirms validation/acceptance status; final locate results are delivered asynchronously to ReplyURL.
Historical access and retention period are subject to the platform's data retention policy and environment configuration.