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

# Check KYC Verification

> Check KYC verification status for a user account

## Overview

Check the KYC (Know Your Customer) verification status for a user account. This endpoint returns whether the user is verified, their money transfer limit, and a verification URL if needed.

## KYC Provider

CashQ uses [Veriff](https://www.veriff.com/) as our Attested KYC provider for identity verification.

<Info>
  **Custom Veriff Integration**

  If you are using your own Veriff account, we can integrate with your Veriff API key to maintain a unified verification experience.
</Info>

<Note>
  **Alternative KYC Providers**

  If you need to use another KYC provider, please contact [support@mycashq.com](mailto:support@mycashq.com) to discuss integration options.
</Note>

## Endpoint

```http theme={null}
GET /api/kyc/:account
```

## Path Parameters

<ParamField path="account" type="string" required>
  User account ID (phone number in E.164 format without the `+` sign)

  **Format:** `[country code][subscriber number including area code]`

  **Example:** `16175551212` for a US number
</ParamField>

<Warning>
  **Phone Number Format**

  Phone numbers must be in E.164 international standard **without** the `+` sign:

  * ✅ Correct: `16175551212`
  * ❌ Incorrect: `+16175551212`
  * ❌ Incorrect: `6175551212` (missing country code)
</Warning>

## Authentication

<ParamField header="API-KEY" type="string" required>
  Your CashQ API Key for authentication
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.cashqbot.com/api/kyc/16175551212' \
    -H 'API-KEY: your_api_key_here'
  ```

  ```javascript Node.js theme={null}
  const phoneNumber = '16175551212';

  const response = await fetch(
    `https://api.cashqbot.com/api/kyc/${phoneNumber}`,
    {
      method: 'GET',
      headers: {
        'API-KEY': 'your_api_key_here'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  phone_number = '16175551212'

  response = requests.get(
      f'https://api.cashqbot.com/api/kyc/{phone_number}',
      headers={'API-KEY': 'your_api_key_here'}
  )

  data = response.json()
  print(data)
  ```

  ```php PHP theme={null}
  <?php
  $phoneNumber = '16175551212';

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, "https://api.cashqbot.com/api/kyc/{$phoneNumber}");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'API-KEY: your_api_key_here'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  print_r($data);
  ?>
  ```
</CodeGroup>

## Response

<ResponseField name="kyc_verify" type="boolean" required>
  KYC verification status

  * `true`: User is verified
  * `false`: User is not verified or has limited verification
</ResponseField>

<ResponseField name="money_limit" type="string" required>
  Maximum amount the user can receive in a single transfer (in dollars)

  * If `"0"`: User cannot receive money transfers
  * Otherwise: Maximum transfer amount allowed
</ResponseField>

<ResponseField name="kyc_url" type="string" required>
  URL to redirect user for KYC verification

  * Empty string (`""`) if user is fully verified
  * Contains verification URL if user needs to complete KYC
</ResponseField>

## Response Examples

<ResponseExample>
  ```json Verified User theme={null}
  {
    "kyc_verify": true,
    "money_limit": "8990",
    "kyc_url": ""
  }
  ```

  ```json Unverified User theme={null}
  {
    "kyc_verify": false,
    "money_limit": "600",
    "kyc_url": "https://link.cashqbot.com/j2tf"
  }
  ```

  ```json No Transfer Ability theme={null}
  {
    "kyc_verify": false,
    "money_limit": "0",
    "kyc_url": "https://link.cashqbot.com/j2tf"
  }
  ```

  ```json Error - Invalid Phone theme={null}
  {
    "error": {
      "message": "Invalid phone number format",
      "code": "invalid_phone_number"
    },
    "success": "false"
  }
  ```
</ResponseExample>

## Understanding KYC Status

### Verified Users (`kyc_verify: true`)

* User has completed full KYC verification
* Can receive transfers up to their `money_limit`
* No additional verification needed
* `kyc_url` will be empty

### Unverified Users (`kyc_verify: false`)

* User has limited or no verification
* Can only receive transfers up to their `money_limit`
* Should be directed to `kyc_url` to complete verification
* After verification, their `money_limit` will increase

### Money Limit Interpretation

| money\_limit | Meaning                                |
| ------------ | -------------------------------------- |
| `"0"`        | Cannot receive any transfers           |
| `"600"`      | Can receive up to \$600 per transfer   |
| `"8990"`     | Can receive up to \$8,990 per transfer |

## Phone Number Formatting

### Converting to E.164 Format

<CodeGroup>
  ```javascript Node.js theme={null}
  function formatPhoneNumber(phone, countryCode = '1') {
    // Remove all non-digit characters
    const digits = phone.replace(/\D/g, '');
    
    // Add country code if not present
    if (!digits.startsWith(countryCode)) {
      return countryCode + digits;
    }
    
    return digits;
  }

  // Examples
  formatPhoneNumber('(617) 555-1212', '1');  // Returns: 16175551212
  formatPhoneNumber('+1-617-555-1212', '1'); // Returns: 16175551212
  formatPhoneNumber('6175551212', '1');      // Returns: 16175551212
  ```

  ```python Python theme={null}
  import re

  def format_phone_number(phone, country_code='1'):
      # Remove all non-digit characters
      digits = re.sub(r'\D', '', phone)
      
      # Add country code if not present
      if not digits.startswith(country_code):
          return country_code + digits
      
      return digits

  # Examples
  format_phone_number('(617) 555-1212', '1')  # Returns: 16175551212
  format_phone_number('+1-617-555-1212', '1') # Returns: 16175551212
  format_phone_number('6175551212', '1')      # Returns: 16175551212
  ```
</CodeGroup>

## Error Responses

| Error Code              | Description                      | Solution                           |
| ----------------------- | -------------------------------- | ---------------------------------- |
| `authentication_error`  | Invalid or missing API key       | Verify your API key                |
| `invalid_phone_number`  | Phone number format is incorrect | Use E.164 format without `+`       |
| `account_not_found`     | Account doesn't exist            | Verify the phone number is correct |
| `internal_server_error` | Server error occurred            | Retry the request                  |

## Best Practices

<AccordionGroup>
  <Accordion title="Always check before transfers">
    Check KYC status before initiating any transfer to avoid failures due to verification limits.
  </Accordion>

  <Accordion title="Cache KYC status appropriately">
    Cache KYC status for a reasonable time (e.g., 1 hour) but refresh before large transfers.
  </Accordion>

  <Accordion title="Provide clear user guidance">
    If a user needs verification, clearly explain why and provide the verification URL.
  </Accordion>

  <Accordion title="Validate phone numbers">
    Validate and format phone numbers on your end before sending to the API.
  </Accordion>

  <Accordion title="Handle all limit scenarios">
    Account for all cases: fully verified, partially verified, and unverified users.
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Check Transfer" icon="magnifying-glass" href="/api-reference/check-transfer">
    Validate transfer details including KYC requirements
  </Card>

  <Card title="Money Transfer" icon="money-bill-transfer" href="/api-reference/transfer">
    Execute a money transfer after KYC verification
  </Card>
</CardGroup>