---
title: "Request verification code by hash"
method: POST
path: "/v1/purchases-by-hash/{hash}/request-code"
tags: ["Purchases by Hash"]
---

# Request verification code by hash

`POST /v1/purchases-by-hash/{hash}/request-code`

## Request

- Base URL: `https://api.getmytg.com`
- URL: `https://api.getmytg.com/v1/purchases-by-hash/{hash}/request-code`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Requests verification code and password from provider using purchase hash code. Updates purchase status to SUCCESS.

**No authentication required.** The hash code serves as the access token.

**Idempotent Operation.** Safe to retry on network errors - will not generate duplicate codes.

**Path parameter `hash`.** If it is missing or empty before `/request-code` (e.g. `/v1/purchases-by-hash/request-code`), the API returns **400** with `fieldViolations` on `hash`.

## Path parameters

- `hash` string, required: Unique hash code of the purchase

## Request body

- object
  - `callback_url` string, uri: URL to receive webhook notification when code is received. POST request will be sent with either `WebhookSuccessPayload` or `WebhookFailedPayload`. **Retry policy.** If your endpoint does not return HTTP 200, webhook will be retried up to 3 times with delays: immediately, after 10 seconds, after 30 seconds. Any non-200 response triggers retry.

## Response `200`

Response for status 200

- object
  - `purchase` object, required
    - `id` integer, required: Unique purchase identifier.
    - `country_code` string, required: ISO 3166-1 alpha-2 country code.
    - `emoji` string, required: Country flag emoji.
    - `display_name` object, required
      - `ru` string, required: Name in Russian.
      - `en` string, required: Name in English.
    - `phone_number` string, nullable, required: **E.164 International Format.** Phone number with country code prefix (e.g., `+12025550123` for US, `+79991234567` for Russia). **Usage.** This is your Telegram account login. Use it with `verification.code` and `verification.password` to access the account.
    - `price` object, required: **Final Price After Discount.** The actual amount deducted from your balance, with your personal discount already applied. **To see pricing breakdown before purchase.** Check `GET /accounts/:country_code` which shows both discounted price and original `base_price`. **Discount eligibility.** Based on your total successful purchase count. Higher volume = bigger discounts.
      - `amount` string, required: Monetary amount as a string with up to 2 decimal places.
      - `currency_code` string, required: ISO 4217 currency code.
    - `status` 'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND' | 'EXPIRED', required: **Purchase Status Lifecycle.** `PENDING` (initial) → `SUCCESS` (after code request) or `ERROR` (provider failure). Any status can transition to `REFUND` via admin action. **Important.** Status is immutable once set to `SUCCESS`, `ERROR`, or `REFUND`. **Filter options** - `PENDING` - code not requested. - `SUCCESS` - code ready. - `ERROR` - provider failed. - `REFUND` - money returned.
    - `purchase_type` 'SINGLE' | 'BULK' | 'ADMIN', required: Type of purchase: SINGLE (regular), BULK (batch purchase), ADMIN (admin deduction)
    - `purchase_source` 'BOT' | 'WEB' | 'API', required: Purchase channel: BOT (Telegram), WEB (site JWT), API (x-api-key)
    - `verification` object, nullable, required: **Verification Credentials.** Login credentials for the purchased Telegram account. Initially `null` after purchase creation. **Availability.** Populated after calling `POST /purchases/:id/request-code`. Once received, credentials are permanent and cannot be re-requested. **Security.** Verification data is only visible to the purchase owner.
      - `code` string, required: Verification code for account.
      - `password` string, nullable, required: Account password.
      - `received_at` string, required: **Code Retrieval Timestamp.** Marks when verification code was successfully fetched from the provider (not when purchase was created). **Example timeline.** - `created_at`: `2024-11-19T10:00:00Z` (purchase created) - `received_at`: `2024-11-19T10:05:02Z` (code requested 5 minutes later) **Note.** These timestamps may be identical if code is requested immediately after purchase.
    - `created_at` string, required: Purchase creation time in ISO 8601 format (UTC).
  - `code_request` object, required
    - `status` 'not_requested' | 'pending' | 'success' | 'failed', required: Current status of the code request
    - `attempt` integer, required: Current attempt number
    - `max_attempts` integer, required: Maximum number of attempts
    - `next_attempt_at` string, nullable, required: ISO timestamp of next attempt (null if not scheduled)
    - `retry_after` integer, nullable, required: Seconds until next attempt (null if not scheduled)

## Other responses

- `400`: Invalid request
- `404`: Purchase not found
- `500`: Internal server error

## Changes

- **2026-11-03** `aa3ff24cbee2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getmytg/apis/get-my-tg-api/changes/v1/purchases-by-hash/:hash/request-code/post.md)

---

[API](https://skmtc.dev/getmytg/apis/get-my-tg-api.md) - [All operations](https://skmtc.dev/getmytg/apis/get-my-tg-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getmytg/apis/get-my-tg-api/revisions/aa3ff24cbee2?raw)