getLocationNotes

POST public/getLocationNotes

Returns the notes for a location, or for a company and its locations. Notes are the same notes you see in the SC//AcuVigil dashboard, such as notes you add and notes SC//AcuVigil adds automatically when an ESD changes.

Request syntax

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

curl https://apiv2.acumera.net/public/getLocationNotes \
  --cookie av_session.txt \
  --data-urlencode "company_id=<company_id>" \
  [--data-urlencode "company_level_only=1"]

Send either location_id or company_id. If you send both, location_id is used. Optional parameters are shown in brackets. 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 the location to return notes for. Send this or `company_id`. To find location IDs, use getCompanyInfo with `include_sites=1`.	Conditional
`company_id`	Integer	The ID of the company to return notes for. Send this or `location_id`. Returns the company's own notes and the notes of its locations. To find your company ID, use getCompanyInfo.	Conditional
`company_level_only`	Integer	With `company_id`, set to `1` to return only the company's own notes, not its locations' notes.	No	`0`

Response syntax

{
    "success": "string",
    "data": {
        "location_notes": [
            {
                "id": "string",
                "topic": "string",
                "note": "string",
                "category": "string",
                "category_name": "string",
                "created": "string",
                "created_by": "string",
                "created_by_name": "string",
                "pinned": "string",
                "editable": "string",
                "shipping_provider": "string",
                "tracking_number": "string",
                "location_id": "string",
                "filename": "string",
                "file_description": "string",
                "file_created": "string"
            }
        ]
    }
}

Response parameters

If the call succeeds, success is "1" and the following data is returned. All values are strings. Pinned notes come first, then the newest notes.

Field	Description
`location_notes`	The notes. Empty if there are none. Private notes, which Scale Computing uses internally, aren't returned.
`id`	The note's ID. Use it with getLocationNote, updateLocationNote, and deleteLocationNote.
`topic`	The note's title.
`note`	The note's text.
`category`	The category ID.
`category_name`	The category name, for example `General`, or `MG Change` for notes SC//AcuVigil adds when an ESD changes.
`created`	When the note was created, as a Unix timestamp.
`created_by`	The user ID of the person who created the note.
`created_by_name`	The name of the person who created the note.
`pinned`	`"1"` if the note is pinned, otherwise `"0"`.
`editable`	`"1"` if you can edit or delete the note, otherwise `"0"`.
`shipping_provider`	The shipping provider, for notes that track a shipment. Otherwise empty.
`tracking_number`	The tracking number, for notes that track a shipment. Otherwise empty.
`location_id`	The location the note belongs to. A company-level note has `company_id` instead.
`filename`	Only for notes with an attachment: the attachment's stored filename. Use it with getLocationNoteAttachment.
`file_description`	Only for notes with an attachment: the attachment's description.
`file_created`	Only for notes with an attachment: when it was attached, 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
`LOCATION_NOT_FOUND`	The location was not found.	No location has that ID.
`COMPANY_NOT_FOUND`	The company was not found.	No company has that ID.
`AUTH_FAILED_FUNC_NOT_ALLOWED`	Authorization failed because you are not permitted to access the requested function.	Neither `location_id` nor `company_id` was sent, or your account doesn't have access to the location or company.
`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: List the notes for a location

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

Response:

{
    "success": "1",
    "data": {
        "location_notes": [
            {
                "id": "123457",
                "topic": "Router replaced",
                "note": "The ISP replaced the router on Monday.",
                "category": "5",
                "category_name": "General",
                "created": "1793398094",
                "created_by": "1001",
                "created_by_name": "Pat Example",
                "pinned": "0",
                "editable": "1",
                "shipping_provider": "",
                "tracking_number": "",
                "location_id": "4510",
                "filename": "rack_1793398094.png",
                "file_description": "Network rack",
                "file_created": "1793398094"
            },
            {
                "id": "123456",
                "topic": "Network device 0041ac000003 activated by Pat Example",
                "note": "",
                "category": "8",
                "category_name": "MG Change",
                "created": "1703270067",
                "created_by": "1001",
                "created_by_name": "Pat Example",
                "pinned": "0",
                "editable": "1",
                "shipping_provider": "",
                "tracking_number": "",
                "location_id": "4510"
            }
        ]
    }
}

Example: List only a company's own notes

curl https://apiv2.acumera.net/public/getLocationNotes \
  --cookie av_session.txt \
  --data-urlencode "company_id=121" \
  --data-urlencode "company_level_only=1"

The response has the same structure. Each note has company_id instead of location_id.