> ## Documentation Index
> Fetch the complete documentation index at: https://clear.nfigate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Verification

> Create a new KYC or KYB verification

# Create Verification

Create a new verification request for an individual (KYC) or business (KYB).

## Request

### Headers

| Header       | Required | Description                |
| ------------ | -------- | -------------------------- |
| X-API-Key    | Yes      | Your API key               |
| Content-Type | Yes      | Must be `application/json` |

### Body Parameters

```json theme={null}
{
  "subjectType": "kyc",
  "subjectReference": "user-12345",
  "metadata": {
    "customerId": "cus_12345"
  }
}
```

| Parameter        | Type   | Required | Description                                    |
| ---------------- | ------ | -------- | ---------------------------------------------- |
| subjectType      | string | Yes      | Type of verification: `kyc` or `kyb`           |
| subjectReference | string | Yes      | Your unique identifier for this subject        |
| metadata         | object | No       | Additional data to store with the verification |

## Response

### Success (201 Created)

```json theme={null}
{
  "success": true,
  "data": {
    "id": "abc123def456",
    "type": "kyc",
    "subjectReference": "user-12345",
    "status": "pending",
    "requestedAt": "2024-01-15T10:30:00.000Z",
    "currentStep": 0,
    "verificationUrl": "https://app.nfi-clear.com/verify/abc123def456"
  },
  "message": "Verification created successfully"
}
```

## Example

### cURL

```bash theme={null}
curl -X POST 'https://clear-api.nfigate.com/api/v1/verifications' \
  -H 'X-API-Key: nfi_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "subjectType": "kyc",
    "subjectReference": "user-12345",
    "metadata": {
      "customerId": "cus_12345"
    }
  }'
```

### JavaScript

```javascript theme={null}
const response = await fetch('https://clear-api.nfigate.com/api/v1/verifications', {
  method: 'POST',
  headers: {
    'X-API-Key': 'nfi_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    subjectType: 'kyc',
    subjectReference: 'user-12345',
  }),
});

const data = await response.json();
console.log('Verification URL:', data.data.verificationUrl);
```

## Error Responses

| Status | Code                          | Description                        |
| ------ | ----------------------------- | ---------------------------------- |
| 400    | `INVALID_SUBJECT_TYPE`        | subjectType must be "kyc" or "kyb" |
| 400    | `MISSING_SUBJECT_REFERENCE`   | subjectReference is required       |
| 403    | `NO_ACTIVE_SUBSCRIPTION`      | No active subscription found       |
| 403    | `LIMIT_EXCEEDED`              | Monthly verification limit reached |
| 409    | `DUPLICATE_SUBJECT_REFERENCE` | Active verification already exists |


## OpenAPI

````yaml POST /verifications
openapi: 3.0.0
info:
  title: NFI Clear API
  description: Identity verification platform for KYC and KYB
  version: 1.0.0
  contact:
    email: support@nfi-clear.com
servers:
  - url: https://clear-api.nfigate.com/api/v1
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /verifications:
    post:
      summary: Create Verification
      description: Create a new KYC or KYB verification
      operationId: createVerification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequest'
            examples:
              kyc:
                summary: KYC Verification
                value:
                  subjectType: kyc
                  subjectReference: user-12345
                  metadata:
                    customerId: cus_12345
              kyb:
                summary: KYB Verification
                value:
                  subjectType: kyb
                  subjectReference: company-67890
                  metadata:
                    companyId: comp_67890
      responses:
        '201':
          description: Verification created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
        '403':
          description: Forbidden - Subscription issue
        '409':
          description: Conflict - Duplicate subject reference
components:
  schemas:
    CreateVerificationRequest:
      type: object
      required:
        - subjectType
        - subjectReference
      properties:
        subjectType:
          type: string
          enum:
            - kyc
            - kyb
          description: Type of verification
        subjectReference:
          type: string
          description: Your unique identifier
        metadata:
          type: object
          description: Additional data
    VerificationResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Verification'
        message:
          type: string
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        code:
          type: string
        data:
          type: object
    Verification:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - kyc
            - kyb
        subjectReference:
          type: string
        status:
          type: string
          enum:
            - pending
            - submitted
            - action_needed
            - approved
            - rejected
        requestedAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
          nullable: true
        currentStep:
          type: integer
        verificationUrl:
          type: string
        submittedData:
          type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key from the dashboard

````