Creating a User Event

Create a user event for a leg. User events are used to track the start, end, or cancellation of a leg by either the rider or operator.

When a user event is created, the user's verification service will be notified at their notification URL. The verification service will then verify the event and respond with pass, fail, or undetermined for each party's location.

📚 Full API Documentation: For all endpoints, see https://api.opteverything.com/docs

Prerequisites

• You have created a trip (see Rider/Operator Trip Guide)
• You have created legs for the trip (see Creating Legs Guide)
• You have your authentication token

Overview

User events are crucial for managing the trip lifecycle. They control when legs start and end, track trip progress, and ultimately determine when a trip is completed.

Step 1: Create a User Event

Endpoint

POST /user-event/user-events

Required Information

Name	Type	Required	Description	Default
leg_id	integer	Yes	ID of the leg associated with this event	—
event_type	enum	Yes	Type of event (EventType)	—
description	string	Yes	Human-readable description of the event	—
timestamp	datetime	Yes	Timestamp when the event occurred	—
position	object	Yes	Coordinates where the event occurred (latitude, longitude)	—

Event Types (per API)

Value	Name	Description
0	SUCCESS_START	Leg started successfully
1	SUCCESS_END	Leg ended successfully
2	NOT_SHOWN_UP_OPERATOR	Operator has not shown up
3	REFUSED_ENTRY_OPERATOR	Operator refused entry
4	NO_CONTINUE_OPERATOR	Operator unable/unwilling to continue ride
5	NOT_SHOWN_UP_RIDER	Rider did not show up
6	REFUSED_ENTRY_RIDER	Rider refused to enter vehicle
7	NO_CONTINUE_RIDER	Rider unable/unwilling to continue ride

Example Request - Starting a Leg

curl -X POST "https://api.opteverything.com/user-event/user-events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "leg_id": 123,
    "event_type": "START",
    "description": "Driver started the trip leg",
    "timestamp": "2024-06-01T10:00:00Z",
    "position": {
      "latitude": 40.7128,
      "longitude": -74.0060
    }
  }'

Example Request - Ending a Leg

curl -X POST "https://api.opteverything.com/user-event/user-events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "leg_id": 123,
    "event_type": "END",
    "description": "Driver completed the trip leg",
    "timestamp": "2024-06-01T15:30:00Z",
    "position": {
      "latitude": 40.7589,
      "longitude": -73.9851
    }
  }'

Responses

Success (201 Created)

Status Code: 201 Created

{
  "user_event_id": 0
}

Field	Type	Description
user_event_id	integer	Unique identifier for the newly created user event

Error (400 Bad Request)

Status Code: 400 Bad Request

{
  "success": false,
  "error_code": "INVALID_EVENT_TYPE",
  "message": "The event_type provided is not valid"
}

Field	Type	Description
success	boolean	Always false on error
error_code	string	Machine-readable error identifier
message	string	Human-readable error explanation

Trip Lifecycle Management

Starting a Trip

1. Create a user event with event_type: "START" for the first leg
2. The leg status changes to "ACTIVE"
3. The trip begins tracking

Managing Leg Transitions

• Each leg can be started and ended independently
• Multiple legs can be active simultaneously
• User events track the progress of each leg
• Position data is recorded for each event
• A leg is completed when a success start user event has been created for its cargo trip and operator trip respectively

Ending a Trip

1. Create user events to end all active legs
2. When the final leg ends, the trip status changes to "COMPLETED"
3. A trip result is automatically generated

Event Details

Position Tracking

• latitude: Latitude coordinate where the event occurred
• longitude: Longitude coordinate where the event occurred
• Used for tracking trip progress and location history

Event Descriptions

• Provide human-readable descriptions for each event
• Useful for debugging and trip history
• Should be descriptive and meaningful

Next Steps

Continue to the next guide: Verification Services

Or see the full API documentation.