addLocationNote

POST public/addLocationNote

Adds a note to a location or a company, optionally with one file attached. Notes added this way are in the General category.

Request syntax

curl https://apiv2.acumera.net/public/addLocationNote \
  --cookie av_session.txt \
  --data-urlencode "location_id=<location_id>" \
  --data-urlencode "topic=<topic>" \
  --data-urlencode "note=<note_text>" \
  [--data-urlencode "filename=<filename>"] \
  [--data-urlencode "content_type=<mime_type>"] \
  [--data-urlencode "content_length=<size_in_bytes>"] \
  [--data-urlencode "file_content=<base64_file_content>"] \
  [--data-urlencode "file_description=<description>"]

Send location_id for a location note, or company_id instead for a company note. Optional parameters are shown in brackets; to attach a file, send filename, content_type, content_length, and file_content. 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 add the note to. Send this or `company_id`.	Conditional
`company_id`	Integer	The ID of the company to add the note to. Send this or `location_id`; it's ignored if you send both.	Conditional
`topic`	String	The note's title.	Yes
`note`	String	The note's text.	Yes
`filename`	String	The name of a file to attach, for example `rack.png`.	No
`content_type`	String	The attachment's MIME type, for example `image/png`. Required if you send `filename`.	Conditional
`content_length`	Integer	The attachment's size in bytes. Required if you send `filename`.	Conditional
`file_content`	String	The attachment, base64-encoded. Required if you send `filename`.	Conditional
`file_description`	String	A description of the attachment. Letters, numbers, and spaces.	No	The filename without its extension

topic and note can contain letters, numbers, spaces, line breaks, and these characters: # & ' " ( ) * + , - . / : @ _ < > ! ?

Response syntax

{
    "success": "string",
    "returnCode": "string",
    "returnMessage": "string"
}

Response parameters

Field	Description
`success`	`"1"` if the note was added.
`returnCode`	`NOTE_CREATED` when the note was added.
`returnMessage`	A description of the result.

The response doesn't include the new note's ID. To get it, call getLocationNotes. An attachment is stored with a timestamp added to its filename, for example rack.png becomes rack_1793398094.png.

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.
`NO_NOTE_TOPIC`	The note requires a topic.	`topic` is missing or empty.
`INVALID_NOTE_TOPIC`	The topic contains invalid characters.	`topic` contains a character that isn't allowed.
`NO_NOTE_NOTE`	The note cannot be empty.	`note` is missing or empty.
`INVALID_NOTE_NOTE`	The note contains invalid characters.	`note` contains a character that isn't allowed.
`MISSING_CONTENT_LENGTH`	The Content-Length value was not supplied.	`filename` was sent, but `content_length` is missing or isn't a number.
`MISSING_CONTENT_TYPE`	The Content-Type value was not supplied.	`filename` was sent, but `content_type` is missing.
`MISSING_FILE_CONTENT`	The file content was not supplied.	`filename` was sent, but `file_content` is missing.
`INVALID_DESCRIPTION`	Description contains invalid characters.	`file_description` contains a character that isn't allowed.
`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: Add a note to a location

curl https://apiv2.acumera.net/public/addLocationNote \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "topic=Router replaced" \
  --data-urlencode "note=The ISP replaced the router on Monday."

Response:

{
    "success": "1",
    "returnCode": "NOTE_CREATED",
    "returnMessage": "The note has been created."
}

Example: Add a note with a photo attached

This example attaches rack.png. The shell reads the file, base64-encodes it, and measures its size.

curl https://apiv2.acumera.net/public/addLocationNote \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "topic=Rack photo" \
  --data-urlencode "note=Photo of the network rack after the router swap." \
  --data-urlencode "filename=rack.png" \
  --data-urlencode "content_type=image/png" \
  --data-urlencode "content_length=$(wc -c < rack.png | tr -d ' ')" \
  --data-urlencode "file_content=$(base64 < rack.png | tr -d '\n')" \
  --data-urlencode "file_description=Network rack"

Response:

{
    "success": "1",
    "returnCode": "NOTE_CREATED",
    "returnMessage": "The note has been created."
}

Example: Send a topic with a character that isn't allowed

{
    "success": "0",
    "returnCode": "INVALID_NOTE_TOPIC",
    "returnMessage": "The topic contains invalid characters."
}