Introduction

Welcome to the Yoooo API documentation. This API allows you to programmatically access and interact with the Yoooo platform. It provides endpoints for user authentication, comprehensive profile management, contacts syncing, and retrieving public data such as user profiles, countries, and cities.

The API is built using RESTful principles and returns standard JSON responses. The base URL for all endpoints is:

https://api.yooo.app/api/v1

Standard Response Format

All successful requests will return a consistent JSON structure wrapped with a status, a message, and the requested data payload:

{
  "status": "success",
  "message": "Success message here",
  "data": {
    // ... payload data
  }
}

Authentication

Protected API endpoints require authentication via JWT (JSON Web Tokens). You can obtain a token by using the Login or Sign Up endpoints.

Once you have a token, you must include it in the Authorization header of your HTTP requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Errors

The API uses standard HTTP status codes to indicate the success or failure of an API request. Failed requests will always return a status of error and a descriptive message.

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": "The email field must contain a valid email address.",
    "password": "The password field is required."
  }
}
Code Description
200 / 201 Success: The request was successful and data is returned.
400 Bad Request: The request was unacceptable, often due to missing or invalid parameters.
401 Unauthorized: No valid API token provided or the token has expired.
403 Forbidden: The API token doesn't have permissions to perform the request.
404 Not Found: The requested resource does not exist.
500 Server Error: Something went wrong on the API's end.

Public Endpoints

Endpoints accessible without authentication.

Get Home

Retrieve initial home data and recent profiles.

GET /home
No parameters required.

Response Example 200 OK 

{
  "status": "success",
  "message": "Welcome to the Yoooo API",
  "data": {
    "message": "Welcome to the Yoooo API",
    "recent_profiles": [
      {
        "id": 10,
        "status": "active",
        "name": "Jane Doe",
        "...": "..."
      }
    ]
  }
}

Get Countries

Retrieve a list of available active countries.

GET /countries
No parameters required.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "countries": [
      {
        "id": 1,
        "name": "United States",
        "code": "US"
      }
    ]
  }
}

Get Cities

Retrieve cities, optionally filtered by country.

GET /cities

Query Parameters

Parameter Type Description
country_id integer Optional. Filter cities by the given country ID.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "cities": [
      {
        "id": 100,
        "name": "New York",
        "country_id": 1
      }
    ]
  }
}

Get Profiles List

Retrieve a list of profiles with extensive filtering options.

GET /profiles

Query Parameters

Parameter Type Description
gender string Filter by gender. Defaults to female.
country string Filter by country name.
city string Filter by city name.
membership string Filter by membership level.
sexualities string|array Filter by sexualities. Can be an array or comma-separated string.
is_verified boolean Filter only verified profiles (true/false).
services string|array Filter by provided services. Can be an array or comma-separated string.
limit integer Number of profiles to retrieve. Defaults to 24.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "profiles": [
      {
        "id": 1,
        "name": "Jane Doe",
        "gender": "female",
        "is_verified": true,
        "...": "..."
      }
    ]
  }
}

Get Single Profile Details

Retrieve specific details of a single profile by ID.

GET /profile/{id}

Path Parameters

Parameter Type Description
id Required integer The unique ID of the profile.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "profile": {
      "id": 1,
      "name": "Jane Doe",
      "gender": "female",
      "country": "United States",
      "city": "New York",
      "about": "Hello, this is my profile.",
      "...": "..."
    }
  }
}

Error Example 404 Not Found 

{
  "status": "error",
  "message": "Profile not found"
}

Auth Endpoints

Endpoints related to user authentication and account recovery.

Login

Authenticate a user and receive a JWT token. Requires an active account.

POST /login

Body Parameters (application/json or form-data)

Parameter Type Description
email Required string The user's registered email address. Must be a valid email.
password Required string The user's password.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

Sign Up

Register a new user account. Returns an authentication token immediately and triggers a verification email.

POST /signup

Body Parameters

Parameter Type Description
name Required string Full name of the user. Min 3, max 20 chars.
email Required string Must be a valid, unique email address.
password Required string Password for the account. Minimum 8 characters.

Response Example 200 OK 

