> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.nms.go.ug/llms.txt.
> For full documentation content, see https://apidocs.nms.go.ug/llms-full.txt.

# Getting Started

> Set up your environment and make your first API call to the NMS API.

# Getting Started

This guide walks you through setting up your environment and making your first API call.

## Prerequisites

* A valid NMS user account with assigned facility access
* A tool for making HTTP requests (e.g., `curl`, Postman, or any HTTP client)

## Step 1: Authenticate

All API requests (except health checks) require a valid JWT token. Obtain one by calling the login endpoint:

```bash title="Login Request"
curl -X POST https://testapi.nms.go.ug/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
```

**Response:**

```json
{
  "token": "eyJhbGciOiJIUzM4NCJ9...",
  "expiresIn": 3600
}
```

Save the `token` value — you'll include it in all subsequent requests.

## Step 2: Make an Authenticated Request

Include the token in the `Authorization` header to call any protected endpoint. For example, to search for a facility:

```bash title="Search Facilities"
curl -X GET "https://testapi.nms.go.ug/api/v1/master/facilities?keyword=bubulo" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Step 3: Explore the API

Here are useful starting points depending on your use case:

| Use Case               | Endpoint                                        | Method |
| ---------------------- | ----------------------------------------------- | ------ |
| Look up a facility     | `/api/v1/master/facilities?keyword=...`         | GET    |
| Search products        | `/api/v1/master/products?keyword=...`           | GET    |
| View order cycles      | `/api/v1/master/order-cycles?financialYear=...` | GET    |
| Create a program order | `/api/v1/orders/program`                        | POST   |
| Check deliveries       | `/api/v1/deliveries/facility/{facilityCode}`    | GET    |

## Collection Variables

These variables are used throughout the API and should be set based on your context:

| Variable          | Description                  | Example                    |
| ----------------- | ---------------------------- | -------------------------- |
| `facility_code`   | MoH/DHIS2 facility code      | `HF0124`                   |
| `financial_year`  | Financial year for filtering | `2023/2024`                |
| `cycle`           | Ordering cycle number        | `1`                        |
| `template_code`   | Program order identifier     | `HF0124-2023/24Cycle1-LAB` |
| `plan_identifier` | Procurement/EMHS plan ID     | *(from API response)*      |

<Note>
  Tokens expire after the duration specified in `expiresIn` (in seconds). If you receive a `401 Unauthorized` response, re-authenticate by calling the login endpoint again. See the [Authentication Guide](/docs/authentication) for more details.
</Note>