### GET /device-phone-number API Operation

Source: https://developer.ooredoo.com/index.php/api/130

Returns the phone number associated with the access token. Use this to retrieve the device's phone number for your own verification processes.

```http
GET /device-phone-number
Returns the phone number associated with the access token
```

--------------------------------

### GET /device-phone-number

Source: https://developer.ooredoo.com/sites/default/files/apidoc_specs/NV_Swagger_Prod.yaml

Returns the phone number associated with the access token for the user authenticated via the mobile network. This allows API clients to verify the number themselves.

```APIDOC
## GET /device-phone-number

### Description
Returns the phone number so the API clients can verify the number themselves:
- It will be done for the user that has authenticated via mobile network
- It returns the authenticated user's `device phone number` associated to the access token

### Method
GET

### Endpoint
/device-phone-number

### Parameters
#### Header Parameters
- **x-correlator** (string) - Optional - Correlation id for the different services

### Response
#### Success Response (200)
- **x-correlator** (string) - Correlation id for the different services
- **NumberVerificationShareResponse** (object) - Schema containing the shared phone number.

#### Response Example
```json
{
  "device_phone_number": "+1234567890"
}
```

#### Error Responses
- **400**: Bad Request
- **401**: Unauthorized
- **403**: Phone Number Verification Permission Denied
```

--------------------------------

### Create an AdjustBalance

Source: https://developer.ooredoo.com/api/129

Creates an adjustment to a user's balance, supporting one-time debit operations.

```APIDOC
## Create an AdjustBalance

### Description
Creates a one-time debit adjustment to a user's balance.

### Method
POST

### Endpoint
/v1/adjustments

### Parameters
#### Request Body
- **AdjustBalance_CreateOne** (object) - Required - The details for the balance adjustment.
  - **PartyAccountRef** (object) - Required - Reference to the party's account.
    - **partyId** (string) - Required - The unique identifier for the party.
  - **ProductRef** (object) - Required - Reference to the product being purchased.
    - **productId** (string) - Required - The unique identifier for the product.
  - **UsageType** (string) - Required - The type of usage, e.g., 'DEBIT'.
  - **Quantity** (object) - Required - The quantity of the item being purchased.
    - **amount** (number) - Required - The monetary amount.
    - **currency** (string) - Required - The currency of the amount.
```

--------------------------------

### Create AdjustBalance

Source: https://developer.ooredoo.com/index.php/api/62

Creates an AdjustBalance entry, which can be used for debit or credit operations.

