Omnichannel Rail

Omnichannel Rail

The Omnichannel Rail provides APIs for managing customer journeys, delegation of authority, multi-channel approvals, activity timelines, and notification delivery across all channels.

Overview

The Omnichannel Rail unifies customer-facing and back-office interaction flows:

Capability	Description
Journey Management	Define, advance, and complete multi-step customer journeys
Journey Templates	Reusable journey templates with configurable steps
Delegation	Grant and revoke authority delegation between users
Approvals	Multi-party approval workflows with audit trail
Timeline	Unified activity timeline per customer or entity
Notifications	Multi-channel notification delivery (push, email, SMS, in-app)

Endpoints

List Journeys

GET /api/v1/omni/journeys

Lists all customer journeys for the authenticated tenant.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status (created, in_progress, assigned, completed, cancelled)
templateId	string	Filter by journey template ID
customerId	string	Filter by customer entity ID
assigneeId	string	Filter by assigned user ID
page	number	Page number (default: 1)
perPage	number	Items per page (default: 20, max: 100)

Create Journey

POST /api/v1/omni/journeys

Creates a new customer journey from a template.

Request Body:

{
  "templateId": "tmpl_onboarding_sme",
  "customerId": "ent_customer_456",
  "channel": "web",
  "context": {
    "productType": "murabaha",
    "requestedAmount": { "amount": 2000000, "currency": "SAR" }
  },
  "assigneeId": "usr_rm_001",
  "priority": "normal",
  "dueAt": "2024-01-25T17:00:00Z"
}

Response:

