Complete Guide: Using the Web API

What the Web API is and what it's for

The AdmCloud Web API is a REST API that exposes, over HTTPS and in JSON, almost everything you can do from the web screens: read and create customers, vendors, items, GL accounts, invoices, quotes, sales orders, purchase orders, receptions, deposits, journal entries, payroll and much more. That way an external system can read from and write to your company without a person having to log into the application.

The production base address is https://api.admcloud.net/api/, and each object has its own route. For example, listing customers is:

GET https://api.admcloud.net/api/Customers?skip=0&company=MyCompanyDB&role=Administrators&appid=00000000-0000-0000-0000-000000000000

Before you start: what to have at hand

• A plan that includes the API: Basic or higher (not available on Billing or Start).
• The Customization permission in your user group, so you can create the Integration.
• A real AdmCloud user and password: the API has no standalone keys; it always authenticates as a user of the company.
• Your company's database name (the company parameter). You can see it on the Web Services Integrations screen, in the Database Name field.
• The name of the user group the calls will run as (the role parameter; for example Administrators).
• The Integration ID (the appid parameter), which you get in step 1.

Step 1: create the Integration that authorizes API usage

Before your first call you must authorize in the system the program that will consume the API. You do that by creating an Integration: AdmCloud assigns it a unique identifier (the appid) that travels with every call, so each connected system is identified and can be switched off independently whenever you want.

1. Go to Web Services Integrations (Customization / System Administration menu) and click New Integration.
2. Enter a descriptive Name identifying the system that will use it (for example, "Order website" or "Branch point-of-sale integration"). The name is required and can't be duplicated.
3. Decide whether the integration should Execute as Administrator (see the warning below) and use Notes to record what it's for and who requested it.
4. Save. AdmCloud generates the Integration ID (the appid), which can no longer be changed.
5. Open the details of the integration you just created. There you'll find the appid, the database name and a list of ready-made sample URLs for the most used objects (Customers, Vendors, Items, Accounts, Invoices, Purchase Orders, Deposits, Journal Entries, etc.). It's the fastest way to test: copy a URL and open it in your browser.

Step 2: basic authentication (the simplest way)

Basic authentication (the HTTP standard) is the most direct way to call the API: on every call you send the user's email and password in the Authorization header, and the context data (company, group and integration) as parameters in the address.

• Header: Authorization: Basic <email:password in Base64>. Almost every tool and library builds it for you: you just type the user and password.
• company parameter: the company's database name. It tells the API which company to work on.
• role parameter: the name of the user group the call runs as (or roleid if you prefer to send its identifier).
• appid parameter: the ID of the Integration created in step 1.

A complete call looks like this:

GET https://api.admcloud.net/api/Customers?skip=0&company=MyCompanyDB&role=Administrators&appid=8f3c1e42-...-9b21
Authorization: Basic dXNlckBjb21wYW55LmNvbTpNeVBhc3N3b3Jk

When the call comes in, AdmCloud validates, in this order:

1. That the email and password are correct and the account isn't blocked.
2. That the user exists in the company given in company.
3. That the user group given in role (or roleid) is actually assigned to that user.
4. That the Integration for the appid exists and isn't marked as Disabled.
5. That the user has the privilege required for the operation... unless the integration is set to Execute as Administrator, in which case this step is skipped.

Step 3: token authentication

The alternative is to authenticate once and then use a token. The token is a signed string that already carries the session context inside (user, company, group, subsidiary and location), so subsequent calls don't send the password again: the token parameter is enough. This is the recommended option when your system makes many calls in a row or when you don't want the password travelling on every request.

1. (Optional) Find the user's companies. Using basic authentication and without the company parameter, call POST /api/Login/GetCompanies. It returns the user's companies, ordered by last login, with their identifier and database name.
2. Find the user group identifier (RoleID). You can get it by calling POST /api/Login/SelectCompany?CompanyID=..., which returns the user's available groups in that company; or take it from the identifier shown in the address when you open the group under User Groups inside the application.
3. Generate the token using basic authentication:

   POST https://api.admcloud.net/api/Token?Company=MyCompanyDB&RoleID=1c9a...&appid=8f3c1e42-...-9b21
   Authorization: Basic dXNlckBjb21wYW55LmNvbTpNeVBhc3N3b3Jk

   The response carries the token in the data field.
4. Use the token on the remaining calls, as the token parameter and with no authentication header:

   GET https://api.admcloud.net/api/Customers?skip=0&token=eyJhbGciOi...

Step 4: making your first call with Swagger or another tool

