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

# Start Card Onboarding

> Initiate Yativo Card onboarding for your own account. Generates a wallet, authenticates with the card provider, and sends an OTP to your email.

<ParamField header="Authorization" type="string" required>
  Bearer token: `Bearer YOUR_ACCESS_TOKEN`
</ParamField>

<ParamField body="email" type="string" required>
  Your email address. Yativo sends a one-time verification code here. Must not already be in use by an active card session under your account.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/onboard' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"email": "you@example.com"}'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://crypto-api.yativo.com/api/v1/yativo-card/onboard',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email: 'you@example.com' }),
    }
  );
  const { data } = await response.json();
  // data.yativo_card_id — save this for all subsequent calls
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "success": true,
    "message": "Card onboarding initiated. Check your email for verification code.",
    "data": {
      "yativo_card_id": "yativo_card_0xAbCd1234EfGh5678IjKl9012_1769031332068",
      "email_masked": "yo***@example.com",
      "next_step": "verify_otp",
      "otp_expires_in_seconds": 600
    }
  }
  ```

  ```json 400 Invalid email theme={null}
  {
    "success": false,
    "error_code": "INVALID_EMAIL",
    "message": "Valid email is required"
  }
  ```

  ```json 400 Already in progress theme={null}
  {
    "success": false,
    "error_code": "CARD_ALREADY_ACTIVE",
    "message": "Card onboarding already in progress",
    "data": {
      "yativo_card_id": "yativo_card_0xAbCd1234EfGh5678IjKl9012_1769031332068",
      "flow_status": "otp_requested",
      "next_step": "verify_otp"
    }
  }
  ```

  ```json 400 Session expired theme={null}
  {
    "success": false,
    "error_code": "JWT_EXPIRED",
    "message": "Session expired. Please re-authenticate.",
    "data": {
      "yativo_card_id": "yativo_card_0xAbCd1234EfGh5678IjKl9012_1769031332068",
      "needs_reauth": true,
      "flow_status": "kyc_initiated"
    }
  }
  ```
</ResponseExample>

## Next Steps

After a `201` response, check your email for the OTP and continue:

1. **Verify OTP** — `POST /v1/yativo-card/{yativoCardId}/verify-otp`
2. **Get KYC link** — `GET /v1/yativo-card/{yativoCardId}/kyc-link`
3. **Poll KYC status** — `GET /v1/yativo-card/{yativoCardId}/kyc-status`
4. **Deploy card wallet** — `POST /v1/yativo-card/{yativoCardId}/safe/deploy`
5. **Create virtual card** — `POST /v1/yativo-card/{yativoCardId}/cards/virtual`