Contents

1   Overview — four ways to submit a request

Every equipment-retrieval (or delivery) request enters the platform through one of four channels. All four land in the same system of record, run through the same scheduling engine, and emit the same lifecycle webhooks.

2   Authentication

The REST API and MCP server use OAuth 2.0 client-credentials (machine-to-machine). Web-form users authenticate with their own portal login; CSV uploads in the portal inherit that session.

2.1   Get a token

# OAuth 2.0 client credentials
POST https://auth.retrieveitassets.com/oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "YOUR_AUDIENCE",
  "grant_type": "client_credentials"
}

# Response
{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 86400 }

Send it on every request: Authorization: Bearer YOUR_ACCESS_TOKEN

2.2   API-key fallback

If you were issued an API key instead of OAuth credentials, send it directly — no token exchange needed: X-Api-Key: YOUR_API_KEY

2.3   Your clientId

Every integration is assigned a numeric clientId. Always send it in the payload — credentials are authorized only for specific clientId values. An unauthorized value returns 403 client_mismatch.

3   The asset-movement request contract

movementType is required and is the contract-level discriminator for delivery vs. retrieval. Do not infer direction from the free-text requestDetails. Allowed values: retrieval, delivery.

4   REST API endpoints

4.1   Submit a retrieval

POST /api/v1/requests/asset-movements
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 11111111-2222-3333-4444-555555555555

{
  "clientId": 95,
  "source": "ServiceNow",
  "items": [{
    "movementType": "retrieval",
    "employeeName": "Jane Smith",
    "employeePhone": "555-123-4567",
    "customerTrackingNumber": "RET-1001",
    "pickupAddress1": "123 Main St",
    "pickupCity": "Boston",
    "pickupState": "MA",
    "pickupZip": "02101",
    "finalDestination": "RetrieveITAssets Concierge",
    "requestDetails": "Pick up laptop, dock, and charger from employee home."
  }]
}

4.2   Async behavior

Submit → receive 202 Accepted with a submissionId → poll the status endpoint until processing completes.

{ "submissionId": "6c600f5ebe27427287...", "status": "Pending", "createdAt": "2026-04-30T14:00:00Z" }

4.3   Idempotency

Put a client-generated unique id (UUID) in the Idempotency-Key header per logical submission. Reuse the same key only when retrying the exact same submission. Do not use clientId or submissionId as the key.

5   CSV bulk upload

For submitting many requests at once. Download the template, one request per row, then upload it in the portal or POST it to the import endpoint.

5.1   Columns

The header row must be exactly:

movementType,employeeName,employeePhone,customerTrackingNumber,pickupAddress1,
pickupAddress2,pickupCity,pickupState,pickupZip,finalDestination,requestDetails,clientId,source

• movementType must be retrieval or delivery (required, sets direction).
• Wrap any field containing a comma in double quotes, e.g. "ModernIT, 123 XX Street".
• Empty optional cells are fine; leave the comma in place (e.g. an empty pickupAddress2).
• Each row is validated independently — valid rows import even if others are rejected; the response lists per-row errors.

5.2   Example rows

movementType,employeeName,...,finalDestination,requestDetails,clientId,source
retrieval,Jane Smith,...,RetrieveITAssets Concierge,"Pick up laptop and dock.",95,ServiceNow
delivery,Taylor Quinn,...,"ModernIT, 123 XX Street",Deliver laptop to employee.,95,Workday

6   Web form intake

Signed-in portal users submit one request at a time through a guided form whose fields map one-to-one to the contract in §3. The form enforces the required fields and the retrieval/delivery choice before it will submit, so a web-form request is always contract-valid. On submit it creates the same request record as the API and CSV paths and returns a request number the user can track in the portal.

7   Webhooks — lifecycle events

The platform sends outbound webhooks as a request moves through its lifecycle. Delivery and retrieval share the same event catalog.

Security headers: X-T2-Signature, X-T2-Timestamp, X-T2-EventId. Validate the HMAC-SHA256 signature, enforce a replay window on the timestamp, and process idempotently by eventId. Status polling remains available for reconciliation alongside webhooks.

8   MCP — Model Context Protocol server

MCP is how AI agents talk to the platform. Instead of hand-writing HTTP calls, an assistant connects to the RIA MCP server, which exposes a small set of typed tools. The agent picks a tool, fills its inputs, and the server performs the same authenticated API call under the hood — with the same auth, the same contract, and the same guardrails as the REST API.

8.1   How it works

• Connect. The agent adds the RIA MCP server endpoint and its credentials (an API key or OAuth client scoped to a clientId). The server advertises its tools on connect.
• Discover tools. The agent reads each tool's name, description and input schema — no separate integration code needed.
• Call a tool. The agent calls e.g. create_request with structured inputs. The server validates against the §3 contract and calls the REST API.
• Read the result. The server returns a structured result (a request number, a status) the agent can act on or report back.

8.2   Tools exposed

8.3   Guardrails

Every MCP tool runs under the same scoped credential as the API: it can only touch data for its authorized clientId, read-only tools cannot write, and write tools that change state (cancel) are permission-gated. The MCP server never exposes credentials, accounting, or delete operations.

9   Errors & support