> For the complete documentation index, see [llms.txt](https://docs.toomuchmedia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toomuchmedia.com/api/api-overview.md).

# API Overview

Welcome to an Overview of the NATS REST API. The NATS API is available for all installations, giving you a programmatic way to manage, automate, and scale your business. 

{% hint style="info" %}
**Please note:** Certain API Endpoints require having additional features. External Hit and External Transaction, for example, require NATS Pro. While /biller/verify/ requires Payze. 
{% endhint %}

## Base URL Structure

All REST requests interact with the API layer via a predictable, structured routing template:

{% code overflow="wrap" %}

```
http://<domain>/api/<endpoint>/<action>
```

{% endcode %}

When building your requests, ensure you input the correct routing properties:

* **\<domain>:** Replace this with your specific, licensed NATS installation domain name
* **\<endpoint>:** Replace with the endpoint you are trying to access.
* **\<action>:** Replace with the specific action you are trying to perform.
  * Some endpoints do not require an action in the URL, and will be specified in the documentation.

## API Activation

Before your system can listen for outbound REST commands, you must have the **Enable REST API** configuration setting enabled.

* Navigate to the **Security** section of the **Configuration Admin**.
* Locate the Enable REST API setting underneath the APIs header.
* Ensure the checkbox is set to **Yes.**

For a detailed guide on everything required to use the API, see [API Usage Requirements](/api/api-usage-requirements.md).

## Accessing APIs

The NATS REST API enforces strict restrictions to protect your system from unauthorized system manipulations.

### User Authorization

* All API is accessible exclusively to NATS affiliates with Admin-level permissions.

### IP Whitelisting

To successfully communicate with the NATS REST API, your server's outbound IP address must be explicitly set in your system.&#x20;

* This is done by navigating to the Security section of the Configuration Admin.&#x20;
* Under the APIs header, modify the **Admin API Allowed IPs** setting to add or remove authorized IPs.

## Authentication & Headers

Authentication is handled universally using secure **HTTP Header Authentication.** Every individual outbound request must be supplied with your admin credentials via headers.

### Required HTTP Headers

{% hint style="info" %}
**Please note:** Header keys are completely case-insensitive.
{% endhint %}

Pass these exact keys inside your request headers array:

* api-key: Affiliate key
* api-username: Affiliate Username

{% code overflow="wrap" %}

```
api-key: your_affiliate_api_key
api-username: your_affiliate_username
```

{% endcode %}

### Retrieving Your API Key

{% hint style="info" %}
**Please note:** Only full admin accounts are authorized to use the API and set an API key.
{% endhint %}

* Navigate to the Affiliate Admin
* Select the relevant Affiliate
* Navigate to the API tab
* Grab the key from the API Key underneath the General API Details section.

If you do not have an API key, you can set one by clicking the icon labeled "Change API Key."

## Request Methods & Status Codes

All API payloads and system responses exchange data through raw **JSON** strings.

### Supported HTTP Methods

* GET
* POST
* DELETE
* PATCH
  * If PATCH requests are not honored, please add 'x-http-method: PATCH' in the headers array passed.

For detailed information about these HTTP Request methods, please refer to their official documentation here: <http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html>

### Response Status Codes

**200**

* On Success, the API will return a '**200'** status and output the results of the API call. Please refer to the available API endpoints for possible responses.
* NOTE: As long as the endpoint and HTTP request method are valid and there are no invalid parameters, a '**200'** response is returned.

**400**

* The API will return a '**400'** status if an invalid or unsupported HTTP request is sent.

**404**

* The API will return either a '**404'** status if an invalid parameter is sent, or if an HTTP request is sent to an invalid endpoint.

**405**

* The API will return a '**405'** status if an invalid HTTP request method is used.

## Code Examples

Authentication can be handled in various ways using different programming languages. Below are some complete example calls to the Ping endpoint with HTTP Header authentication.

### PHP

{% code overflow="wrap" %}

```
<?php 
$url = 'http://domain/api/service/ping';
$curl = curl_init(); 
 
$headers = array( 
    'api-key: 44b5498dbcb481a0d00b404c0169af62', 
    'api-username: tmm1phrvezsbu' 
); 
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); 
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($curl, CURLOPT_URL, $url); 
                                                                                                                                                               
$resp = curl_exec($curl); 
//dumps an associative array representation of the json 
var_dump(json_decode($resp, true)); 
// Close request to clear up some resources 
curl_close($curl); 
?> 
```

{% endcode %}

### Python

This example requires pip and the requests library, which can be installed via pip by:

{% code overflow="wrap" %}

```
pip install requests
```

{% endcode %}

{% code overflow="wrap" %}

```
import requests

url = 'http://domain/api/service/ping'
headers = {
	'api-key': '44b5498dbcb481a0d00b404c0169af62',
	'api-username': 'tmm1phrvezsbu'
}
 params =  { 
        'payvia_type_id': 1, 
        'rule_type': 'enabled' 
 }
	
res = requests.get(url, params=params, headers=headers)
print res.json()
```

{% endcode %}

### node.js

This example requires npm and the request module, which can be installed via npm by:

{% code overflow="wrap" %}

```
npm install request
```

{% endcode %}

{% code overflow="wrap" %}

```
var request = require('request');
                          
var options = {           
    url: 'http://domain/api/service/ping',
    method: 'GET',        
    json: true,           
    headers: {            
        'api-key': '44b5498dbcb481a0d00b404c0169af62',
        'api-username': 'tmm1phrvezsbu'
    }                     
};                        
                          
function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }                     
    else{                 
        console.log(body);                                                                                                                                     
    }                     
                          
}                         
                          
request(options, callback);
```

{% endcode %}

### cURL

{% code overflow="wrap" %}

```
curl -X GET 'http://domain/api/service/ping' -H "api-key: 44b5498dbcb481a0d00b404c0169af62" -H "api-username: tmm1phrvezsbu"
```

{% endcode %}

Expected output:

{% code overflow="wrap" %}

```
true
```

{% endcode %}

## Related Articles

{% content-ref url="/pages/KGNgHQm3Sb2l8MvZY2TU" %}
[API Usage Requirements](/api/api-usage-requirements.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toomuchmedia.com/api/api-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.