# Verify user email

> **Legacy.** This endpoint is kept for existing integrations. Use the current API reference for new work.

Verify user email

- Endpoint: `POST https://api.returning.ai/auth/verify-email`
- Section: Legacy / Authentication
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/legacy-authentication/verify-user-email

## Authentication

- Header: `Authorization: Bearer <API_KEY>`

## Behaviour

**What it is for**

Verify user email. Use this as part of password-based account authentication rather than broker system ingestion.

**How to use it**

Send a POST request to `/auth/verify-email` with the request body, query parameters, or multipart fields shown below. Authentication endpoint. It does not use the broker integration API key in the same way as `/v1/...` endpoints.

**Successful response**

HTTP 200. The body follows the endpoint schema; many integration endpoints wrap the useful payload under `data` with `status` and `message`.

**Common error states**

- `400` invalid request body, query, ObjectId, pagination, file format, or missing required field.
- `401` missing, invalid, expired, or insufficient API key/token.
- `403` key is valid but cannot access this community/channel/user/resource, where supported by the service.
- `404` target resource, route, or community-scoped record was not found.
- `409` duplicate or conflicting state for create/update operations, where applicable.
- `500` unexpected Returning.AI service error.

## Request

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | API key. (`Bearer <API_KEY>`) |
| `Content-Type` | `string` | Yes | Request body format. (`application/json`) |

### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | Yes | User email address. |
| `code` | `string` | Yes | - |
| `host` | `string` | No | - |

### Example request

```bash
curl --request POST \
  --url https://api.returning.ai/auth/verify-email \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "samoqa@koletter.com",
    "code": "441225",
    "host": "ic.genesiv.com"
  }'
```

## Response

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | - |
| `meta.success` | `boolean` | always | - |
| `meta.message` | `string` | always | - |
| `meta.devMessage` | `string` | always | - |
| `body` | `object` | always | - |
| `accessToken` | `string` | always | - |
| `refreshToken` | `string` | always | - |

### Example response (200)

```json
{
  "meta": {
    "success": true,
    "message": "Email has been verified successfully",
    "devMessage": "Email has been verified successfully"
  },
  "body": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIiLCJpYXQiOjE3MjE5MjI1MTYsImV4cCI6MTcyMjAwODkxNn0.RU6HbgnjhudD5h1hjCQ0OBo5HD2ANRtw8VNKHBLdvMA",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjIiLCJpYXQiOjE3MjE5MjI1MTYsImV4cCI6MTcyMjUyNzMxNn0.95J7P0_vUGnAKARhwVhws0T-M_yZNzu-i-2XY-5H-Hk"
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | Invalid request. Check required parameters, body fields, file format, pagination values, and ObjectId values. |
| 401 | - | Verification token is missing, invalid, or expired. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | User or verification record was not found. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | Unexpected Returning.AI service error. |

## Next step

- [Log in user with password](https://docs.returning.ai/api-reference/legacy-authentication/log-in-user-with-password.md): `POST /auth/login`.