> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartcomply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Journey Tracking

> Track and validate user transaction events in sequence to detect out-of-order or suspicious behaviour.

The User Journey API tracks critical steps in a user's transaction flow through defined checkpoints. It validates that expected events occur in the correct sequence and flags suspicious or out-of-order behaviour in real time.

## Submit Event

Submit a user journey event for fraud assessment.

### Endpoint

```
POST /api/v1/journey/event/
```

### Headers

| Header           | Value               | Required |
| ---------------- | ------------------- | -------- |
| `x-access-token` | Your API secret key | Yes      |
| `Content-Type`   | `application/json`  | Yes      |

### Body Parameters

| Parameter           | Type   | Required | Description                                                                        |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `user_id`           | string | Yes      | Unique identifier for the user                                                     |
| `session_id`        | string | Yes      | Identifier for the current session                                                 |
| `event`             | string | Yes      | Event type: `LOGIN`, `OTP_VERIFY`, `PAYMENT_INIT`, `PAYMENT_COMPLETE`, or `LOGOUT` |
| `timestamp`         | string | Yes      | ISO-8601 datetime of the event                                                     |
| `device_id`         | string | No       | Device identifier                                                                  |
| `ip_address`        | string | No       | IP address during the event                                                        |
| `metadata.amount`   | number | No       | Transaction amount if applicable                                                   |
| `metadata.currency` | string | No       | Currency code                                                                      |

### 201 Created

```json theme={null}
{
  "status": "Success",
  "data": {
    "status": "allow",
    "risk_score": 0.12,
    "reason": "Normal login pattern",
    "session_state": "OTP_VERIFY",
    "alert_triggered": false
  },
  "message": "success"
}
```

***

## Get Session State

Retrieve the current state and event history for a session.

### Endpoint

```
GET /api/v1/journey/session/{session_id}/
```

### Path Parameters

| Parameter    | Type   | Required | Description                            |
| ------------ | ------ | -------- | -------------------------------------- |
| `session_id` | string | Yes      | Identifier for the session to retrieve |

### 200 OK

```json theme={null}
{
  "status": "success",
  "data": {
    "session_id": "abc-123",
    "user_id": "user-456",
    "current_state": "PAYMENT_INIT",
    "events": [],
    "start_time": "2025-08-01T10:00:00Z"
  },
  "message": "success"
}
```

***

## Clear Session

Delete all stored data for a session.

### Endpoint

```
DELETE /api/v1/journey/session/{session_id}/
```

### Path Parameters

| Parameter    | Type   | Required | Description                         |
| ------------ | ------ | -------- | ----------------------------------- |
| `session_id` | string | Yes      | Identifier for the session to clear |

### 204 No Content

```json theme={null}
{
  "message": "Session cleared"
}
```

***

## User Analytics

Retrieve fraud and risk statistics for a user across all sessions.

### Endpoint

```
GET /api/v1/journey/analytics/user/{user_id}/
```

### Path Parameters

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `user_id` | string | Yes      | Identifier for the user |

### 200 OK

```json theme={null}
{
  "status": "success",
  "data": {
    "user_id": "user-456",
    "total_events": 42,
    "average_risk_score": 0.08,
    "blocked_events": 1,
    "reviewed_events": 3,
    "total_sessions": 10,
    "average_session_risk": 0.07
  },
  "message": "Success"
}
```

***

## Health Check

Check the service health and dependency status.

### Endpoint

```
GET /api/v1/journey/health/
```

### 200 OK

```json theme={null}
{
  "status": "healthy",
  "broker": "connected",
  "database": "connected",
  "timestamp": "2025-08-01T10:00:00Z"
}
```

***

## Error Codes

| Code  | Description                                |
| ----- | ------------------------------------------ |
| `200` | Success                                    |
| `201` | Event processed successfully               |
| `400` | Missing, malformed, or invalid fields      |
| `401` | Authentication failed or API key missing   |
| `403` | Insufficient permissions for this resource |
| `404` | Resource or endpoint not found             |
| `429` | Rate limit exceeded — retry after cooldown |
| `500` | Unexpected server error                    |


## OpenAPI

````yaml POST /api/v1/journey/event/
openapi: 3.0.3
info:
  title: Adhere API
  description: >-
    Identity verification, credit checks, transaction monitoring, and loan fraud
    detection across Africa.
  version: 3.0.0
servers:
  - url: https://adhere-api.smartcomply.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Nigeria KYC
  - name: Kenya KYC
  - name: Ghana KYC
  - name: Rwanda KYC
  - name: Uganda KYC
  - name: Biometrics
  - name: Individual Credit
  - name: Business Credit
  - name: Transaction Monitoring
  - name: Transaction Screening
  - name: Transaction KYC
  - name: Loan Fraud
  - name: User Journey
paths:
  /api/v1/journey/event/:
    post:
      tags:
        - User Journey
      summary: Submit Journey Event
      operationId: submitJourneyEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - session_id
                - event
                - timestamp
              properties:
                user_id:
                  type: string
                session_id:
                  type: string
                event:
                  type: string
                  enum:
                    - LOGIN
                    - OTP_VERIFY
                    - PAYMENT_INIT
                    - PAYMENT_COMPLETE
                    - LOGOUT
                timestamp:
                  type: string
                  format: date-time
                device_id:
                  type: string
                ip_address:
                  type: string
                metadata:
                  type: object
                  properties:
                    amount:
                      type: number
                    currency:
                      type: string
      responses:
        '201':
          description: Event processed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: failed
              data:
                type: array
                items: {}
              message:
                type: string
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: failed
              message:
                type: string
                example: Authentication credentials were not provided.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-access-token
      description: Your Adhere API secret key

````