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

# Generate OTP

> Generate and send a one-time password (OTP) to a recipient via SMS

# Generate OTP

This endpoint allows you to generate and send a one-time password (OTP) to a recipient via SMS. The OTP can be used for verification purposes with customizable expiry time and retry limits.

**Endpoint:** `POST /v1/external/generate/otp`

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.kairosafrika.com/v1/external/generate/otp \
    --header 'x-api-key: YOUR_API_KEY' \
    --header 'x-api-secret: YOUR_API_SECRET' \
    --header 'x-api-version: 2025-08-01' \
    --header 'Content-Type: application/json' \
    --data '{
      "recipient": "0559400612",
      "from": "PHCCU",
      "message": "Your verification code is {code}, it expires in {amount} {duration}",
      "pinLength": 4,
      "pinType": "NUMERIC",
      "expiry": {
        "amount": 12,
        "duration": "minutes"
      },
      "maxAmountOfValidationRetries": 3
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.kairosafrika.com/v1/external/generate/otp', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-api-secret': 'YOUR_API_SECRET',
      'x-api-version': '2025-08-01',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      recipient: '0559400612',
      from: 'PHCCU',
      message: 'Your verification code is {code}, it expires in {amount} {duration}',
      pinLength: 4,
      pinType: 'NUMERIC',
      expiry: {
        amount: 12,
        duration: 'minutes'
      },
      maxAmountOfValidationRetries: 3
    })
  });

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

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

  response = requests.post(
      'https://api.kairosafrika.com/v1/external/generate/otp',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'x-api-secret': 'YOUR_API_SECRET',
          'x-api-version': '2025-08-01',
          'Content-Type': 'application/json'
      },
      json={
          'recipient': '0559400612',
          'from': 'PHCCU',
          'message': 'Your verification code is {code}, it expires in {amount} {duration}',
          'pinLength': 4,
          'pinType': 'NUMERIC',
          'expiry': {
              'amount': 12,
              'duration': 'minutes'
          },
          'maxAmountOfValidationRetries': 3
      }
  )

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

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.kairosafrika.com/v1/external/generate/otp',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(array(
      'recipient' => '0559400612',
      'from' => 'PHCCU',
      'message' => 'Your verification code is {code}, it expires in {amount} {duration}',
      'pinLength' => 4,
      'pinType' => 'NUMERIC',
      'expiry' => array(
        'amount' => 12,
        'duration' => 'minutes'
      ),
      'maxAmountOfValidationRetries' => 3
    )),
    CURLOPT_HTTPHEADER => array(
      'x-api-key: YOUR_API_KEY',
      'x-api-secret: YOUR_API_SECRET',
      'x-api-version: 2025-08-01',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);
  echo $response;
  ?>
  ```
</RequestExample>

## Request Body

* **recipient** (string, required): Recipient phone number (without + prefix).
* **from** (string, required): Sender ID or name.
* **message** (string, required): OTP message template with placeholders:
  * `{code}` - Will be replaced with the generated OTP code
  * `{amount}` - Will be replaced with expiry amount
  * `{duration}` - Will be replaced with expiry duration
* **pinLength** (integer, required): Length of the OTP code (4-10 digits).
* **pinType** (string, required): Type of OTP code (NUMERIC, ALPHANUMERIC, or ALPHABETIC).
* **expiry** (object, required): OTP expiry configuration.
  * **amount** (integer, required): Expiry time amount.
  * **duration** (string, required): Expiry time duration unit (seconds, minutes, or hours).
* **maxAmountOfValidationRetries** (integer, required): Maximum number of validation attempts allowed (minimum 1).

## Responses

* **200 OK**: OTP generated and sent successfully.
* **400 Bad Request**: Invalid input data.
* **401 Unauthorized**: Invalid or missing API key.

## Response Example

```json theme={null}
{
  "statusCode": "200",
  "statusMessage": "OTP successfully sent to your device",
  "transactionId": "ec1fb725-3e86-47dc-bf0c-82b7776080e8",
  "sequenceNo": "01K6NA4F7KJKSR6JM912JMY4NV",
  "data": {
    "uuid": "b6ec4e28-c496-4ea5-b6e6-6a31301f3a79",
    "code": "***********"
  },
  "timestamp": "2025-10-03T15:13:03.227Z"
}
```

## Response Fields

* **statusCode** (string): HTTP status code.
* **statusMessage** (string): Status message (e.g., "OTP successfully sent to your device").
* **transactionId** (string): Unique transaction identifier.
* **sequenceNo** (string): Sequence number for tracking.
* **data** (object): OTP generation result data.
  * **uuid** (string): Unique identifier for the OTP generation.
  * **code** (string): Masked OTP code for security.
* **timestamp** (string): ISO 8601 timestamp of the response.

## Usage Flow

1. **Generate OTP**: Call this endpoint to generate and send an OTP to the recipient.
2. **Validate OTP**: Use the [Validate OTP](/sms-api/endpoint/validate-otp) endpoint to verify the code entered by the user.
3. The OTP will expire after the specified time period.
4. Users have a limited number of validation attempts (as specified in `maxAmountOfValidationRetries`).


## OpenAPI

````yaml POST /v1/external/generate/otp
openapi: 3.0.3
info:
  title: Kairos Afrika SMS API
  description: >-
    Send SMS messages through the Kairos Afrika platform. Switch between staging
    and production environments using the server dropdown.
  version: 1.0.0
  contact:
    name: Kairos Afrika Support
    email: support@kairosafrika.com
servers:
  - url: https://api.kairosafrika.com
    description: Sms API Base URL
security:
  - apiKeyAuth: []
    apiSecretAuth: []
paths:
  /v1/external/generate/otp:
    post:
      tags:
        - OTP
      summary: Generate OTP
      description: Generate and send a one-time password (OTP) to a recipient via SMS
      operationId: generateOTP
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2025-08-01'
          description: API version header (required for full JSON response)
          example: '2025-08-01'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateOTPRequest'
      responses:
        '200':
          description: OTP generated and sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateOTPResponse'
        '400':
          description: Bad request - Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GenerateOTPRequest:
      type: object
      required:
        - recipient
        - from
        - message
        - pinLength
        - pinType
        - expiry
        - maxAmountOfValidationRetries
      properties:
        recipient:
          type: string
          description: Recipient phone number (without + prefix)
          example: '0559400612'
        from:
          type: string
          description: Sender ID or name
          example: PHCCU
        message:
          type: string
          description: >-
            OTP message template with {code}, {amount}, and {duration}
            placeholders
          example: Your verification code is {code}, it expires in {amount} {duration}
        pinLength:
          type: integer
          description: Length of the OTP code
          example: 4
          minimum: 4
          maximum: 10
        pinType:
          type: string
          description: Type of OTP code
          enum:
            - NUMERIC
            - ALPHANUMERIC
            - ALPHABETIC
          example: NUMERIC
        expiry:
          type: object
          required:
            - amount
            - duration
          properties:
            amount:
              type: integer
              description: Expiry time amount
              example: 12
            duration:
              type: string
              description: Expiry time duration unit
              enum:
                - seconds
                - minutes
                - hours
              example: minutes
        maxAmountOfValidationRetries:
          type: integer
          description: Maximum number of validation attempts allowed
          example: 3
          minimum: 1
    GenerateOTPResponse:
      type: object
      properties:
        statusCode:
          type: string
          description: HTTP status code
          example: '200'
        statusMessage:
          type: string
          description: Status message
          example: OTP successfully sent to your device
        transactionId:
          type: string
          description: Unique transaction identifier
          example: ec1fb725-3e86-47dc-bf0c-82b7776080e8
        sequenceNo:
          type: string
          description: Sequence number
          example: 01K6NA4F7KJKSR6JM912JMY4NV
        data:
          type: object
          properties:
            uuid:
              type: string
              description: Unique identifier for the OTP generation
              example: b6ec4e28-c496-4ea5-b6e6-6a31301f3a79
            code:
              type: string
              description: Masked OTP code
              example: '***********'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
          example: '2025-10-03T15:13:03.227Z'
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: INVALID_PHONE_NUMBER
        message:
          type: string
          description: Human-readable error message
          example: The provided phone number is not valid
        details:
          type: object
          description: Additional error details
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key for authentication
    apiSecretAuth:
      type: apiKey
      in: header
      name: x-api-secret
      description: API Secret for authentication

````