Response Notes API

Add internal notes to responses during review and approval workflows. Track decision rationale and compliance documentation.

Response Notes vs Comments

Response Notes are attached to the entire response (for approval decisions). Comments are attached to specific answers (for question-level feedback).

Response Note Object

The response note object represents an internal note attached to a response, typically used for approval decisions and workflow documentation.

Attributes

Field	Type	Description
`id`	string	Unique identifier for the note
`text`	string	Note text content (encrypted at rest)
`status_transition`	string	Optional status change: `APPROVED`, `REJECTED`, `CHANGES_REQUESTED`, or `null`
`profile_name`	string	Name of the user who created the note
`profile_email`	string	Email of the user who created the note
`created_at`	datetime	ISO 8601 timestamp of when the note was created

List Response Notes

Retrieve all notes for a specific response.

GET /api/v1/responses/{response_id}/notes/

Path Parameters

Parameter	Type	Description
`response_id`	uuid	ID of the response

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token: `Bearer YOUR_API_KEY`

Response

{
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "response_name": "ACME Corporation - Vendor DDQ 2026",
  "response_status": "APPROVED",
  "count": 2,
  "notes": [
    {
      "id": "note_123",
      "text": "All documentation verified. Screening passed with no matches.",
      "status_transition": "APPROVED",
      "profile_name": "Jane Smith",
      "profile_email": "[email protected]",
      "created_at": "2026-01-19T14:30:00Z"
    },
    {
      "id": "note_124",
      "text": "Initial review complete. Minor clarification needed on Q15.",
      "status_transition": null,
      "profile_name": "John Doe",
      "profile_email": "[email protected]",
      "created_at": "2026-01-19T10:30:00Z"
    }
  ]
}

Create Response Note

Add a new note to a response, optionally with a status transition.

POST /api/v1/responses/{response_id}/notes/

Path Parameters

Parameter	Type	Description
`response_id`	uuid	ID of the response

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token: `Bearer YOUR_API_KEY`
`Idempotency-Key`	string	Recommended	Unique key to prevent duplicate note creation. Retrying with the same key returns the original note.

Request Body

Field	Type	Required	Description
`text`	string	Yes	Note text (encrypted at rest)
`status_transition`	string	No	Optional status change: `APPROVED`, `REJECTED`, `CHANGES_REQUESTED`

Valid Status Transitions

Status	Description	Use Case
`APPROVED`	Final approval	All checks passed, approved for business
`REJECTED`	Final rejection	Failed critical checks, cannot proceed
`CHANGES_REQUESTED`	Send back to entity	Need additional information or corrections
`null`	No status change	General review note

Response

{
  "id": "note_125",
  "text": "Verified incorporation certificate matches company registry",
  "status_transition": null,
  "created_at": "2026-01-19T16:45:00Z"
}

Delete Response Note

Delete a response note. This action is logged in the audit trail for compliance.

DELETE /api/v1/responses/{response_id}/notes/{note_id}/

Path Parameters

Parameter	Type	Description
`response_id`	uuid	ID of the response
`note_id`	string	ID of the note to delete

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token: `Bearer YOUR_API_KEY`

Response

Returns 204 No Content on success.

Audit Trail

Note deletions are logged in the audit trail for compliance. Consider marking notes as outdated rather than deleting them if you need a complete history.

import requests response_id = '550e8400-e29b-41d4-a716-446655440000' response = requests.get( f'https://api.kycgenie.com/api/v1/responses/{response_id}/notes/', headers={'Authorization': 'Bearer YOUR_API_KEY'} ) notes_data = response.json() print(f"Response: {notes_data['response_name']}") print(f"Status: {notes_data['response_status']}") print(f"Notes: {notes_data['count']}") for note in notes_data['notes']: print(f"\n{note['profile_name']} ({note['created_at']}):") print(f" {note['text']}") if note['status_transition']: print(f" Status transition: {note['status_transition']}")

curl -X POST 'https://api.kycgenie.com/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/notes/' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: note-create-12345' \ -d '{ "text": "Verified incorporation certificate matches company registry" }'

import requests response_id = '550e8400-e29b-41d4-a716-446655440000' response = requests.post( f'https://api.kycgenie.com/api/v1/responses/{response_id}/notes/', headers={ 'Authorization': 'Bearer YOUR_API_KEY', 'Idempotency-Key': 'note-create-12345' }, json={ 'text': 'Verified incorporation certificate matches company registry' } ) note = response.json() print(f"Created note: {note['id']}")

curl -X POST 'https://api.kycgenie.com/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/notes/' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: note-approval-67890' \ -d '{ "text": "All checks passed. Approved for onboarding.", "status_transition": "APPROVED" }'

import requests response_id = '550e8400-e29b-41d4-a716-446655440000' response = requests.post( f'https://api.kycgenie.com/api/v1/responses/{response_id}/notes/', headers={ 'Authorization': 'Bearer YOUR_API_KEY', 'Idempotency-Key': 'note-approval-67890' }, json={ 'text': 'All checks passed. Approved for onboarding.', 'status_transition': 'APPROVED' } ) note = response.json() print(f"Created note with approval: {note['id']}") # Response status will change to APPROVED

import requests response_id = '550e8400-e29b-41d4-a716-446655440000' note_id = 'note_123' response = requests.delete( f'https://api.kycgenie.com/api/v1/responses/{response_id}/notes/{note_id}/', headers={'Authorization': 'Bearer YOUR_API_KEY'} ) # Returns 204 No Content on success print(f"Status: {response.status_code}")