Skip to main content

Create a note

Use the POST /notes endpoint to create a note and attach it to a specific resource: an entity, assessment, task, or risk output.

Request

To create a new note, make a POST request to the /notes endpoint.

To authenticate your request, include the apikey: YOUR_API_KEY header. See Manage API keys for more information.

Parameters

Include the following required fields in the request body:

Field

Type

Description

content

string

required

The text content of the note.

Maximum size: 2048 bytes

identifier

string

required

The resource the note is attached to. The identifier must include one of the supported resource IDs: entity_id, assessment_id, task_id, or risk_output_id.

Sample request

The following example adds a note to a specified entity. This note will be visible to users in the platform on the entity's notes panel and recorded in the entity's audit record.

curl --request "POST" \ 
 "https://{api_region}/v5/notes" \ 
 --header "apikey: API_KEY" \ 
 --header "Content-Type: application/json" \ 
 --data "{  
  "content": "This entity requires further review.",
  "identifier": {
   "entity_id": "8161163a-f227-466f-bc01-090a01e80165"
  }
 }"

Replace {api_region} with the domain from your region's base URL.

Response

A successful request returns a 201 Created response. The note is created and attached to your specified resource.

{ 
 "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", 
 "content": "This entity requires further review.", 
 "entity_id": "8161163a-f227-466f-bc01-090a01e80165", 
 "assessment_id": null, 
 "risk_output_id": null, 
 "task_id": null
}

Troubleshooting

  • If you receive a 401 Unauthorized response, make sure the apikey header is included and contains a valid key. Check that you are using the correct base URL for your region, and if IP allow listing is enabled, verify your request originates from an allowed IP address.

  • If you receive a 404 Associated resource not found response, check that the resource ID you supplied for the identifier parameter is correct.

  • A response of 409 Maximum number of notes for this resource has been exceeded indicates that the maximum number of 1000 notes per resource has been exceeded.

  • A response of 413 Note content exceeds the maximum allowed size indicates that the note content exceeds the maximum size of 2048 bytes.

  • If you receive a 500 Internal server error response, it means the server couldn't fulfill your request due to an unexpected error. If you can't resolve the issue internally, email our Client Service team.

For a full list of the possible error codes, view the API reference.

Additional information