---
title: "Get applicant verification status"
description: "Retrieves the current KYC review status for a customer from the verification provider."
protocol: rest
method: GET
endpoint: "/v1/customers/{customer_id}/kyc/status"
baseUrl: "https://api.gravv.xyz"
group: "KYC"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Get applicant verification status

<Endpoint method="GET" path="/v1/customers/{customer_id}/kyc/status" />

Retrieves the current KYC review status for a customer from the verification provider.

Use this endpoint to check a customer's verification outcome after you initiate KYC. While a review is in progress, `reviewStatus` is `pending` and `reviewResult` is omitted. Once the review finishes, `reviewStatus` is `completed` and `reviewResult` contains the decision.

## Path Parameters

<ParamField name="customer_id" path="customer_id" type="string" required>
  UUID of the customer
</ParamField>

## Responses

| Status | Description |
| --- | --- |
| `200` | Current verification status retrieved |
| `400` | Invalid request |
| `404` | Customer or applicant not found |
| `500` | Internal processing error while retrieving status |

### 200 response

<ResponseField name="data" type="object" required>

  <Expandable title="properties">
    <ResponseField name="reviewStatus" type="string" required>
      Overall review status from the verification provider. `pending` while a review is in progress; `completed` once a decision is returned.
    </ResponseField>

    <ResponseField name="reviewResult" type="object">
      Review outcome. Present once `reviewStatus` is `completed`; omitted while the review is `pending`.

      <Expandable title="properties">
        <ResponseField name="reviewAnswer" type="string" required>
          Verification decision.

          Possible values: `approved`, `rejected`
        </ResponseField>

        <ResponseField name="rejectLabels" type="string[]">
          Reason codes for a rejection. Present only when `reviewAnswer` is `rejected`.
        </ResponseField>

        <ResponseField name="reviewRejectType" type="string">
          Rejection category, such as `RETRY`. Present only when `reviewAnswer` is `rejected`.
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="reviewDate" type="string">
      Timestamp of the review decision, in `YYYY-MM-DD HH:MM:SS+0000` format. Omitted while `reviewStatus` is `pending`.
    </ResponseField>

    <ResponseField name="priority" type="integer" required>
      Applicant review priority.
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="any" required>
  Error information if the request failed
</ResponseField>

<ResponseExample>

```json title="Approved"
{
  "data": {
    "reviewStatus": "completed",
    "reviewResult": {
      "reviewAnswer": "approved"
    },
    "reviewDate": "2026-06-19 21:59:00+0000",
    "priority": 0
  },
  "error": null
}
```

```json title="Rejected"
{
  "data": {
    "reviewStatus": "completed",
    "reviewResult": {
      "reviewAnswer": "rejected",
      "rejectLabels": [
        "BAD_SELFIE",
        "SCREENSHOTS",
        "UNSATISFACTORY_PHOTOS"
      ],
      "reviewRejectType": "RETRY"
    },
    "reviewDate": "2026-06-19 20:44:19+0000",
    "priority": 0
  },
  "error": null
}
```

```json title="Pending"
{
  "data": {
    "reviewStatus": "pending",
    "priority": 0
  },
  "error": null
}
```

</ResponseExample>

### 400 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseField name="error" type="any">

  <Expandable title="properties">
    <ResponseField name="code" type="any">
    </ResponseField>

    <ResponseField name="message" type="any">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The customer ID provided is not valid. Please verify the customer ID format."
  }
}
```

</ResponseExample>

### 404 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseField name="error" type="any">

  <Expandable title="properties">
    <ResponseField name="code" type="any">
    </ResponseField>

    <ResponseField name="message" type="any">
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseExample>

```json title="CustomerNotFound"
{
  "data": null,
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer not found. Please verify the customer exists in our system."
  }
}
```

```json title="NoApplicant"
{
  "data": null,
  "error": {
    "code": "KYC_NOT_FOUND",
    "message": "no applicant found for customer; KYC has not been initiated"
  }
}
```

</ResponseExample>

### 500 response

<ResponseField name="data" type="any" required>
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="string" required>
  Human-readable error message
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": {
    "code": "KYC_PROCESSING_ERROR",
    "message": "failed to retrieve applicant status"
  }
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**