Connect to Conductor

1. Authentication and first request

Base URL: https://conductorrlv-prod-api-lbgams3snpcdy.azurewebsites.net/api/v1

For trusted server integrations, an administrator creates a minimally scoped key under API keys. The secret is shown once. Keep it in your server's secret store; never in browser code, URLs, logs, spreadsheets or documentation. Explicitly revoke unused keys; this pilot does not automatically expire keys.

curl --fail-with-body \
  -H "Authorization: Bearer $CONDUCTOR_TOKEN" \
  "https://conductorrlv-prod-api-lbgams3snpcdy.azurewebsites.net/api/v1/me"

Web sign-in uses Microsoft Entra v2 authorization code + PKCE. Authority: https://login.microsoftonline.com/318b8053-b4fc-4cdd-83f7-0b0159e352c9; public client ID: 4c331a38-2dee-48d4-bb2b-7a6d920a70cd; scope: api://4c331a38-2dee-48d4-bb2b-7a6d920a70cd/access_as_user. A browser client must use an administrator-registered redirect URI and Microsoft sign-in; it must not hold a client secret or API key. App assignment and an application role are required.

Administrator: all scopes. Dispatcher: operational/financial scopes, but not key management, identity mapping or secret notification configuration. Driver: linked active driver, assigned-trip-only data, minimal eligible open-shift feed and own requests. A driver binding is a hard boundary even if a key has wildcard scopes. Mapping an identity or entering an object ID does not create the Microsoft account, assign a role, grant consent, or alter MFA.

2. Responses, safe retries and time

JSON successes use {data, requestId}; errors use {error, requestId}. Health is raw JSON; CSV and invoice HTML are raw downloads. Keep requestId when asking for support. A 200 notification test can contain an unknown or blocked delivery—inspect its data.status.

400: invalid fields/JSON. 401: sign-in/key failure. 403: role/scope/driver boundary. 404: not found in your organization. 409: stale version, state or duplicate/infeasible business operation. 422: ambiguous address. 429: quota/rate limit. 501: required provider missing. 502/503: provider/configuration unavailable.

For documented idempotent writes, retain the same idempotencyKey and unchanged payload after a network failure. Changed payload with the same key is a conflict. Refresh before retrying a stale expectedVersion. Not every POST is idempotent: generic record/trip/key creation requires reconciliation before resubmission. Use 45-second normal request timeouts and up to 150 seconds for routing/dispatch. Never retry an unknown Teams outcome blindly.

Use YYYY-MM-DD for service dates, and ISO timestamps with Z or an explicit UTC offset for instants. Recurrence preserves local clock time with an IANA time zone; ambiguous/nonexistent DST times require review. AmountCents/unitAmountCents are integer USD cents. Quantities allow up to three fractional places. Tax is basis points; 100 = 1%.

3. Integration workflow

1. Read /me and confirm organization and least-privilege scopes.
2. Create approved driver/vehicle, payer and state-specific contract records. Do not infer qualifications, prices, broker credentials or VINs.
3. Create scheduled trips with exact pickup times. Preview /dispatch/plan, then confirm each proposed pair through /dispatch/assignments. Revalidation may reject a stale proposal.
4. Drivers advance en_route → arrived → picked_up → completed with retained idempotency keys. Attachments use intent → direct Blob PUT → complete. Upload/read URLs are temporary secrets.
5. Create invoice drafts in cents. Issue an immutable numbered invoice, then record only funds actually received. Receipt reversals correct records, not bank transactions. Download the printable HTML document or CSV export.
6. Configure Teams Workflows privately, test the exact chat/audience, confirm receipt, then enable. The scheduler checks every five minutes and sends only the current most urgent due stage.

For local development, use isolated synthetic records and scoped disposable credentials. Never use production rider data in test fixtures. The RLV connector is a dry-run mapping endpoint only; webhook endpoints register metadata but do not yet deliver outbound events.

4. Endpoint reference

Loading reference…

5. Schemas

Open a schema to inspect exact field names, units, enums, required fields and limits. The downloadable OpenAPI file is the machine-readable contract. Additional server-derived metadata may appear in responses.