{
  "data": {
    "id": "jrn_abc123",
    "status": "created",
    "templateId": "tmpl_onboarding_sme",
    "customerId": "ent_customer_456",
    "channel": "web",
    "currentStepIndex": 0,
    "currentStep": {
      "id": "step_kyc",
      "name": "KYC Verification",
      "type": "kyc_check",
      "status": "pending"
    },
    "totalSteps": 6,
    "completedSteps": 0,
    "assigneeId": "usr_rm_001",
    "priority": "normal",
    "dueAt": "2024-01-25T17:00:00Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Advance Journey

POST /api/v1/omni/journeys/{id}/advance

Advances a journey to the next step.

Request Body:

{
  "completedStepId": "step_kyc",
  "stepOutcome": "passed",
  "stepData": {
    "kycStatus": "verified",
    "kycReference": "kyc_ref_001"
  },
  "advancedBy": "usr_rm_001"
}

Response:

{
  "data": {
    "id": "jrn_abc123",
    "status": "in_progress",
    "currentStepIndex": 1,
    "currentStep": {
      "id": "step_docs",
      "name": "Document Collection",
      "type": "document_upload",
      "status": "pending"
    },
    "completedSteps": 1,
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Assign Journey

POST /api/v1/omni/journeys/{id}/assign

Assigns or reassigns a journey to a user or team.

Request Body:

{
  "assigneeId": "usr_rm_002",
  "assigneeType": "user",
  "reason": "Original RM on leave",
  "notifyAssignee": true
}

Complete Journey

POST /api/v1/omni/journeys/{id}/complete

Marks a journey as successfully completed.

Request Body:

{
  "completionNotes": "All steps completed, contract activated",
  "completedBy": "usr_rm_001",
  "outcome": "success"
}

Cancel Journey

POST /api/v1/omni/journeys/{id}/cancel

Cancels an in-progress journey.

Request Body:

{
  "cancellationReason": "Customer withdrew application",
  "cancelledBy": "usr_rm_001"
}

List Journey Templates

GET /api/v1/omni/templates

Lists all journey templates available to the tenant.

Query Parameters:

Parameter	Type	Description
category	string	Filter by category (onboarding, servicing, sales)
status	string	Filter by status (active, draft, archived)

Create Journey Template

POST /api/v1/omni/templates

Creates a new journey template.

Request Body:

{
  "name": "SME Onboarding",
  "description": "End-to-end onboarding journey for SME customers",
  "category": "onboarding",
  "steps": [
    {
      "id": "step_kyc",
      "name": "KYC Verification",
      "type": "kyc_check",
      "order": 1,
      "required": true,
      "timeoutHours": 48
    },
    {
      "id": "step_docs",
      "name": "Document Collection",
      "type": "document_upload",
      "order": 2,
      "required": true,
      "documentsRequired": ["trade_license", "financial_statements"]
    },
    {
      "id": "step_credit",
      "name": "Credit Assessment",
      "type": "approval",
      "order": 3,
      "required": true,
      "approvalRoleRequired": "credit_analyst"
    }
  ],
  "estimatedDurationDays": 5,
  "slaHours": 120
}

List Delegations

GET /api/v1/omni/delegations

Lists all active and historical authority delegations.

Query Parameters:

Parameter	Type	Description
delegatorId	string	Filter by delegating user ID
delegateeId	string	Filter by delegated-to user ID
status	string	Filter by status (active, expired, revoked)
scope	string	Filter by delegation scope (approvals, journeys, all)

Create Delegation

POST /api/v1/omni/delegations

Grants a delegation of authority from one user to another.

Request Body:

{
  "delegatorId": "usr_manager_001",
  "delegateeId": "usr_deputy_002",
  "scope": ["approvals", "journey_assign"],
  "maxApprovalAmount": { "amount": 500000, "currency": "SAR" },
  "validFrom": "2024-01-15T00:00:00Z",
  "validTo": "2024-01-22T23:59:59Z",
  "reason": "Annual leave coverage"
}

Response:

{
  "data": {
    "id": "del_xyz789",
    "status": "active",
    "delegatorId": "usr_manager_001",
    "delegateeId": "usr_deputy_002",
    "scope": ["approvals", "journey_assign"],
    "maxApprovalAmount": { "amount": 500000, "currency": "SAR" },
    "validFrom": "2024-01-15T00:00:00Z",
    "validTo": "2024-01-22T23:59:59Z",
    "createdAt": "2024-01-15T09:00:00Z"
  }
}

List Approvals

GET /api/v1/omni/approvals

Lists all approval requests.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status (requested, approved, rejected, expired)
approverId	string	Filter by approver user ID
requesterId	string	Filter by requester user ID
entityType	string	Filter by entity type (journey, contract, payment)

Create Approval Request

POST /api/v1/omni/approvals

Creates an approval request.

Request Body:

{
  "entityType": "journey",
  "entityId": "jrn_abc123",
  "approvalType": "credit_committee",
  "requestedBy": "usr_rm_001",
  "approvers": [
    { "userId": "usr_credit_001", "role": "primary", "required": true },
    { "userId": "usr_credit_002", "role": "secondary", "required": false }
  ],
  "approvalData": {
    "facilityAmount": { "amount": 2000000, "currency": "SAR" },
    "creditScore": 720,
    "recommendation": "approve"
  },
  "expiresAt": "2024-01-18T17:00:00Z"
}

Get Activity Timeline

GET /api/v1/omni/timeline

Retrieves a unified activity timeline across journeys, approvals, and notifications for an entity.

Query Parameters:

Parameter	Type	Description
entityId	string	Entity ID (customer, journey, contract) - required
entityType	string	Entity type (customer, journey, contract) - required
fromDate	string	Filter from date (ISO 8601)
toDate	string	Filter to date (ISO 8601)
eventTypes	string	Comma-separated event type filters
page	number	Page number (default: 1)
perPage	number	Items per page (default: 50, max: 200)

Response:

{
  "data": [
    {
      "id": "evt_001",
      "timestamp": "2024-01-15T10:30:00Z",
      "eventType": "journey.created",
      "actorId": "usr_rm_001",
      "actorName": "Ahmed Al-Rashidi",
      "channel": "web",
      "summary": "Onboarding journey created",
      "metadata": {
        "journeyId": "jrn_abc123",
        "templateId": "tmpl_onboarding_sme"
      }
    },
    {
      "id": "evt_002",
      "timestamp": "2024-01-15T11:00:00Z",
      "eventType": "journey.advanced",
      "actorId": "usr_rm_001",
      "summary": "Journey advanced: KYC step completed",
      "metadata": { "stepId": "step_kyc", "outcome": "passed" }
    }
  ],
  "pagination": { "page": 1, "perPage": 50, "total": 2 }
}

List Notifications

GET /api/v1/omni/notifications

Lists all notifications for the tenant or a specific recipient.

Query Parameters:

Parameter	Type	Description
recipientId	string	Filter by recipient user or customer ID
channel	string	Filter by channel (push, email, sms, in_app)
status	string	Filter by status (pending, sent, delivered, failed)
read	boolean	Filter by read status

Create Notification

POST /api/v1/omni/notifications

Sends a notification through one or more channels.

Request Body:

{
  "recipientId": "ent_customer_456",
  "recipientType": "customer",
  "channels": ["push", "email"],
  "templateCode": "JOURNEY_STEP_REQUIRED",
  "templateData": {
    "journeyName": "SME Onboarding",
    "stepName": "Document Collection",
    "dueDate": "2024-01-17"
  },
  "priority": "normal",
  "scheduleAt": null
}

Journey Lifecycle

stateDiagram-v2
    direction LR

    [*] --> Created: Create Journey
    Created --> InProgress: Advance First Step
    InProgress --> Assigned: Assign to User
    Assigned --> InProgress: Resume
    InProgress --> Completed: All Steps Done
    InProgress --> Cancelled: Cancel
    Created --> Cancelled: Cancel

    classDef created fill:#1565c0,color:#fff,stroke:#1565c0
    classDef inprogress fill:#e65100,color:#fff,stroke:#e65100
    classDef assigned fill:#2e7d32,color:#fff,stroke:#2e7d32
    classDef completed fill:#1a5f4a,color:#fff,stroke:#1a5f4a
    classDef cancelled fill:#c62828,color:#fff,stroke:#c62828

    class Created created
    class InProgress inprogress
    class Assigned assigned
    class Completed completed
    class Cancelled cancelled

Journey Status

Status	Description
created	Journey created, not yet started
in_progress	One or more steps completed, journey active
assigned	Journey assigned to a specific user
completed	All required steps completed successfully
cancelled	Journey cancelled before completion

Approval Status

Status	Description
requested	Approval request raised, pending action
approved	All required approvers have approved
rejected	One or more required approvers rejected
expired	Approval not actioned before expiry deadline

Webhooks

The Omnichannel Rail emits the following webhook events:

Event	Description
omni.journey.created	New journey created
omni.journey.advanced	Journey advanced to next step
omni.journey.assigned	Journey assigned to a user or team
omni.journey.completed	Journey completed successfully
omni.journey.cancelled	Journey cancelled
omni.approval.requested	Approval request raised
omni.approval.approved	Approval granted
omni.approval.rejected	Approval rejected
omni.delegation.granted	Authority delegation created and active
omni.delegation.revoked	Authority delegation revoked

Code Examples

import { IOFClient } from "@iof/sdk";

const client = new IOFClient({ apiKey: process.env.IOF_API_KEY });

// Create an onboarding journey for a customer
const journey = await client.omni.journeys.create({
  templateId: "tmpl_onboarding_sme",
  customerId: "ent_customer_456",
  channel: "web",
  context: {
    productType: "murabaha",
    requestedAmount: { amount: 2000000, currency: "SAR" },
  },
  assigneeId: "usr_rm_001",
});

// Advance through steps
await client.omni.journeys.advance(journey.id, {
  completedStepId: "step_kyc",
  stepOutcome: "passed",
  stepData: { kycStatus: "verified" },
  advancedBy: "usr_rm_001",
});

// Create an approval request for the journey
const approval = await client.omni.approvals.create({
  entityType: "journey",
  entityId: journey.id,
  approvalType: "credit_committee",
  requestedBy: "usr_rm_001",
  approvers: [{ userId: "usr_credit_001", role: "primary", required: true }],
  expiresAt: "2024-01-18T17:00:00Z",
});

// Get the full customer timeline
const timeline = await client.omni.timeline.get({
  entityId: "ent_customer_456",
  entityType: "customer",
  perPage: 50,
});

from iof import IOFClient

client = IOFClient(api_key=os.environ["IOF_API_KEY"])

# Create and advance journey
journey = client.omni.journeys.create(
    template_id="tmpl_onboarding_sme",
    customer_id="ent_customer_456",
    channel="web",
    assignee_id="usr_rm_001",
)

client.omni.journeys.advance(
    journey.id,
    completed_step_id="step_kyc",
    step_outcome="passed",
    advanced_by="usr_rm_001",
)

# Grant a delegation
client.omni.delegations.create(
    delegator_id="usr_manager_001",
    delegatee_id="usr_deputy_002",
    scope=["approvals", "journey_assign"],
    valid_from="2024-01-15T00:00:00Z",
    valid_to="2024-01-22T23:59:59Z",
)

# Send a notification
client.omni.notifications.create(
    recipient_id="ent_customer_456",
    channels=["push", "email"],
    template_code="JOURNEY_STEP_REQUIRED",
    template_data={"step_name": "Document Collection"},
)

Next Steps

• Workflow Rail - Approval workflows
• Notifications Rail - Notification management
• KYC Rail - Customer verification
• Contracts Rail - Islamic contract lifecycle