Bitcall logoBitcall API
OTP
Add your Key ID and Secret to send test requests.

Request a number

POST
/v1/otp/request
*object

Rents a number for a service and country, and starts waiting for its code. The rental is charged on success and the order begins in waiting. serviceId identifies the offer to rent and comes from the catalog — pools[].serviceId on GET /v1/otp/services/{serviceSlug}/{countryCode} is the usual source. It is opaque: send it back as published.

Authorization

KeyId ApiSecret
x-key-id<token>

Your API key id.

In: header

x-api-secret<token>

Your API key secret.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/otp/request" \  -H "Content-Type: application/json" \  -d '{    "serviceId": "CHARLIE-US-openai_/_chatgpt"  }'
{
  "data": {
    "orderId": "string",
    "status": "waiting",
    "actions": {
      "canResend": true,
      "canReactivate": true
    },
    "serviceId": "string",
    "service": "string",
    "countryCode": "string",
    "phoneNumber": "string",
    "price": {
      "amount": 0,
      "currency": "string"
    },
    "code": "string",
    "expiresAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "resend": {
      "cooldownSeconds": 0,
      "price": {
        "amount": 0,
        "currency": "string"
      }
    }
  }
}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request is not valid. See `fields` for what to correct.",
    "requestId": "9f1c7b2e-…"
  }
}
{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "This endpoint requires an API key.",
    "requestId": "9f1c7b2e-…"
  }
}
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your account balance is too low for this operation.",
    "requestId": "9f1c7b2e-…"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry after the interval in `Retry-After`.",
    "requestId": "9f1c7b2e-…"
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong on our side.",
    "requestId": "9f1c7b2e-…"
  }
}
{
  "error": {
    "code": "SERVICE_RESPONSE_INVALID",
    "message": "The upstream service returned an unexpected response.",
    "requestId": "9f1c7b2e-…"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The service is temporarily unavailable. Try again shortly.",
    "requestId": "9f1c7b2e-…"
  }
}

Overview

Previous Page

Check an order GET

Returns the current state of your orders, including the received code once it arrives. Poll this after requesting a number. Pass `orderId` to follow the one order you just placed; omit it to see them all. The answer is always a list — a filtered one carries a single entry, and an order that is not yours simply is not in it.