```APIDOC
## POST /adjustBalance

### Description
Creates an AdjustBalance entry to modify a subscriber's balance. This can be used for one-time or recurring debit operations, or for credit operations.

### Method
POST

### Endpoint
/adjustBalance

### Parameters
#### Request Body
- **AdjustBalance_Create** (object) - Required - The details for creating the balance adjustment.
  - **action** (string) - Required - The type of action to perform (e.g., 'debit', 'credit').
  - **reason** (string) - Optional - The reason for the balance adjustment.
  - **bucketRef** (object) - Required - Reference to the balance bucket to be adjusted.
    - **id** (string) - Required - The ID of the balance bucket.
    - **name** (string) - Optional - The name of the balance bucket.
    - **@referredType** (string) - Optional - The type of the referred resource.
  - **value** (object) - Required - The amount and unit of the balance adjustment.
    - **amount** (number) - Required - The monetary or non-monetary amount.
    - **unit** (string) - Required - The unit of the amount (e.g., 'USD', 'GB', 'SMS').
  - **partyAccount** (object) - Required - Reference to the subscriber's account.
    - **id** (string) - Required - The ID of the subscriber account.
    - **@referredType** (string) - Optional - The type of the referred resource.

### Request Example
```json
{
  "AdjustBalance_Create": {
    "action": "debit",
    "reason": "Service usage charge",
    "bucketRef": {
      "id": "data_bucket_123",
      "name": "Data Allowance"
    },
    "value": {
      "amount": 100,
      "unit": "MB"
    },
    "partyAccount": {
      "id": "sub_acc_456"
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the AdjustBalance entry.
- **href** (string) - The URL to retrieve the AdjustBalance entry.
- **action** (string) - The type of action performed.
- **state** (string) - The state of the adjustment (e.g., 'completed', 'pending').
- **creationDate** (string) - The date and time the adjustment was created.

#### Response Example
```json
{
  "id": "adj_789",
  "href": "https://api.ooredoo.com/v1/adjustBalance/adj_789",
  "action": "debit",
  "state": "completed",
  "creationDate": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Generate Access Token

Source: https://developer.ooredoo.com/index.php/api/119

Generates an access token required for authenticating with the SIM Swap API.

```APIDOC
## Generate Access Token

### Description
Generates an access token for API authentication.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Typically 'client_credentials' for client-side authentication.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.
```

--------------------------------

### Generate Access Token

Source: https://developer.ooredoo.com/index.php/api/120

This endpoint is used to generate an access token for authenticating with the Camara OTP API.

```APIDOC
## Generate Access Token

### Description
Generates an access token required for authenticating subsequent API requests.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Typically set to "client_credentials" for client-based authentication.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.

### Request Example
```json
{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The generated access token.
- **token_type** (string) - The type of token, usually "Bearer".
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### Create AdjustBalance

Source: https://developer.ooredoo.com/api/62

Creates an AdjustBalance entry to modify a subscriber's balance.

```APIDOC
## POST /adjustBalance

### Description
Creates an AdjustBalance entry to modify a subscriber's balance.

### Method
POST

### Endpoint
/adjustBalance

### Parameters
#### Request Body
- **AdjustBalance_Create** (object) - Required - The details for the balance adjustment.
  - **action** (string) - Required - The type of action to perform (e.g., "debit", "credit").
  - **bucket** (BucketRef) - Required - Reference to the balance bucket to adjust.
  - **value** (Quantity) - Required - The quantity and unit of the balance adjustment.
  - **reason** (string) - Optional - The reason for the balance adjustment.
  - **correlationId** (string) - Optional - A unique identifier for the request.
  - **callbackUrl** (string) - Optional - URL for asynchronous callback.

### Request Example
{
  "example": {
    "action": "debit",
    "bucket": {
      "id": "data_bucket_1",
      "type": "data"
    },
    "value": {
      "amount": 100,
      "unit": "MB"
    },
    "reason": "Data top-up",
    "correlationId": "abc-123-xyz"
  }
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the AdjustBalance entry.
- **action** (string) - The type of action performed.
- **bucket** (BucketRef) - Reference to the balance bucket adjusted.
- **value** (Quantity) - The quantity and unit of the balance adjustment.
- **state** (string) - The state of the adjustment (e.g., "pending", "completed", "failed").
- **correlationId** (string) - The correlation ID of the request.

#### Response Example
{
  "example": {
    "id": "adj-987-zyx",
    "action": "debit",
    "bucket": {
      "id": "data_bucket_1",
      "type": "data"
    },
    "value": {
      "amount": 100,
      "unit": "MB"
    },
    "state": "completed",
    "correlationId": "abc-123-xyz"
  }
}
```

--------------------------------

### Create an AdjustBalance Recurring

Source: https://developer.ooredoo.com/api/99

Creates a recurring balance adjustment for a user's account.

```APIDOC
## POST /v1/adjustments/recurring

### Description
Creates a recurring balance adjustment, allowing for scheduled debits from a user's mobile bill or prepaid SIM.

### Method
POST

### Endpoint
/v1/adjustments/recurring

### Parameters
#### Request Body
- **adjustBalance_CreateRecurring** (object) - Required - The details for the recurring balance adjustment.
  - **partyAccountRef** (object) - Required - Reference to the party's account.
    - **accountIdentifier** (string) - Required - The identifier of the account.
  - **productRef** (object) - Required - Reference to the product for the adjustment.
    - **productIdentifier** (string) - Required - The identifier of the product.
  - **usageType** (string) - Required - The type of usage for the adjustment (e.g., "data", "voice").
  - **bucketRef** (object) - Required - Reference to the balance bucket.
    - **bucketIdentifier** (string) - Required - The identifier of the bucket.
  - **quantity** (object) - Required - The quantity of the adjustment.
    - **amount** (number) - Required - The monetary amount for the adjustment.
    - **currency** (string) - Required - The currency of the amount.
  - **recurrence** (object) - Required - Details of the recurrence.
    - **startTime** (string) - Required - The start time of the recurrence (ISO 8601 format).
    - **endTime** (string) - Optional - The end time of the recurrence (ISO 8601 format).
    - **frequency** (string) - Required - The frequency of the recurrence (e.g., "DAILY", "WEEKLY", "MONTHLY").

### Request Example
{
  "adjustBalance_CreateRecurring": {
    "partyAccountRef": {
      "accountIdentifier": "MSISDN:123456789"
    },
    "productRef": {
      "productIdentifier": "PROD-123"
    },
    "usageType": "data",
    "bucketRef": {
      "bucketIdentifier": "DATA_GB"
    },
    "quantity": {
      "amount": 5.00,
      "currency": "DZD"
    },
    "recurrence": {
      "startTime": "2023-10-27T10:00:00Z",
      "frequency": "MONTHLY"
    }
  }
}

### Response
#### Success Response (200)
- **actionStatus** (object) - The status of the action.
  - **actionStatusType** (string) - The type of action status (e.g., "SUCCESS", "PENDING").
  - **description** (string) - A description of the action status.

#### Response Example
{
  "actionStatus": {
    "actionStatusType": "SUCCESS",
    "description": "Recurring balance adjustment created successfully."
  }
}
```

--------------------------------

### Generic API Error Responses

Source: https://developer.ooredoo.com/sites/default/files/apidoc_specs/NV_Swagger_Prod.yaml

This section details common error responses that can be encountered when interacting with the Ooredoo Developer API. It includes explanations for permission denied, authentication issues, and server-side errors.

```APIDOC
## API Error Responses

### Description
This section outlines various error responses that the API may return, providing details on their meaning and potential causes.

### Error Codes and Messages

- **GENERIC_403_PERMISSION_DENIED**
  - **Code**: `PERMISSION_DENIED`
  - **Message**: `Client does not have sufficient permissions to perform this action.`
  - **Description**: Returned when the OAuth2 token lacks the required scope or the user fails operational security checks.

- **GENERIC_403_USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
  - **Code**: `NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK`
  - **Message**: `Client must authenticate via the mobile network to use this service`
  - **Description**: Indicates that client authentication was not performed via the mobile network. The AMR parameter in the access token can be checked to verify the authentication method.

- **GENERIC_403_INVALID_TOKEN_CONTEXT**
  - **Code**: `INVALID_TOKEN_CONTEXT`
  - **Message**: `Phone number cannot be deducted from access token context`
  - **Description**: Occurs when the phone number cannot be determined from the access token's context.

- **Generic500**
  - **Code**: `INTERNAL`
  - **Message**: `Server error`
  - **Description**: Represents a general server error. If this occurs repeatedly, it may indicate an issue with the server.

- **Generic503**
  - **Code**: `UNAVAILABLE`
  - **Message**: `Service unavailable`
  - **Description**: Indicates that the service is temporarily unavailable, typically due to the server being down.

- **Generic504**
  - **Code**: `TIMEOUT`
  - **Message**: `Request timeout exceeded. Try later.`
  - **Description**: Returned when the request time exceeded. If this happens repeatedly, consider reducing the request complexity.

### Headers
All error responses include the `x-correlator` header.

### Content Type
Error responses are typically in `application/json` format, with a schema defined by `#/components/schemas/ErrorInfo`.
```

--------------------------------

### Generate Access Token

Source: https://developer.ooredoo.com/api/118

Generates an access token for authenticating with the Communication Management API.

```APIDOC
## POST /access-token

### Description
Creates an access token for API authentication.

### Method
POST

### Endpoint
/access-token

### Parameters
#### Request Body
- **grant_type** (string) - Required - The grant type for the token request (e.g., 'client_credentials').
- **client_id** (string) - Required - The client ID for authentication.
- **client_secret** (string) - Required - The client secret for authentication.

### Request Example
{
  "example": "{\"grant_type\": \"client_credentials\", \"client_id\": \"YOUR_CLIENT_ID\", \"client_secret\": \"YOUR_CLIENT_SECRET\"}"
}

### Response
#### Success Response (200)
- **access_token** (string) - The generated access token.
- **token_type** (string) - The type of token (e.g., 'Bearer').
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
{
  "example": "{\"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\", \"token_type\": \"Bearer\", \"expires_in\": 3600}"
}
```

--------------------------------

### POST /verify

Source: https://developer.ooredoo.com/sites/default/files/apidoc_specs/NV_Swagger_Prod.yaml

Verifies if the provided hashed or plain text phone number matches the phone number associated with the access token. This operation is performed for the user authenticated via the mobile network and returns a boolean indicating the match.

```APIDOC
## POST /verify

### Description
Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided.
- The number verification will be done for the user that has authenticated via mobile network
- It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token

### Method
POST

### Endpoint
/verify

### Parameters
#### Header Parameters
- **x-correlator** (string) - Optional - Correlation id for the different services

#### Request Body
- **NumberVerificationRequestBody** (object) - Required - Schema defining the phone number to verify (either plain or hashed).

### Request Example
```json
{
  "plain_phone_number": "+1234567890",
  "hashed_phone_number": "some_hashed_value"
}
```

### Response
#### Success Response (200)
- **x-correlator** (string) - Correlation id for the different services
- **NumberVerificationMatchResponse** (object) - Schema indicating if the phone number matched.

#### Response Example
```json
{
  "match": true
}
```

#### Error Responses
- **400**: Bad Request
- **401**: Unauthorized
- **403**: Phone Number Verification Permission Denied
- **500**: Internal Server Error
- **503**: Service Unavailable
- **504**: Gateway Timeout
```

--------------------------------

### Retrieve AdjustBalance by ID (CREDIT)

Source: https://developer.ooredoo.com/api/62

Retrieves a specific AdjustBalance entry by its ID, for credit operations.

```APIDOC
## GET /adjustBalance/{id}

### Description
Retrieves a specific AdjustBalance entry by its ID, for credit operations.

### Method
GET

### Endpoint
/adjustBalance/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the AdjustBalance entry.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the AdjustBalance entry.
- **action** (string) - The type of action performed.
- **bucket** (BucketRef) - Reference to the balance bucket adjusted.
- **value** (Quantity) - The quantity and unit of the balance adjustment.
- **state** (string) - The state of the adjustment (e.g., "pending", "completed", "failed").
- **correlationId** (string) - The correlation ID of the request.

#### Response Example
{
  "example": {
    "id": "adj-123-abc",
    "action": "credit",
    "bucket": {
      "id": "voice_bucket_1",
      "type": "voice"
    },
    "value": {
      "amount": 50,
      "unit": "minutes"
    },
    "state": "completed",
    "correlationId": "def-456-uvw"
  }
}
```

--------------------------------

### POST /verify API Operation

Source: https://developer.ooredoo.com/index.php/api/130

Verifies if the received hashed or plain text phone number matches the phone number associated with the access token. Use this to confirm number ownership.

```http
POST /verify
Verifies if the received hashed/plain text phone number matches the phone number associated with the access token
```

--------------------------------

### Generate Access Token

Source: https://developer.ooredoo.com/api/119

Generates an access token required for authenticating API requests.

```APIDOC
## Generate Access Token

### Description
Generates an access token required for authenticating API requests.

### Method
POST

### Endpoint
/v1/auth/token
```

--------------------------------

### Generate Access Token

Source: https://developer.ooredoo.com/api/129

Generates an access token required for authenticating API requests.

```APIDOC
## Generate Access Token

### Description
Generates an access token for authenticating API requests.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Request Body
- **grant_type** (string) - Required - The grant type for the request, typically 'client_credentials'.
- **client_id** (string) - Required - The client ID for authentication.
- **client_secret** (string) - Required - The client secret for authentication.
```

--------------------------------

### Create Communication Message

Source: https://developer.ooredoo.com/api/118

Creates a new communication message.

```APIDOC
## POST /communication-messages

### Description
Creates a new communication message, such as an SMS or email.

### Method
POST

### Endpoint
/communication-messages

### Parameters
#### Request Body
- **sender** (object) - Required - Information about the sender.
  - **type** (string) - Required - The type of sender (e.g., 'application', 'user').
  - **id** (string) - Required - The ID of the sender.
- **receivers** (array) - Required - A list of receivers for the message.
  - **type** (string) - Required - The type of receiver (e.g., 'user', 'group').
  - **id** (string) - Required - The ID of the receiver.
- **messageType** (string) - Required - The type of message (e.g., 'SMS', 'EMAIL').
- **text** (string) - Required - The content of the message.
- **attachments** (array) - Optional - A list of attachments for the message.
  - **fileName** (string) - Required - The name of the attachment file.
  - **fileUrl** (string) - Required - The URL of the attachment.
  - **fileType** (string) - Required - The MIME type of the attachment.

### Request Example
{
  "example": "{\"sender\": {\"type\": \"application\", \"id\": \"app123\"}, \"receivers\": [{\"type\": \"user\", \"id\": \"user456\"}], \"messageType\": \"SMS\", \"text\": \"Hello, this is a test message!\", \"attachments\": [{\"fileName\": \"report.pdf\", \"fileUrl\": \"http://example.com/report.pdf\", \"fileType\": \"application/pdf\"}]}"
}

### Response
#### Success Response (201)
- **messageId** (string) - The unique identifier for the created message.
- **status** (string) - The status of the message creation (e.g., 'SENT', 'PENDING').

#### Response Example
{
  "example": "{\"messageId\": \"msg789\", \"status\": \"SENT\"}"
}
```

--------------------------------

### Create CommunicationMessage

Source: https://developer.ooredoo.com/index.php/api/118

Creates a new communication message, such as an SMS or email.

```APIDOC
## POST /communicationMessages

### Description
Creates a new communication message.

### Method
POST

### Endpoint
/communicationMessages

### Parameters
#### Request Body
- **sender** (Sender) - Required - Information about the sender.
- **receivers** (Array<Receiver>) - Required - An array of receivers for the message.
- **message** (CommunicationMessage_Create) - Required - The content and details of the message.
- **attachments** (Array<Attachment>) - Optional - An array of attachments for the message.

### Request Example
```json
{
  "sender": {
    "type": "EMAIL",
    "address": "sender@example.com"
  },
  "receivers": [
    {
      "type": "EMAIL",
      "address": "recipient1@example.com"
    },
    {
      "type": "SMS",
      "address": "+1234567890"
    }
  ],
  "message": {
    "subject": "Test Message",
    "body": "This is the content of the test message.",
    "contentType": "text/plain",
    "communicationStateType": "PENDING"
  },
  "attachments": [
    {
      "fileName": "document.pdf",
      "contentType": "application/pdf",
      "content": "base64_encoded_content"
    }
  ]
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created communication message.
- **status** (string) - The status of the message creation.

#### Response Example
```json
{
  "id": "msg_12345abcde",
  "status": "CREATED"
}
```
```

--------------------------------

### Retrieve AdjustBalance by ID (DEBIT)

Source: https://developer.ooredoo.com/api/62

Retrieves a specific AdjustBalance entry by its ID, for debit operations.

```APIDOC
## GET /adjustBalance/{id}

### Description
Retrieves a specific AdjustBalance entry by its ID, for debit operations.

### Method
GET

### Endpoint
/adjustBalance/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the AdjustBalance entry.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the AdjustBalance entry.
- **action** (string) - The type of action performed.
- **bucket** (BucketRef) - Reference to the balance bucket adjusted.
- **value** (Quantity) - The quantity and unit of the balance adjustment.
- **state** (string) - The state of the adjustment (e.g., "pending", "completed", "failed").
- **correlationId** (string) - The correlation ID of the request.

#### Response Example
{
  "example": {
    "id": "adj-987-zyx",
    "action": "debit",
    "bucket": {
      "id": "data_bucket_1",
      "type": "data"
    },
    "value": {
      "amount": 100,
      "unit": "MB"
    },
    "state": "completed",
    "correlationId": "abc-123-xyz"
  }
}
```

--------------------------------

### POST /number/verification

Source: https://developer.ooredoo.com/sites/default/files/apidoc_specs/NV_Swagger_Prod.yaml

Verifies a phone number against the user's device. It can be used to check if a provided phone number matches the one registered on the device, or to share the device's phone number with the application.

```APIDOC
## POST /number/verification

### Description
Verifies a phone number against the user's device. This endpoint can be used to check if a provided phone number matches the one registered on the device, or to share the device's phone number with the application.

### Method
POST

### Endpoint
/number/verification

### Parameters
#### Request Body
- **phoneNumber** (string) - Required - A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
- **hashedPhoneNumber** (string) - Optional - Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in E.164 format (starting with country code). Prefixed with '+'.

### Request Example
```json
{
  "phoneNumber": "+97433106287"
}
```

### Response
#### Success Response (200)
- **devicePhoneNumberVerified** (boolean) - True, if the phone number matches the device's registered number.

#### Response Example
```json
{
  "devicePhoneNumberVerified": true
}
```

#### Error Responses
- **400** - Problem with the client request. (INVALID_ARGUMENT)
- **401** - Unauthorized. (UNAUTHENTICATED or AUTHENTICATION_REQUIRED)
- **403** - Client does not have sufficient permission. (PERMISSION_DENIED)
- **500** - Internal Server Error.
- **503** - Service Unavailable.
- **504** - Gateway Timeout.
```