> ## 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.

# Get Account Holder

> Retrieve details of an account holder by their ID

# Get Account Holder

This endpoint allows you to retrieve details of an account holder by their unique identifier.

**Endpoint:** `GET /v1/accountholders/{accountHolderId}`

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.staging.kairosafrika.cloud/paygw/v1/accountholders/233559400612 \
    --header 'Authorization: Basic $(echo -n "username:password" | base64)'
  ```

  ```javascript JavaScript theme={null}
  const username = 'your_username';
  const password = 'your_password';
  const credentials = btoa(`${username}:${password}`);

  const response = await fetch('https://api.staging.kairosafrika.cloud/paygw/v1/accountholders/233559400612', {
    method: 'GET',
    headers: {
      'Authorization': `Basic ${credentials}`
    }
  });

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

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

  username = 'your_username'
  password = 'your_password'
  credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()

  response = requests.get(
      'https://api.staging.kairosafrika.cloud/paygw/v1/accountholders/233559400612',
      headers={
          'Authorization': f'Basic {credentials}'
      }
  )

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

  ```php PHP theme={null}
  <?php
  $username = 'your_username';
  $password = 'your_password';
  $credentials = base64_encode($username . ':' . $password);

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.staging.kairosafrika.cloud/paygw/v1/accountholders/233559400612',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
      'Authorization: Basic ' . $credentials
    ),
  ));

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

## Path Parameter

* **accountHolderId** (string, required): The unique identifier of the account holder to retrieve.
  * Example: `233559400612`

## Responses

### 200 OK - Success Response

Returns account holder details when found.

```json theme={null}
{
    "statusCode": "0000",
    "statusMessage": "Successful",
    "transactionId": "454545455",
    "sequenceNo": "030720241222005656869",
    "data": {
        "accountName": "John Doe",
        "msisdn": "2335548908839",
        "network": "MTN"
    },
    "links": []
}
```

### 404 Not Found - Account Holder Not Found

```json theme={null}
{
    "statusCode": "0404",
    "statusMessage": "Account holder not found",
    "transactionId": null,
    "sequenceNo": null,
    "data": null,
    "links": []
}
```

### 401 Unauthorized - Invalid Credentials

```json theme={null}
{
    "statusCode": "0401",
    "statusMessage": "Unauthorized",
    "transactionId": null,
    "sequenceNo": null,
    "data": null,
    "links": []
}
```

## Response Fields

* **statusCode** (string): Status code indicating the result of the request
  * `"0000"`: Successful
  * `"0404"`: Account holder not found
  * `"0401"`: Unauthorized
* **statusMessage** (string): Human-readable status message
* **transactionId** (string): Unique transaction identifier for tracking
* **sequenceNo** (string): Sequence number for the request
* **data** (object): Account holder information when successful
  * **accountName** (string): Account holder's full name
  * **msisdn** (string): Mobile subscriber identifier
  * **network** (string): Mobile network provider (e.g., MTN, Vodafone)
* **links** (array): HATEOAS links for related actions

## Usage Example

The examples above show how to authenticate and retrieve account holder information using different programming languages.


## OpenAPI

````yaml GET /v1/accountholders/{accountHolderId}
openapi: 3.0.3
info:
  title: Kairos Afrika Payment API
  description: >-
    Process payments and manage transactions 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: /
    description: API Base
security:
  - basicAuth: []
paths:
  /v1/accountholders/{accountHolderId}:
    get:
      tags:
        - Account Holders
      summary: Get Account Holder
      description: Retrieve details of an account holder by their ID
      operationId: getAccountHolder
      parameters:
        - name: accountHolderId
          in: path
          required: true
          description: The unique identifier of the account holder
          schema:
            type: string
          example: '233559400612'
      responses:
        '200':
          description: Account holder details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountHolderResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Account holder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AccountHolderResponse:
      type: object
      properties:
        statusCode:
          type: string
          description: Status code indicating the result of the request
          example: '0000'
        statusMessage:
          type: string
          description: Human-readable status message
          example: Successful
        transactionId:
          type: string
          description: Unique transaction identifier for tracking
          example: '454545455'
        sequenceNo:
          type: string
          description: Sequence number for the request
          example: '030720241222005656869'
        data:
          type: object
          nullable: true
          description: Account holder information when successful
          properties:
            accountName:
              type: string
              description: Account holder's full name
              example: Lord Acheampong
            msisdn:
              type: string
              description: Mobile subscriber identifier
              example: '233559400612'
            network:
              type: string
              description: Mobile network provider
              example: MTN
        links:
          type: array
          description: HATEOAS links for related actions
          items:
            type: object
            properties:
              rel:
                type: string
                description: Relationship type
              href:
                type: string
                description: Link URL
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: INSUFFICIENT_FUNDS
        message:
          type: string
          description: Human-readable error message
          example: The customer has insufficient funds for this transaction
        details:
          type: object
          description: Additional error details
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using base64 encoded username:password

````