Getting started with the SC//AcuVigil API

This guide covers how to authenticate with the SC//AcuVigil™ API and how to call its public functions. It applies to every function under the public API.

Requirements

• A valid SC//AcuVigil user account (your username is your email address)
• Your account password
• A multi-factor authentication (2FA) token — the 6-digit code from your authenticator app

Your account must also have permission to use the function you are calling. API permissions mirror what your account can see and do in the SC//AcuVigil dashboard.

The basics

Every public function is an HTTPS endpoint of the form:

https://apiv2.acumera.net/public/<functionName>

Send parameters as a form-encoded POST body. Responses are JSON.

Every response includes a success field:

Always check success before using the response — a failed call still returns HTTP 200 with success: "0" and an explanatory returnCode.

Authentication

There are two ways to authenticate. Both use the same three credentials:

Recommended: log in once and use a session cookie

Call the login function first. On success, the API sets an authentication cookie; present that cookie on subsequent calls and omit the credential parameters entirely.

# 1. Log in and save the cookie
curl https://apiv2.acumera.net/public/login \
  --cookie-jar av_session.txt \
  --data-urlencode "username=you@example.com" \
  --data-urlencode "password=YourPassword" \
  --data-urlencode "tfa_token=123456"

{
  "success": "1",
  "returnCode": "LOGIN_SUCCESSFUL",
  "returnMessage": "Login successful."
}

# 2. Call any function with the cookie — no credentials needed
curl https://apiv2.acumera.net/public/getSupportInfo \
  --cookie av_session.txt

{
  "success": "1",
  "data": {
    "support_info": {
      "mg_esd_url": "https:\/\/install.acumera.net\/en\/Safety_MGESD.pdf",
      "noc_install_videos_url": "https:\/\/install.acumera.net\/",
      "noc_phone_number": "+1 512 687 7401"
    }
  }
}

# 3. End the session when finished
curl https://apiv2.acumera.net/public/logout --cookie av_session.txt

The session approach is recommended for all use, and especially for scripts that make many calls: you only need one valid 2FA code at the start of the run instead of a fresh code per request.

Alternative: credentials on every request

If you prefer not to manage a cookie — for example, in a one-off call or a tool without cookie support — include username, password, and tfa_token alongside the function's own parameters in each call. No session state is required.

curl https://apiv2.acumera.net/public/getSupportInfo \
  --data-urlencode "username=you@example.com" \
  --data-urlencode "password=YourPassword" \
  --data-urlencode "tfa_token=123456"

Successful response:

{
  "success": "1",
  "data": {
    "support_info": {
      "mg_esd_url": "https:\/\/install.acumera.net\/en\/Safety_MGESD.pdf",
      "noc_install_videos_url": "https:\/\/install.acumera.net\/",
      "noc_phone_number": "+1 512 687 7401"
    }
  }
}

Keep in mind that 2FA codes rotate every 30–60 seconds. If you are looping over many calls with this method, be prepared to supply a fresh tfa_token when a call fails with INVALID_LOGIN.

Authentication failures

An invalid username, password, or expired 2FA code returns:

{
  "success": "0",
  "returnCode": "INVALID_LOGIN",
  "returnMessage": "We were unable to log you in. Make sure you entered the correct username, password and 2FA code."
}

Fix the credentials (usually: enter a fresh 2FA code) and retry.

Calling functions

Function parameters are sent in the same POST body as the credentials (or alone, when using a session cookie). A few representative examples:

Support contacts — getSupportInfo

No parameters. It returns the same data to every authenticated user and changes nothing, which makes it a safe first call for checking credentials and connectivity before building anything.

Company and site information — getCompanyInfo

curl https://apiv2.acumera.net/public/getCompanyInfo \
  --cookie av_session.txt \
  --data-urlencode "customer_code=(Your Customer Code)" \
  --data-urlencode "include_sites=1"

Returns company details in data; with include_sites=1, data.locations[] lists every location with its location_id, name, address, and current status.

Device status — getStatusDocument

Returns the current status document(s) for all devices at a location. Supply either location_id or serial_number.

curl https://apiv2.acumera.net/public/getStatusDocument \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510"

The data object is keyed by device serial number; each entry includes the location ID, location name, overall status (OK, INFO, WARNING, CRITICAL, DOWN), the report timestamp, and detailed per-application status.

Registered devices — getRegisteredDevices

Returns the devices registered at a location along with their current status. Takes location_id.

Firewall policies — getPolicies

Returns the firewall policies for a company or location.

Error handling

• Check success on every response. HTTP status alone does not indicate API-level success or failure.
• Branch on returnCode, not returnMessage — codes are stable machine-readable identifiers; messages are for people.
• Each function documents its own error codes (for example, TARGET_COMPANY_NOT_FOUND from getCompanyInfo, or NO_LOCATION_SELECTED from location-based functions).

Good practices

• Protect your credentials. Never hard-code passwords in scripts or commit them to source control. Load them from a secured configuration file or environment variables, and prompt for the 2FA code at runtime.
• Prefer a login session. One login call at the start of a run avoids 2FA-rotation failures mid-loop, and logout cleanly ends the session.
• Pace your requests. When iterating over many locations, add a short delay between calls.
• Treat IDs as strings. Location IDs, company codes, and serial numbers should be handled as text values, exactly as returned by the API.

Function reference

The full public function catalog is documented in the Function reference, which has a page per function giving its parameters, a sample request, a sample response, and its return codes. The functions are grouped into Authentication, Companies, Locations, Location notes, Location photos, Devices, Installation and activation, and Platform services.