POST
/
api
/
v1
/
auth
/
verify-email
Verify email (OTP)
curl --request POST \
  --url https://api.example.com/api/v1/auth/verify-email
import requests

url = "https://api.example.com/api/v1/auth/verify-email"

response = requests.post(url)

print(response.text)
const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/auth/verify-email', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/auth/verify-email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.example.com/api/v1/auth/verify-email"

req, _ := http.NewRequest("POST", url, nil)

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/auth/verify-email")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/auth/verify-email")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Overview

Verifies the 6-digit OTP that was sent to the user’s email during registration (or via POST /resend-verify-email). On success:
  1. The OTP row is marked consumed.
  2. users.emailVerified is set to true.
  3. A new session is minted — access token (RS256 JWT, 15-min TTL) + refresh token (256-bit opaque, 30-day TTL, single-use rotating).
Wrong codes increment attemptsUsed and return 401 INVALID_CODE. After 5 attempts the row is dead and further calls return 401 CODE_EXPIRED; the client must request a fresh code. The endpoint is idempotent on already-verified users — a second call returns a fresh session without consuming an OTP. This keeps the client’s “verify → land in app” flow robust on network retries.

Authentication

None required — this endpoint is part of the login sequence.

Path parameters

None.

Query parameters

None.

Request body

FieldTypeRequiredAllowed valuesExample
emailstringyesRFC 5322 valid, lowercased server-sidealice@example.com
codestringyesExactly 6 digits482301

Example payload

{
  "email": "alice@example.com",
  "code": "482301"
}

Response — 200 OK

FieldTypeNotes
accessTokenstringRS256 JWT, 15-min TTL.
refreshTokenstring256-bit opaque, 30-day TTL, single-use rotating.
userobjectSee below.

User object

FieldTypeAllowed valuesExample
idstring24-char Mongo ObjectId6a22f1897f96f4bd18ab7168
emailstringlowercasedalice@example.com
firstNamestring | nullnull until collected at signupAlice
lastNamestring | nullnull until collected at signupAndersson
avatarUrlstring | nullPublic CDN URL of the profile photo, or nullnull
emailVerifiedbooleanAlways true on this responsetrue
onboardingStepstringnormalized lowercase of OnboardingStatusin_progress
tenancyStatusstringnormalized lowercasenot_submitted
subscriptionStatusstringnormalized lowercasefree_launch

Example response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "v8q3xZ0p6rW7sT4uV1nB2cX9yY8mK5jL6hG7fD3eA0c",
  "user": {
    "id": "6a22f1897f96f4bd18ab7168",
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": "Andersson",
    "avatarUrl": null,
    "emailVerified": true,                 // literal: true
    "onboardingStep": "in_progress",       // enum: "in_progress" | "complete"
    "tenancyStatus": "not_submitted",      // enum: "not_submitted" | "pending" | "approved" | "rejected"
    "subscriptionStatus": "free_launch"    // enum: "none" | "trialing" | "active" | "past_due" | "cancelled" | "free_launch"
  }
}

Error responses

StatusCodeMeaning
400VALIDATION_FAILEDEmail malformed, or code is not exactly 6 digits.
401INVALID_CODEWrong digits. attemptsUsed was bumped; you have at most 5 wrong tries before the row dies.
401CODE_EXPIREDNo live OTP for this email — either it expired (5-min TTL), it was already consumed, or the attempt cap was hit. Request a fresh code via /resend-verify-email.

Example error — 401 INVALID_CODE

{
  "type": "https://api.swappr.co.uk/errors/invalid-code",
  "title": "Verification code incorrect",
  "status": 401,
  "code": "INVALID_CODE",
  "detail": "Verification code is incorrect",
  "instance": "/api/v1/auth/verify-email",
  "requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}

Side effects

  • Marks the OTP row consumed (consumedAt = now).
  • Sets users.emailVerified = true.
  • Inserts a refresh_tokens row keyed by the new session id.

See also

curl

curl -X POST https://api.swappr.co.uk/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "code": "482301"
  }'