List own medical certificates and insurance

Overview

Lists the authenticated user's own medical certificates and insurance, with the state the model computes for each: whether one is required, whether it is valid, expired, approved or rejected. Served by DocumentController::medical(). Any authenticated user can call it, whatever their role.

The files come from the same collections POST /api/v1/diver/documents writes to (medical_certificate, medical_certificate_professional, insurance_certificate), which GET /api/v1/diver/documents does not list.

Controller: App\Http\Controllers\Api\V1\Diver\DocumentController::medical()
Route name: api.v1.diver.medical-documents.index

Authentication

Type: Bearer Token
Header: Authorization: Bearer {token}

Request

Method: GET
Path: /api/v1/diver/medical-documents

No parameters and no body.

Example request

Response `200 OK`

Captured live against a professional with 4 medical certificates and 3 insurance documents, abbreviated to 2 of each. Issuer, number and file names are replaced with examples; every other value is as returned.

{
  "success": true,
  "status": "success",
  "message": "OK",
  "data": {
    "medical_certificate": {
      "required": false,
      "valid": true,
      "expired": false,
      "approved": false,
      "rejected": false,
      "current": {
        "id": 112465,
        "name": "example-certificate-1.jpg",
        "file_name": "example-certificate-1.jpg",
        "mime_type": "image/jpeg",
        "size": 1019974,
        "url": "https://raid-backend.s3.amazonaws.com/user_documents/112465/example-certificate-1.jpg",
        "created_at": "2026-04-27 20:06:20",
        "document": {
          "id": 7102,
          "type": "pro_medical_certificate",
          "status": "pending",
          "is_professional": true,
          "issuer": "Example Issuer",
          "number": "EX-7102",
          "issue_date": "2026-04-24",
          "expire_date": "2027-04-23",
          "approved_at": null,
          "rejected_at": null,
          "reject_notation": null
        }
      },
      "documents": [
        {
          "id": 112465,
          "name": "example-certificate-1.jpg",
          "file_name": "example-certificate-1.jpg",
          "mime_type": "image/jpeg",
          "size": 1019974,
          "url": "https://raid-backend.s3.amazonaws.com/user_documents/112465/example-certificate-1.jpg",
          "created_at": "2026-04-27 20:06:20",
          "document": {
            "id": 7102,
            "type": "pro_medical_certificate",
            "status": "pending",
            "is_professional": true,
            "issuer": "Example Issuer",
            "number": "EX-7102",
            "issue_date": "2026-04-24",
            "expire_date": "2027-04-23",
            "approved_at": null,
            "rejected_at": null,
            "reject_notation": null
          }
        },
        {
          "id": 112462,
          "name": "example-certificate-2.jpg",
          "file_name": "example-certificate-2.jpg",
          "mime_type": "image/jpeg",
          "size": 1086530,
          "url": "https://raid-backend.s3.amazonaws.com/user_documents/112462/example-certificate-2.jpg",
          "created_at": "2026-04-27 19:46:50",
          "document": {
            "id": 7099,
            "type": "diver_medical_certificate",
            "status": "approved",
            "is_professional": true,
            "issuer": "Example Issuer",
            "number": "EX-7099",
            "issue_date": "2026-04-24",
            "expire_date": "2027-04-23",
            "approved_at": "2026-04-27 19:46:50",
            "rejected_at": null,
            "reject_notation": null
          }
        }
      ]
    },
    "insurance": {
      "required": false,
      "valid": true,
      "expired": false,
      "approved": true,
      "rejected": false,
      "current": {
        "id": 112464,
        "name": "example-certificate-3.jpg",
        "file_name": "example-certificate-3.jpg",
        "mime_type": "image/jpeg",
        "size": 146424,
        "url": "https://raid-backend.s3.amazonaws.com/user_documents/112464/example-certificate-3.jpg",
        "created_at": "2026-04-27 20:05:29",
        "document": {
          "id": 7101,
          "type": "pro_insurance",
          "status": "approved",
          "is_professional": true,
          "issuer": "Example Issuer",
          "number": "EX-7101",
          "issue_date": "2026-04-22",
          "expire_date": "2027-04-21",
          "approved_at": "2026-05-13 18:07:16",
          "rejected_at": null,
          "reject_notation": null
        }
      },
      "documents": [
        {
          "id": 112464,
          "name": "example-certificate-3.jpg",
          "file_name": "example-certificate-3.jpg",
          "mime_type": "image/jpeg",
          "size": 146424,
          "url": "https://raid-backend.s3.amazonaws.com/user_documents/112464/example-certificate-3.jpg",
          "created_at": "2026-04-27 20:05:29",
          "document": {
            "id": 7101,
            "type": "pro_insurance",
            "status": "approved",
            "is_professional": true,
            "issuer": "Example Issuer",
            "number": "EX-7101",
            "issue_date": "2026-04-22",
            "expire_date": "2027-04-21",
            "approved_at": "2026-05-13 18:07:16",
            "rejected_at": null,
            "reject_notation": null
          }
        },
        {
          "id": 82019,
          "name": "example-certificate-4.jpg",
          "file_name": "example-certificate-4.jpg",
          "mime_type": "image/jpeg",
          "size": 520260,
          "url": "https://raid-backend.s3.amazonaws.com/user_documents/82019/example-certificate-4.jpg",
          "created_at": "2025-04-09 09:53:35",
          "document": {
            "id": 547,
            "type": "pro_insurance",
            "status": "approved",
            "is_professional": true,
            "issuer": "Example Issuer",
            "number": "EX-547",
            "issue_date": "2025-04-21",
            "expire_date": "2026-04-20",
            "approved_at": "2025-04-10 15:33:13",
            "rejected_at": null,
            "reject_notation": null
          }
        }
      ]
    }
  }
}

