---
# System prepended metadata

title: SMS Billing Microservice API Documentation

---

SMS Billing Microservice API Documentation
===

# Table of Contents
[TOC]

# How To Run

# APIs

## Retrieve Previous Month Invoice
Retrieve the previous month invoice for an organization

Path: `/organizations/{organization_id}/invoices/latest`  
Method: `GET`  
Success status code: `200`

**Path parameters:**
| Parameter Name  | Data Type | Required | Description     |
| --------------- | --------- | -------- | --------------- |
| organization_id | String    | Yes      | Organization ID |

**Response parameters:**
| Parameter Name | Data Type | Description |
| -------------- | --------- | ----------- |
| Reference      | String    | Additional reference number
| Payments       | List      | Payments for invoice
| CreditNotes    | List      | Credit notes
| Prepayments    | List      | Prepayments
| Overpayments   | List      | Overpayments
| AmountDue      | Number    | Amount remaining to be paid on invoice
| AmountPaid     | Number    | Sum of payments received for invoice
| AmountCredited | Number    | Sum of all credit notes, over-payments and pre-payments applied to invoice
| CurrencyRate   | Number    | Currency rate for a multicurrency invoice

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
N/A

**Sample response:**
```json=
{
    "Reference": "Feb 2020",
    "Payments": [],
    "CreditNotes": [],
    "Prepayments": [],
    "Overpayments": [],
    "AmountDue": 50.0,
    "AmountPaid": 0.0,
    "AmountCredited": 0.0,
    "CurrencyRate": 1.0
}
```

## Retrieve List of Invoices
Retrieve list of invoices of an organization

Path: `/organizations/{organization_id}/invoices`  
Method: `GET`  
Success status code: `200`

**Path parameters:**
| Parameter Name  | Data Type | Required | Description     |
| --------------- | --------- | -------- | --------------- |
| organization_id | String    | Yes      | Organization ID |

**Query parameters:**
| Parameter Name | Data Type | Required | Description               |
| -------------- | --------- | -------- | ------------------------- |
| limit          | String    | No       | Number. Limit list length |

**Response parameters:**
| Parameter Name | Data Type | Description                         |
| -------------- | --------- | ----------------------------------- |
| invoice_number | String    | The invoice number                  |
| invoice_id     | String    | The invoice Id                      |
| created_date   | String    | Date of creation                    |
| status         | String    | Current bill status                 |
| reference      | String    | Reference month and year of invoice |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```
N/A
```

**Sample response:**
```json=
[
    {
        "invoice_number": "INV-0236",
        "invoice_id": "0cfd35f8-d861-4f12-8875-91a01ed98362",
        "created_date": "2020-03-01 00:00:00",
        "status": "PAID",
        "reference": "Feb 2020"
    },
    {
        "invoice_number": "INV-0245",
        "invoice_id": "4dd6553a-4122-4ba3-9ff6-d508cf1df409",
        "created_date": "2020-04-01 00:00:00",
        "status": "PAID",
        "reference": "Mar 2020"
    }
]
```

## Get Recent Invoice List
Get list of recent invoices from any organization

Path: `/organizations/invoices`  
Method: `GET`  
Success status code: `200`

**Query parameters:**

| Parameter Name | Data Type | Required | Description                             |
| -------------- | --------- | -------- | --------------------------------------- |
| limit          | String    | No       | Count of latest invoices to be returned |

**Response parameters:**
List of dictionaries containing details: `invoice_number, invoice_id, created_date, status, reference, organization_id`

| Parameter Name  | Data Type | Description                                            |
| --------------- | --------- | ------------------------------------------------------ |
| invoice_number  | String    | Non-unique alpha numeric code identifying invoice      |
| invoice_id      | String    | Xero generated unique identifier for invoice           |
| created_date    | String    | Creation date of invoice                               |
| status          | String    | Approval status of the invoice (i.e. AUTHORISED, etc.) |
| reference       | String    | Reference month and year of invoice                    |
| organization_id | String    | Unique identification of an organization               |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```
N/A
```

**Sample response:**
```json=
[
    {
        "invoice_number": "INV-0591",
        "invoice_id": "31b8fd50-c113-42f3-bf54-0fe69a17c3f9",
        "created_date": "2020-08-01 00:00:00",
        "status": "AUTHORISED",
        "reference": "Jul 2020",
        "organization_id": "1187a768-f1d8-402e-89bf-b6ea4ddae55c"
    },
    {
        "invoice_number": "INV-0288",
        "invoice_id": "dad05f92-6868-4dc8-8a90-f113ab23661f",
        "created_date": "2020-04-20 00:00:00",
        "status": "AUTHORISED",
        "reference": "Mar 2020",
        "organization_id": "8c95a964-4e69-4f59-ac92-aca46f77fbea"
    }
]
```

## Get Invoice URL
Retrieve link to an invoice

Path: `/organizations/{organization_id}/invoices/{invoice_id}/url`  
Method: `GET`  
Success status code: `200`

