getPolicies

POST public/getPolicies

Returns the policy documents for a location or a company. Policy documents hold firewall policies and company-wide settings, such as maintenance windows and speed test settings. Scale Computing creates and maintains these documents as part of the managed service. For more information, see Firewall policies.

Request syntax

curl https://apiv2.acumera.net/public/getPolicies \
  --cookie av_session.txt \
  --data-urlencode "location_id=<location_id>"

curl https://apiv2.acumera.net/public/getPolicies \
  --cookie av_session.txt \
  --data-urlencode "customer_code=<customer_code>"

Send either location_id or customer_code. If you send both, location_id is used. The username, password, and tfa_token parameters are also accepted, and are required only if the client hasn't already signed in with login. See Getting started with the SC//AcuVigil API.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter Type Description Required Default value
location_id Integer The ID of a location. Send this or customer_code. Returns the company's policy documents and the location's own. Conditional
customer_code String Your company's customer code: five lowercase letters, for example exmpl. Send this or location_id. Returns the company's policy documents and those of every location that has its own. Conditional

Response syntax

{
    "success": "string",
    "data": {
        "corporate": {
            "<policy_name>": {
                "...": "...",
                "timestamp": "string"
            }
        },
        "<location_name>": {
            "<policy_name>": {
                "...": "...",
                "timestamp": "string"
            }
        }
    }
}

Response parameters

If the call succeeds, success is "1" and the following data is returned.

Field Description
corporate The company-level policy documents, keyed by policy name. Locations inherit these.
<location_name> The site-level policy documents for a location, keyed by policy name. Present only for locations that have their own.
<policy_name> One policy document. Its fields depend on the policy. The company-wide settings document is named after the customer code and holds settings such as maintenance, speedtest, and compliance (who requested and reviewed the last change).
<policy_name>.timestamp When the document was last saved, as a Unix timestamp.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code Message Cause
API_NO_LOCATION_OR_HANDLE_SUPPLIED Either a location ID or a customer code must be supplied. Neither location_id nor customer_code was sent.
API_INVALID_LOCATION_ID The supplied location ID is invalid. location_id isn't a number.
LOCATION_NOT_FOUND The location was not found. No location has that ID.
API_INVALID_HANDLE The supplied customer code is invalid. customer_code isn't five lowercase letters.
API_COMPANY_NOT_FOUND The specified company was not found. No company has that customer code.
AUTH_FAILED_FUNC_NOT_ALLOWED Authorization failed because you are not permitted to access the requested function. Your account doesn't have access to the company.
MG_TYPE_HARDWARE_NOT_FOUND No MG-type hardware is present at this location. The location has no supported ESD.
INVALID_LOGIN We were unable to log you in. Make sure you entered the correct username, password and 2FA code. You haven't signed in, your session has ended, or the credentials sent with the call are wrong.

Examples

Example: Get the policy documents for a company

curl https://apiv2.acumera.net/public/getPolicies \
  --cookie av_session.txt \
  --data-urlencode "customer_code=exmpl"

Response:

{
    "success": "1",
    "data": {
        "corporate": {
            "exmpl": {
                "modified": "231216203928",
                "maintenance": {
                    "update_approval_required": "1",
                    "permitted_hours": ["0", "1", "2", "3", "4", "5", "6", "22", "23"],
                    "permitted_days": ["1", "2", "3", "4"]
                },
                "speedtest": {
                    "enabled": "1",
                    "frequency": "daily",
                    "interfaces": ["wan", "backup"]
                },
                "fqdn": {
                    "enabled": "1"
                },
                "compliance": {
                    "requested_by": "pat@example.com",
                    "reviewed": "231216203928",
                    "reviewed_by": "pat@example.com",
                    "change_description": "Updated Company Policy Settings",
                    "signature": "0"
                },
                "timestamp": "1702759418"
            }
        }
    }
}

In this example, the company has only its company-wide settings document. A company with custom firewall policies also gets an entry for each policy, and locations with their own policies get their own keys.

Example: Get the policy documents for a location

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

The response has the same structure. corporate holds the company's documents, and a key named after the location (for example, Store 101) holds the location's own documents, if it has any.

Example: Send a customer code that isn't valid

{
    "success": "0",
    "returnCode": "API_INVALID_HANDLE",
    "returnMessage": "The supplied customer code is invalid."
}