{
  "status": "success",
  "message": "Account created successfully. Please verify your email.",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "verification_email_sent": true,
    "user": {
      "id": 2,
      "username": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

Verify Email

Verify an email address using the token sent in the welcome email.

GET /auth/verify-email

Query Parameters

Parameter Type Description
token Required string The verification token sent to the user's email. 
{
  "status": "success",
  "message": "Email verified successfully.",
  "data": []
}

Resend Verification

Resend the email verification token if not already verified. (Cooldown applies).

POST /auth/resend-verification

Body Parameters

Parameter Type Description
email Required string The registered email address. 
{
  "status": "success",
  "message": "Verification email processed.",
  "data": {
    "sent": true
  }
}

Forgot Password

Request a password reset link to be sent via email.

POST /auth/forgot-password

Body Parameters

Parameter Type Description
email Required string The registered email address. 
{
  "status": "success",
  "message": "If an account exists for that email, a reset link has been sent.",
  "data": []
}

Reset Password

Reset the password using the token from the forgot password email.

POST /auth/reset-password

Body Parameters (JSON only)

Parameter Type Description
token Required string The valid reset token.
password Required string New password. Minimum 8 characters.
confirm_password Required string Must match the password parameter exactly. 
{
  "status": "success",
  "message": "Password reset successfully.",
  "data": []
}

User Panel Endpoints

Requires a valid JWT Bearer token in the Authorization header. Actions performed here are scoped to the authenticated user.

Dashboard

Retrieve user dashboard overview, including basic user account info and high-level profile statistics (like completion percentage).

GET /dashboard
No parameters required. Header must contain Bearer Token.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "profile": {
      "id": 15,
      "status": "active",
      "is_verified": true,
      "membership": "premium",
      "completion": 85
    }
  }
}

Get User Profile

Retrieve the authenticated user's complete, editable profile data. JSON string fields (like images, pricing, services) are automatically decoded into arrays.

GET /user/profile
No parameters required.

Response Example 200 OK 

{
  "status": "success",
  "message": "Success",
  "data": {
    "profile": {
      "id": 15,
      "name": "John Doe",
      "gender": "male",
      "dob": "1990-01-01",
      "location": "Miami, FL",
      "images": ["user_1_12345.webp"],
      "services": ["service1", "service2"]
    }
  }
}

Update Profile

Create or update the user's profile. You must send a valid JSON payload. Certain fields (like images, services, etc.) should be sent as JSON arrays.

POST /user/profile/update

Body Parameters (application/json ONLY)

Parameter Type Description
name Required string Display name (3-100 chars).
gender Required string Must be male, female, or other.
dob Required string Date of birth in YYYY-MM-DD format.
location Required string Location text (3-255 chars).
images array Array of image filenames.
pricing, services, languages, other_pages, sexuality array/object Must be sent as JSON structures. Will be encoded before saving.
other fields... string description, phone, whatsapp, height, weight, ethnicity, etc. 
{
  "status": "success",
  "message": "Profile updated successfully",
  "data": []
}

Upload Photo

Upload a single profile photo. The server will process it, create WEBP variants, and append the filename to the profile's image list.

POST /user/profile/upload-photo

Body Parameters (multipart/form-data)

Parameter Type Description
photo or image Required file The image file to upload. Allowed types: JPG, PNG, WEBP. 
{
  "status": "success",
  "message": "Photo uploaded successfully",
  "data": {
    "image": "user_1_169...webp",
    "images": [
      "user_1_169...webp"
    ]
  }
}

Upload Contacts

Upload user contacts to the platform using a JSON file.

POST /upload-contacts

Body Parameters (multipart/form-data)

Parameter Type Description
contacts_file Required file A valid .json file containing an array of contacts. Max size: 5MB. 
{
  "status": "success",
  "message": "Contacts uploaded successfully.",
  "data": {
    "uploaded_contacts_count": 250,
    "stored_file": "contacts_2023....json"
  }
}

Change Password

Change the authenticated user's account password.

POST /user/change-password

Body Parameters

Parameter Type Description
current_password Required string The user's current password.
new_password Required string The new password (min 8 chars).
confirm_password Required string Must match new_password exactly. 
{
  "status": "success",
  "message": "Password updated successfully.",
  "data": []
}

Delete Account

Permanently delete the user's account, profile data, and uploaded images.

POST /user/delete-account
No parameters required. Authentication token maps to the user.
{
  "status": "success",
  "message": "Your account has been deleted successfully.",
  "data": []
}