# Programmable Wireless

***

The Programmable Wireless REST API enables you to programmatically manage global fleets of cellularly connected IoT devices.

Using this REST API, you can:

* Exchange [machine-to-machine (M2M) messages with SMS-capable devices](https://docs.korewireless.com/en-us/programmable-wireless/get-started/get-started-with-programmable-wireless-machine-to-machine-sms-commands) .
* Obtain real-time insights to your SIM's connectivity with [SIM Data Sessions](https://docs.korewireless.com/en-us/api/products/programmable-wireless/datasession-resource) .
* Manage SIM capabilities and data metering with [RatePlan resources](https://docs.korewireless.com/en-us/api/products/programmable-wireless/rateplan-resource) .
* Manage [SIM resources](https://docs.korewireless.com/en-us/api/products/programmable-wireless/wireless-sim-resource) .
* Obtain [SIM Usage Records](https://docs.korewireless.com/en-us/api/products/programmable-wireless/sim-usagerecord-resource) .
* Obtain [Account Usage Records](https://docs.korewireless.com/en-us/api/products/programmable-wireless/account-usagerecord-resource) .

***

## The Programmable Wireless API base URL <a href="#the-programmable-wireless-api-base-url" id="the-programmable-wireless-api-base-url"></a>

All URLs in the reference documentation use the following base URL:

```bash
https://programmable-wireless.api.korewireless.com/v1
```

The Programmable Wireless REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. All responses are provided in JSON format.

{% hint style="info" %}
You don't need to use the `.json` file extension in API request URIs.
{% endhint %}

***

## API resources <a href="#api-resources" id="api-resources"></a>

The following lists the resources exposed by the Wireless REST API.

{% hint style="info" %}
To avoid ambiguity, **Sim** (initial cap) refers to the Sim API resource. **SIM** (all caps) refers to the physical Subscriber Identity Module (that is, a SIM card) associated with a Sim resource.
{% endhint %}

| **Resource**                                                                                                                | **Description**                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Account Usage Record](https://docs.korewireless.com/en-us/api/products/programmable-wireless/account-usagerecord-resource) | This resource is used to query the combined usage for all of the SIMs in your account. You can query multiple dimensions by providing query filters. |
| [Command](https://docs.korewireless.com/en-us/api/products/programmable-wireless/command-resource)                          | This resource represents an M2M SMS message.                                                                                                         |
| [SIM Data Sessions](https://docs.korewireless.com/en-us/api/products/programmable-wireless/datasession-resource)            | This resources returns data session information for a SIM over a period of 30 days or under, presented as an aggregated list.                        |
| [RatePlan](https://docs.korewireless.com/en-us/api/products/programmable-wireless/rateplan-resource)                        | This resource describes the capabilities and restrictions that will apply to any SIMs that are associated with the specified Rate Plan.              |
| [Sim](https://docs.korewireless.com/en-us/api/products/programmable-wireless/wireless-sim-resource)                         | A Sim resource (note the case) represents a physical SIM card that is capable of connecting to a wireless network.                                   |
| [Sim Usage Record](https://docs.korewireless.com/en-us/api/products/programmable-wireless/sim-usagerecord-resource)         | This resource is used to query the usage of a SIM. You can query multiple dimensions by providing query filters.                                     |

***

## API resource properties <a href="#api-resource-properties" id="api-resource-properties"></a>

When you create or update resources, you indicate the data that is being added or changed by specifying the appropriate resource property. All resource properties are case-sensitive and written in [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case). For example, if you want to change a new Sim's status from `ready` to `active` and receive an asynchronous notification of the change, you call:

```bash
curl https://programmable-wireless.api.korewireless.com/v1/Sims/{Sim SID} \
  -d 'Status=active' \
  -d 'CallbackUrl=<YOUR_WEBHOOK_URL>' \
  -d 'CallbacMethod=<YOUR_WEBHOOK_METHOD>' \
  --header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'
```

This contrasts with responses from the API, in which properties are referenced using [lower\_snake\_case](https://en.wikipedia.org/wiki/Snake_case). For example, getting that same Sim's details will return:

{% code overflow="wrap" %}

```json
{
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "unique_name": "unique_name",
  "commands_callback_method": "POST",
  "commands_callback_url": "<YOUR_WEBHOOK_URL>",
  "date_created": "2021-04-01T20:00:00Z",
  "date_updated": "2021-04-01T20:00:00Z",
  "friendly_name": "friendly_name",
  "links": {
    "data_sessions": "https://programmable-wireless.api.korewireless.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/DataSessions",
    "rate_plan": "https://programmable-wireless.api.korewireless.com/v1/RatePlans/WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "usage_records": "https://programmable-wireless.api.korewireless.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/UsageRecords"
  },
  "rate_plan_sid": "WPXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "sid": "DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "iccid": "iccid",
  "e_id": "e_id",
  "status": "active",
  "reset_status": null,
  "url": "https://programmable-wireless.api.korewireless.com/v1/Sims/DEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "ip_address": "192.168.1.1"
}
```

{% endcode %}

The API documentation presents the appropriate parameter formatting for the language or tool that you select in the code column.

{% hint style="info" %}
If you use one of KORE's Helper Libraries or [SDKs](https://gitlab.com/korewireless/public/kore_examples/-/tree/develop?ref_type=heads), properties' cases may differ from those outlined above for the base API. The API documentation always shows the correct case for a given library
{% endhint %}

***

## API authentication <a href="#api-authentication" id="api-authentication"></a>

HTTP requests made to the REST API are protected with [HTTP Bearer authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). To learn more about how KORE handles authentication, please see our [security documentation](https://docs.korewireless.com/en-us/v/developers/api-management/auth). You use your KORE **Auth Token** as the token for HTTP Bearer authentication.

```bash
curl -G https://programmable-wireless.api.korewireless.com/v1/Sims \
 --header 'Authorization: Bearer <YOUR_AUTH_TOKEN>'
```

You can find your Auth Token in the [Console](https://build.korewireless.com).

{% hint style="info" %}
To learn more about authentication and interaction with the KORE REST API, see our documentation for [**requests to the API**](https://docs.korewireless.com/en-us/v/developers/get-started/apis) and [**KORE's response**](https://docs.korewireless.com/en-us/v/developers/api-management/api-responses) .
{% endhint %}

***

## API errors <a href="#api-errors" id="api-errors"></a>

Errors are signaled by 4xx and 5xx HTTP response status codes and a JSON response body. The error data is a standard KORE structure. For example:

```json
{
  "code": 20003, 
  "detail": "Your AuthToken was incorrect.", 
  "message": "Authentication Error - No credentials provided", 
  "more_info": "https://docs.korewireless.com/errors/20003", 
  "status": 401
}
```

As you can see, the JSON gives you a human- and machine-readable indication of the nature (the `detail` key) and cause (`message`) of the error, and a reference to a more detailed description of the error in [KORE's documentation](https://docs.korewireless.com/en-us/v/developers/api-management/api-responses). The value of code is a KORE error code, and is referenced again in the `more_info` URL.

Many errors are generic to platform — the one shown above, for example. However, Programmable Wireless-specific error codes are in the range `33000-33999`.

You can see a list of all such codes in the [error code documentation](https://docs.korewireless.com/en-us/v/developers/api-management/api-responses) and as a [JSON file](https://docs.korewireless.com/en-us/v/developers/api-management/api-responses).

***

## Asynchronous resources <a href="#asynchronous-resources" id="asynchronous-resources"></a>

Certain operations in the Programmable Wireless REST API, such as changing the status of a Sim resource, can take some time to complete: anywhere from a few seconds to a minute or more. These operations will return an intermediate synchronous HTTP response — `202 Accepted`— while the action completes in the background.

Requests that will be processed asynchronously allow you to specify a callback URL for KORE to notify when the request has completed. A callback is sent to your server as either an HTTP `POST` or `GET` request, depending on your preference. Form parameters or query string parameters sent with the callback request describe the asynchronous outcome. Callback request formats are documented with each of the relevant REST API resources.

If your initial request completes synchronously, a `200 OK`, `201 Created`, or `204 No Content` response will be returned and you should not expect an asynchronous callback, even if a callback URL was specified.

An event will be posted to your account's Debugger in the Console with error details if KORE does not receive a success response from your callback URL.