# Retrieve pending notes for the merchant application

## Retrieve Underwriting Notes

Fetches a list of pending underwriting notes for a specific merchant application. Each note includes the note text, the author who created it, and the timestamp. Use this endpoint during the underwriting workflow to review unresolved comments before advancing the application to the next status.

### Endpoint

`GET /api/v1/merchant/underwritingNotes`

### Authentication

Basic HTTP Authentication required.
Encode `username:password` in Base64 and pass in the Authorization header:

```
Authorization: Basic {base64(username:password)}
```

### When to use

Call this endpoint after a merchant application enters underwriting (status "UW Level 1") to check whether the underwriter has left notes that require action before the application can be advanced. It is also useful for auditing purposes to confirm all notes have been addressed before calling `underwritingReview`.

### Query Parameters

| Parameter | Type            | Required | Description                                                       |
| --------- | --------------- | -------- | ----------------------------------------------------------------- |
| id        | integer (int32) | Yes      | The merchant profile ID for which to retrieve underwriting notes. |

### Response

**200 OK**

| Field             | Type               | Description                                                      |
| ----------------- | ------------------ | ---------------------------------------------------------------- |
| data              | array              | Array of `Note` objects representing pending underwriting notes. |
| data\[].text      | string             | The content of the underwriting note.                            |
| data\[].author    | string             | Username or name of the person who wrote the note.               |
| data\[].date      | string (date-time) | ISO 8601 timestamp when the note was created.                    |
| status            | string             | HTTP status name (e.g., `"OK"`).                                 |
| error             | string             | Error message if the request failed; otherwise null.             |
| warning           | string             | Non-fatal warning message, if any.                               |
| validationResults | array              | Validation errors, if any.                                       |
| requestId         | integer            | Internal request tracking ID.                                    |

```json
{
  "data": [
    {
      "text": "Missing voided check — please upload bank account proof before approval.",
      "author": "j.underwriter",
      "date": "2026-05-10T14:32:00Z"
    },
    {
      "text": "Federal Tax ID format appears invalid. Confirm EIN with merchant.",
      "author": "j.underwriter",
      "date": "2026-05-11T09:15:00Z"
    }
  ],
  "status": "OK",
  "error": null,
  "warning": null,
  "validationResults": [],
  "requestId": 84712
}
```

### Error Codes

| Code | When it happens                                             |
| ---- | ----------------------------------------------------------- |
| 400  | The `id` query parameter is missing or not a valid integer. |
| 401  | Invalid or missing Basic Auth credentials.                  |
| 403  | User does not have permission for this operation.           |
| 404  | No merchant application found with the given ID.            |
| 500  | Internal server error.                                      |

### Common Mistakes

* Omitting the `id` query parameter entirely results in a 400 error.
* Passing a merchant ID that belongs to a different ISO than the authenticated user returns 403.
* Expecting notes to be returned when none exist — an empty `data` array is a valid 200 response indicating no pending notes.

### Related Endpoints

* `POST /api/v1/merchant/attachment` — Upload supporting documents to address note requests.
* `POST /api/v1/merchant/underwritingReview` — Advance the application from "Pending" to "Pending Review" after notes are resolved.
* `POST /api/v1/merchant/underwritingPending` — Set the merchant status back to "UW Level 1: Pending".

### Example

```bash
curl -X GET "https://hq.staging.netevia.dev/api/v1/merchant/underwritingNotes?id=10482" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Content-Type: application/json"
```

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "v1",
    "title": "Netevia HQ | API Documentation",
    "description": "Netevia HQ | API Documentation"
  },
  "paths": {
    "/api/v1/merchant/underwritingNotes": {
      "get": {
        "tags": [
          "Merchant applications/Merchants notes and attachments"
        ],
        "summary": "Retrieve pending notes for the merchant application",
        "operationId": "Boarding_GetUnderwritingNotes",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseArray1_Note"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseArray1_Note"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseArray1_Note"
                }
              },
              "text/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponseArray1_Note"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "Basic": []
    }
  ],
  "servers": [
    {
      "url": "https://hq.staging.netevia.dev"
    }
  ],
  "components": {
    "securitySchemes": {
      "Basic": {
        "type": "http",
        "description": "Basic HTTP Authentication",
        "scheme": "basic"
      }
    },
    "schemas": {
      "ValidationResult": {
        "type": "object",
        "properties": {
          "memberNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "readOnly": true
          },
          "errorMessage": {
            "type": "string"
          }
        }
      },
      "ApiResponseArray1_Note": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Note"
            }
          },
          "status": {
            "enum": [
              "Continue",
              "SwitchingProtocols",
              "OK",
              "Created",
              "Accepted",
              "NonAuthoritativeInformation",
              "NoContent",
              "ResetContent",
              "PartialContent",
              "MultipleChoices",
              "Ambiguous",
              "MovedPermanently",
              "Moved",
              "Found",
              "Redirect",
              "SeeOther",
              "RedirectMethod",
              "NotModified",
              "UseProxy",
              "Unused",
              "TemporaryRedirect",
              "RedirectKeepVerb",
              "BadRequest",
              "Unauthorized",
              "PaymentRequired",
              "Forbidden",
              "NotFound",
              "MethodNotAllowed",
              "NotAcceptable",
              "ProxyAuthenticationRequired",
              "RequestTimeout",
              "Conflict",
              "Gone",
              "LengthRequired",
              "PreconditionFailed",
              "RequestEntityTooLarge",
              "RequestUriTooLong",
              "UnsupportedMediaType",
              "RequestedRangeNotSatisfiable",
              "ExpectationFailed",
              "UpgradeRequired",
              "InternalServerError",
              "NotImplemented",
              "BadGateway",
              "ServiceUnavailable",
              "GatewayTimeout",
              "HttpVersionNotSupported"
            ],
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "warning": {
            "type": "string"
          },
          "validationResults": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationResult"
            }
          },
          "requestId": {
            "format": "int32",
            "type": "integer"
          }
        }
      },
      "Note": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "date": {
            "format": "date-time",
            "type": "string"
          }
        }
      }
    }
  }
}
```