diver

Overview

Searches divers (non-professionals) in the RAID network. Unlike the instructor search, at least one of search or country is required - it is not possible to retrieve a full list of all divers. For divers under 16 years of age, email and mobile are automatically masked.

Authentication

Type: API Key
Header: token: {your-api-key}

Request

Method: POST
Path: /api/v1/diver
Content-Type: application/json or application/x-www-form-urlencoded

Body parameters

Parameter	Type	Required	Description
`search`	`string`	Conditional	Free text - searches across: `first_name`, `last_name`, `full_name`, `city`, `email`, `raid_id`
`country`	`string`	Conditional	ISO 3166-1 alpha-2 country code (e.g. `IT`, `ES`)

At least one of search or country is required. If neither is provided, the endpoint returns an error response.

Response `200 OK` - Results found

{
  "data": [
    {
      "raid_id": "RAID-IT-98765",
      "first_name": "Giulia",
      "last_name": "Bianchi",
      "age": 28,
      "avatar": "https://s3.amazonaws.com/diveraid/avatars/120.jpg",
      "email": "giulia.bianchi@example.com",
      "country": "Italy",
      "city": "Milan",
      "mobile": "+39 347 9876543",
      "diver_certifications": [
        "Open Water Diver",
        "Advanced Open Water"
      ]
    }
  ],
  "success": true,
  "message": "success",
  "total": 1
}

Response `200 OK` - No results

{
  "data": [],
  "success": true,
  "message": "no results",
  "total": 0
}

Response `200 OK` - Missing parameters

When neither search nor country are provided, the endpoint responds with 200 but success: false:

{
  "success": false,
  "message": "Search query or country is required!"
}

`data[]` fields

Field	Type	Description
`raid_id`	`string`	Diver's unique RAID identifier
`first_name`	`string`	First name
`last_name`	`string`	Last name
`age`	`integer\|null`	Age calculated from date of birth (`null` if not available)
`avatar`	`string\|null`	Profile photo URL
`email`	`string`	Email (masked for minors: `gu*@ex***.com`)
`country`	`string`	Full country name (e.g. `"Italy"`)
`city`	`string\|null`	City
`mobile`	`string\|null`	Phone number (masked for minors: `+39 3 **543`)
`diver_certifications`	`array`	Diver's RAID certifications, sorted by name

Response `401` - Missing or invalid API Key

{
  "error": "Access Denied!",
  "message": "No API Key provided.",
  "statusCode": 401
}

Minor data protection

For divers aged under 16, sensitive fields are masked using Str::mask():

email: first 2 characters visible, then ***, domain partially masked

mobile: prefix visible, then ***, last 3 characters visible

This behaviour is automatic and not configurable - it ensures GDPR compliance for minors.

Search examples

Search by name:

{ "search": "Giulia" }

Filter by country:

{ "country": "IT" }

Combined search:

{ "search": "Bianchi", "country": "IT" }

Notes

Search is case-insensitive using LIKE %search%.

Results are ordered by full_name ASC.

Unlike the instructor search, does not include pro_certifications, experience, or professional_status.

The mandatory-parameter constraint prevents full database dumps of diver records.

Responses

🟢200Response OK

application/json

Search results

Bodyapplication/json

Example

{
    "data": [
        {
            "raid_id": "GBXX-123-123",
            "first_name": "Marc",
            "last_name": "Smith",
            "age": 56,
            "avatar": "https://raid-backend/GBXX-123-123.webp",
            "email": "marc.smith@email.com",
            "country": "United Kingdom",
            "city": "London",
            "mobile": "+44xxxxxxxxx",
            "diver_certifications": [
                "Scuba Reboot"
            ]
        }
    ],
    "success": true,
    "message": "success",
    "total": 1
}

🟠401API Key error

🟠422Missing Data

Search divers

POST /api/v1/diver

Overview

Authentication

Request

Body parameters

Response `200 OK` - Results found

Response `200 OK` - No results

Response `200 OK` - Missing parameters

`data[]` fields

Response `401` - Missing or invalid API Key

Minor data protection

Search examples

Notes

Request

Request Code Samples

Responses

Search results

Search divers

POST /api/v1/diver#

Overview#

Authentication#

Request#

Body parameters#

Response 200 OK - Results found#

Response 200 OK - No results#

Response 200 OK - Missing parameters#

data[] fields#

Response 401 - Missing or invalid API Key#

Minor data protection#

Search examples#

Notes#

Request

Request Code Samples

Responses

Search results

POST /api/v1/diver

Overview

Authentication

Request

Body parameters

Response `200 OK` - Results found

Response `200 OK` - No results

Response `200 OK` - Missing parameters

`data[]` fields

Response `401` - Missing or invalid API Key

Minor data protection

Search examples

Notes