A user with no documents (captured live; a diver with nothing uploaded):

{
  "success": true,
  "status": "success",
  "message": "OK",
  "data": {
    "medical_certificate": {
      "required": false,
      "valid": true,
      "expired": true,
      "approved": false,
      "rejected": false,
      "current": null,
      "documents": []
    },
    "insurance": {
      "required": false,
      "valid": false,
      "expired": true,
      "approved": false,
      "rejected": false,
      "current": null,
      "documents": []
    }
  }
}

Response fields

data has two sections, medical_certificate and insurance, with the same keys.

Field	Type	Nullable	Notes
`required`	`boolean`	No	Medical: the distributor setting `pro_certificate_required` for a user whose qualification is professional, `certificate_required` otherwise. Insurance: the distributor setting `pro_insurance_required` for a professional qualification, always `false` otherwise. It follows the user's qualification, not the `professional` role the upload uses
`valid`	`boolean`	No	Medical: `true` when no certificate is required (by the distributor or by a medical condition declared in the last medical form), otherwise `true` only when the current certificate exists, has not expired and is approved. Insurance: `false` when the user has no insurance, even when none is required; otherwise, when insurance is required, `true` only if the current one has not expired and is approved, and when it is not required `true`
`expired`	`boolean`	No	`true` when there is no current document. Medical: the current certificate's `expire_date` is in the past. Insurance: its `expire_date` is not after now in the user's timezone
`approved`	`boolean`	No	The current document exists and has `approved_at` set (it reads the date, not `status`)
`rejected`	`boolean`	No	The current document exists and has `rejected_at` set
`current`	`object`	Yes	The item of the user's current document, or `null` when there is none. See below
`documents`	`array`	No	Every document of the section, newest upload first (`created_at`, then `id`). Medical covers both `diver_medical_certificate` and `pro_medical_certificate`

The current document is the one with the latest expire_date, ties broken by the latest created_at, among documents that have a file. So current is not always documents[0]: a newer upload with an earlier expiry sits first in documents, while current stays the one that expires last.

Item fields

The first seven keys are the item shape of GET /api/v1/diver/documents (see ../documents/GET_list.md) and document is the object of the upload response (see ../documents/POST_upload.md), with three keys added.

Field	Type	Nullable	Notes
`id`, `name`, `file_name`, `mime_type`, `size`, `url`, `created_at`		Yes	All `null` when the document's file no longer exists. The document is still listed
`document.id`	`integer`	No	`Document` row id
`document.type`	`string`	No	`diver_medical_certificate`, `pro_medical_certificate` or `pro_insurance`
`document.status`	`string`	No	`pending`, `approved` or `rejected`
`document.is_professional`	`boolean`	No
`document.issuer`, `document.number`	`string`	Yes
`document.issue_date`, `document.expire_date`	`string`	Yes	`Y-m-d`
`document.approved_at`	`string`	Yes	`Y-m-d H:i:s`. Only in this list, not in the upload response
`document.rejected_at`	`string`	Yes	`Y-m-d H:i:s`. Only in this list
`document.reject_notation`	`string`	Yes	The reason the reviewer gave when rejecting, up to 200 characters. Only in this list

Errors

`401 Unauthorized`

{
  "success": false,
  "status": "error",
  "message": "Unauthenticated"
}

Notes

Read-only, no side effects. The number of database queries does not depend on the number of documents.

There is no way to delete or replace a document through the API. Uploading a sixth document of a type deletes the oldest one.

A user without a distributor cannot be evaluated: the response is a 500. Their uploads fail the same way.

Source: docs/api/diver/medical-documents/GET_list.md

List own medical certificates and insurance

Overview#

Authentication#

Request#

Example request#

Response 200 OK#

Response fields#

Item fields#

Errors#

401 Unauthorized#

Notes#

Request

Responses

Overview

Authentication

Request

Example request

Response `200 OK`

Response fields

Item fields

Errors

`401 Unauthorized`

Notes