You don't need to write code to try the API. The recommended way is Swagger, the interactive documentation that also executes the calls:

1. Open https://api.admcloud.net/ApiDocumentation/ (inside the application, the same link is in the information notice on the Integrations screen).
2. At the top there's a module selector. Since the API exposes close to a thousand operations, the documentation is split into one document per module (General, Accounts Payable, Accounts Receivable, Banking, General Ledger, Inventory, Payroll, Point of Sale, System Administration, etc.). Pick the module of the object you're after.
3. Expand the operation you want to try (for example GET /api/Customers) and click Try it out.
4. Fill in the parameters: skip as 0, company with your database name, role with your user group name and appid with the integration ID. Then execute.
5. The first time, the browser will ask for user and password (the standard basic authentication dialog that appears on the 401). Enter your AdmCloud email and password; the browser reuses them on later calls.
6. Check the response body. If success is true, you're consuming the API correctly.

Other equally valid tools:

• The browser, plain and simple: copy one of the sample URLs from your Integration's details and open it. The browser will ask for user and password and show you the JSON.
• The API Explorer (apiexplorer.admcloud.net): a dedicated interface to browse the available objects and their parameters.
• Postman, Insomnia or similar: create the request, pick Basic Auth in the authorization tab and enter your email and password; add company, role and appid as query parameters.
• curl, from a terminal (see the sample below).

Step 5: a simple code sample

The three samples do the same thing: list the first customers using basic authentication. Replace the email, password, database name, group and appid with your own.

curl

curl -u "user@company.com:MyPassword" \
  "https://api.admcloud.net/api/Customers?skip=0&company=MyCompanyDB&role=Administrators&appid=8f3c1e42-...-9b21"

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string EMAIL = "user@company.com";
        const string PASSWORD = "MyPassword";
        const string COMPANY = "MyCompanyDB";
        const string ROLE = "Administrators";
        const string APPID = "8f3c1e42-...-9b21";

        using (var client = new HttpClient())
        {
            var credentials = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(EMAIL + ":" + PASSWORD));

            client.DefaultRequestHeaders.Authorization =
                new AuthenticationHeaderValue("Basic", credentials);

            var url = "https://api.admcloud.net/api/Customers"
                + "?skip=0"
                + "&company=" + COMPANY
                + "&role=" + ROLE
                + "&appid=" + APPID;

            var response = await client.GetAsync(url);
            var json = await response.Content.ReadAsStringAsync();

            Console.WriteLine(json);
        }
    }
}

JavaScript

const EMAIL = "user@company.com";
const PASSWORD = "MyPassword";
const COMPANY = "MyCompanyDB";
const ROLE = "Administrators";
const APPID = "8f3c1e42-...-9b21";

const url = "https://api.admcloud.net/api/Customers"
    + "?skip=0&company=" + COMPANY + "&role=" + ROLE + "&appid=" + APPID;

const response = await fetch(url, {
    method: "GET",
    headers: {
        "Authorization": "Basic " + btoa(EMAIL + ":" + PASSWORD)
    }
});

const result = await response.json();

if (result.success) {
    console.log(result.data);
} else {
    console.error(result.message);
}

Creating a record is just as simple: use POST against the same route, with the object in the request body as JSON. The response carries the new record's identifier in data:

curl -u "user@company.com:MyPassword" \
  -H "Content-Type: application/json" \
  -d '{ "Name": "Test customer", "Customer": true }' \
  "https://api.admcloud.net/api/Customers?company=MyCompanyDB&role=Administrators&appid=8f3c1e42-...-9b21"

Reading the response and paging

Every operation responds with the same structure:

{
    "success": true,
    "message": null,
    "data": [ ... ]
}

Lists are paged: they return at most 50 records per call. To walk through everything, keep increasing the skip parameter (0, 50, 100, ...) until a call returns an empty list.

Where the API documentation lives

All of these resources are linked from the information notice on the Web Services Integrations screen and also from each integration's details:

Security best practices

• Use a dedicated API user, not a person's personal account. When creating the user you can flag it as Only for API: it then can't sign into the web application and its password won't expire, which prevents an integration from breaking overnight.
• Give that user a group with the minimum permissions needed and turn off Execute as Administrator on the integration, so the API can't do more than that group allows.
• One integration per connected system, with notes explaining its purpose.
• Disable the integration as soon as a system stops being used or you notice odd activity; it's immediate, reversible and keeps the history.
• Keep credentials server-side, never in code downloaded to the end user's browser.
• Always call over HTTPS to the API's published addresses.

Tips and common mistakes