Creating a User and Logging In

This comprehensive guide walks you through the process of creating a new user account and logging into the Optimize Everything API system.

📚 Full API Documentation: For complete API reference and additional endpoints, visit https://api.opteverything.com/docs

Prerequisites

Before you begin, ensure you have:

• A valid email address
• A phone number (numeric only, can include + and spaces)
• A secure password
• Access to make HTTP requests (curl, Postman, or your preferred API client)

Step 1: Create a New User Account

Creates a new user account with the provided information including user details and size specifications.

Endpoint

POST /user/users

Required Information

You'll need to provide the following required fields:

Name	Type	Required	Description	Default
first_name	string	Yes	User's first name (max 256 characters)	—
second_name	string	Yes	User's last name/surname (max 256 characters)	—
email	string	Yes	User's email address (must be valid email format, max 256 characters)	—
password	string	Yes	User's password for account authentication (max 256 characters)	—
phone_number	string	Yes	User's phone number (numeric only, max 15 characters, can include + and spaces)	—

Optional Information

You can also provide:

Name	Type	Required	Description	Default
other_names	string	No	Middle name or additional names (max 256 characters)	—
type	string	No	User role	Customer
notification_urls	array	No	Array of URLs for notifications	—
size	object	No	User's transportation size requirements (adult_count, child_count, accessible_count)	—

User Types

The system supports several user types, each with specific roles and permissions:

Customer

• Someone who rides or gives rides
• Default

Business

• A business that operates rideshares or buses

Market Maker

• A company that trades transportation contracts

Insurer

• A person who guarantees that a customer, business, or market maker has enough funds to cover any required payments in the case they do not pay

Verifier

• Verifies user's reputation, identity, criminal background, etc.

Example Request

curl -X POST "https://api.opteverything.com/user/users" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "second_name": "Doe",
    "other_names": "Middle",
    "email": "john.doe@example.com",
    "password": "SecurePassword123!",
    "phone_number": "+1234567890",
    "type": "Customer",
    "notification_urls": ["https://notify.example.com/callback"],
    "size": {
      "adult_count": 2,
      "child_count": 1,
      "accessible_count": 0
    }
  }'

Responses

Success (200 OK)

Status Code: 200 OK

{
  "user": {
    "first_name": "John",
    "second_name": "Doe",
    "other_names": "Middle",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890",
    "type": "Customer"
  },
  "cargo": {
    "type": "person",
    "size_id": 1
  },
  "size": {
    "adult_count": 2,
    "child_count": 1,
    "accessible_count": 0
  }
}

Field	Type	Description
user	object	User's personal information
cargo	object	Cargo details associated with the user
size	object	User's transportation size requirements

Error (400 Bad Request)

Status Code: 400 Bad Request

{
  "success": false,
  "error_code": "EMAIL_ALREADY_EXISTS",
  "message": "A user with this email already exists"
}

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

Step 2: Log In to Your Account

Endpoint

POST /auth/login

Required Information

• email: The email address you used during registration
• password: The password you set during registration

Example Request

curl -X POST "https://api.opteverything.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "password": "SecurePassword123!"
  }'

Responses

Success (200 OK)

Status Code: 200 OK

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "12345",
    "email": "john.doe@example.com",
    "first_name": "John",
    "second_name": "Doe",
    "type": "Customer"
  }
}

Field	Type	Description
success	boolean	Indicates operation succeeded
message	string	Human-readable success message
token	string	JWT authentication token
user	object	Authenticated user details
id	string	User ID
email	string	User email
first_name	string	First name
second_name	string	Last name
type	string	User type

Error (401 Unauthorized)

Status Code: 401 Unauthorized

{
  "success": false,
  "error_code": "INVALID_CREDENTIALS",
  "message": "Email or password is incorrect"
}

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

Step 3: Using Your Authentication Token

After successful login, you'll receive an authentication token. Use this token for subsequent API requests by including it in the Authorization header:

curl -X GET "https://api.opteverything.com/user/profile" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Validation Rules

Email Validation

• Must be a valid email format
• Maximum 256 characters
• Must be unique in the system

Phone Number Validation

• Must be numeric only (can include + and spaces)
• Maximum 15 characters
• Pattern: ^\+?[0-9\s]+$

Size Validation

• All count fields must be positive integers (> 0)
• All fields are optional

Common Issues and Solutions

User Creation Issues

• Email already exists: Use a different email address
• Invalid phone number: Ensure the phone number follows the required format (numeric only)
• Missing required fields: Double-check that all required fields are provided
• Invalid email format: Ensure email follows standard email format

Login Issues

• Invalid credentials: Verify your email and password
• Account not found: Ensure you've completed the registration process
• Token expired: Re-authenticate by logging in again

Best Practices

1. Password Security: Use a strong password with a mix of letters, numbers, and special characters
2. Token Management: Store your authentication token securely and refresh it when needed
3. Error Handling: Always check the response status and handle errors appropriately
4. User Type Selection: Choose the appropriate user type based on your role in the transportation ecosystem

Next Steps

After creating your account and logging in, you can:

• Update your profile information
• Access protected API endpoints
• Manage your account settings

After the user is created, you can create a contract.

For more detailed information about all available endpoints and features, visit the complete API documentation.