**Path parameters:**
| Parameter Name  | Data Type | Required | Description     |
| --------------- | --------- | -------- | --------------- |
| organization_id | String    | Yes      | Organization ID |
| invoice_id      | String    | Yes      | The invoice Id  |

**Response parameters:**
| Parameter Name | Data Type | Description      |
| -------------- | --------- | ---------------- |
| invoice_url    | String    | The invoice link |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```
N/A
```

**Sample response:**
```json=
{
    "invoice_url": "https://in.xero.com/4vQoHfqhVLKoOzfY3hezDxzCGKtyXQpgCeItFQx6"
}
```

## Get Outstanding Balance
Retrieve outstanding balance of an organization

Path: `/organizations/{organization_id}/outstanding-balance`  
Method: `GET`  
Success status code: `200`

**Path parameters:**
| Parameter Name  | Data Type | Required | Description     |
| --------------- | --------- | -------- | --------------- |
| organization_id | String    | Yes      | Organization ID |

**Response parameters:**
| Parameter Name      | Data Type | Description         |
| ------------------- | --------- | ------------------- |
| outstanding_balance | Number    | Outstanding balance |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```
N/A
```

**Sample response:**
```json=
{
    "outstanding_balance": 50.0
}
```

## Get Unbilled Total
Get unbilled total for the current month

Path: `/organizations/{organization_id}/invoices/unbilled-total`  
Method: `GET`  
Success status code: `200`

**Path parameters:**
| Parameter Name  | Data Type | Required | Description     |
| --------------- | --------- | -------- | --------------- |
| organization_id | String    | Yes      | Organization ID |

**Response parameters:**
| Parameter Name | Data Type | Description            |
| -------------- | --------- | ---------------------- |
| unbilled_total | String    | Number. Unbilled total |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```
N/A
```

**Sample response:**
```json=
{
    "unbilled_total": "1.8"
}
```

## Compute Expected Campaign Cost
Compute expected campaign cost

Path: `/organizations/{organization_id}/invoices/expected-cost`  
Method: `POST`  
Success status code: `200`

**Path parameters:**
| Parameter Name  | Data Type | Required | Description     |
| --------------- | --------- | -------- | --------------- |
| organization_id | String    | Yes      | Organization ID |

**Request parameters:**
| Parameter Name | Data Type | Required | Description                      |
| -------------- | --------- | -------- | -------------------------------- |
| filename       | String    | Yes      | File name                        |
| file_content   | String    | Yes      | Base64 encoded campaign csv file |

**Response parameters:**
| Parameter Name | Data Type | Description           |
| -------------- | --------- | --------------------- |
| expected_cost  | String    | Number. Expected cost |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```json=
{
        "filename": "campaign.csv",
        "file_content": "bWVzc2FnZSxtb2JpbGVfbnVtYmVyDQpUaGlzIGlzIG1lc3NhZ2UgbnVtYmVyIDEsOTQ1NjM3OTIwNA0KVGhpcyBpcyBtZXNzYWdlIG51bWJlciAyLDk0NTYzNzkyMDQ="
}
```

**Sample response:**
```json=
{
    "expected_cost": "0.6"
}
```

## Get All Balances
Get all balances of all all organizations

Path: `/organizations/balances`  
Method: `GET`  
Success status code: `200`

**Query parameters:**

| Parameter Name | Data Type | Required | Description                                             |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| page           | String    | No       | Page number requested of pagination as provided by xero |
| order          | String    | No       | Sorting order                                           |

**Response parameters:**
List of dictionaries containing the following: `organization_id, organization_name, balances`
| Parameter Name | Data Type | Description           |
| -------------- | --------- | --------------------- |
| organization_id  | String    | Unique identifier of an organization |
| organization_name  | String    | Organization name |
| balances | Dictionary | Contains the following details: `AccountsReceivable, AccountsPayable` |
| AccountsReceivable | Dictionary | Sales invoices. Contains the following fields: `Outstanding, Overdue` |
| AccountsPayable | Dictionary | Bills. Contains the following fields: `Outstanding, Overdue` |

**Request headers:**
```json=
{
    "headers": {
        "Authorization": "Bearer <bearer_token>"
    }
}
```

**Sample request body:**
```json=
```

**Sample response:**
```json=
[
    {
        "organization_id": "3c5d7ab7-bbc9-47cf-afbf-845b1556c556",
        "organization_name": "organization-3c5d",
        "balances": {
            "AccountsReceivable": {
                "Outstanding": 1.2,
                "Overdue": 0.0
            },
            "AccountsPayable": {
                "Outstanding": 0.0,
                "Overdue": 0.0
            }
        }
    },
    {
        "organization_id": "1e591749-535d-4a8f-80fe-e82bb22d11f8",
        "organization_name": "organization-1e59",
        "balances": {
            "AccountsReceivable": {
                "Outstanding": 0.0,
                "Overdue": 0.7
            },
            "AccountsPayable": {
                "Outstanding": 0.0,
                "Overdue": 0.0
            }
        }
    }
]
```