Skip to main content

Register

Creates a new user account and sends an email verification link.

Endpoint​

POST /api/v1/auth/register

Authentication​

No authentication required (public endpoint).

Request​

Content-Type​

application/json

Request Body​

FieldTypeRequiredDescription
emailstringYesValid email address
phone_numberstringYesPhone number in E.164 format (e.g., +1234567890)
passwordstringYesPassword (see requirements below)

Password Requirements​

Passwords must meet ALL of the following criteria:

  • Minimum 8 characters long
  • At least one uppercase letter (A-Z)
  • At least one lowercase letter (a-z)
  • At least one digit (0-9)
  • At least one special character (!@#$%^&*(),.?":|<>)

Phone Number Format​

Must be in E.164 international format:

  • Starts with + (optional but recommended)
  • Country code (1-3 digits)
  • Subscriber number (up to 15 digits total)
  • Examples: +12025551234, +442071234567, +61412345678

Example Request​

{
  "email": "john@example.com",
  "phone_number": "+12025551234",
  "password": "SecurePass123!"
}

Response​

Success Response (201 Created)​

{
  "message": "User registered successfully. Please check your email for the verification link.",
  "success": true
}

After registration, the user will receive an email with a verification link. They must verify their email before they can log in.

Response Fields​

FieldTypeDescription
messagestringSuccess message
successbooleanAlways true for successful requests

Verification Flow​

  1. User registers → Receives verification email
  2. User clicks link → Redirected to frontend with token
  3. Frontend calls /auth/verify-email → User is verified and logged in

Examples​

curl -X POST https://api.callcov.com/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
  "email": "john@example.com",
  "phone_number": "+12025551234",
  "password": "SecurePass123!"
}'

Errors​

400 Bad Request​

Email already registered:

{
  "detail": "Email already registered"
}

Phone number already registered:

{
  "detail": "Phone number already registered"
}

Invalid email format:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Password doesn't meet requirements:

{
  "detail": [
    {
      "loc": ["body", "password"],
      "msg": "Password must contain at least one uppercase letter",
      "type": "value_error"
    }
  ]
}

Invalid phone number format:

{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "Invalid phone number format. Use E.164 format (e.g., +1234567890)",
      "type": "value_error"
    }
  ]
}

500 Internal Server Error​

Failed to send verification email:

{
  "detail": "Failed to send verification email. Please try again."
}

Security Considerations​

  • Passwords are hashed: Never stored in plain text
  • Email verification required: Users cannot log in until verified
  • Unique email and phone: Prevents duplicate accounts
  • Rate limiting: Registration endpoint is rate-limited to prevent abuse

Email Verification​

After registration, users receive an email containing:

  • Verification link with token
  • Link expires in 15 minutes (configurable)
  • Token is single-use

Example verification email format:

Subject: Verify your CallCov account

Click the link below to verify your email address:
https://app.callcov.com/verify-email?token=abc123...

This link expires in 15 minutes.

Testing in Development​

In development mode, verification emails are sent to MailHog (accessible at http://localhost:8025).