> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Create Transaction Note > Add a plain-text note, with optional member mentions, to a monitored transaction's review timeline from your own systems. Create Transaction Note API Prompt Copy prompt to clipboard \

\`Add a note to a Didit monitored transaction through the Management API.

Endpoint:
POST https://verification.didit.me/v3/transactions/{transaction_id}/notes/

Authentication:
Use the x-api-key header with my Didit API key. A scoped key needs transactions: write. Keys limited to specific workflows or to approved sessions cannot call this endpoint.

Goal:
\- Record context from my own systems (a support call, a manual check, an outcome from my case tool) on the transaction's review timeline, where Console reviewers see it.

Path parameter:
\- transaction_id: the Didit transaction uuid, not my own txn_id.

Request body (application/json):
\{
"note": "Customer confirmed the withdrawal by phone.",
"mentioned_emails": ["analyst@example.com"]
}
\- note: required. Plain text, no length limit. Leading and trailing whitespace is trimmed and a blank note is rejected.
\- mentioned_emails: optional list of emails of members of my organization to mention.

Behavior:
\- Returns 201 with the created note. actor_email and actor_name are null because the note comes from an API key, not a person.
\- Every mentioned email must belong to a member of my organization; one unknown address fails the whole request with 400. Mentions are stored lower-cased and de-duplicated in metadata.mentioned_emails. This endpoint does not notify the mentioned members.
\- Each call creates a new note. Retrying a request that timed out can add the same note twice, so check GET /v3/transactions/{transaction_id}/notes/ before retrying.
\- There is no API endpoint to edit or remove a note.

Example call:
curl -X POST "https://verification.didit.me/v3/transactions/{transaction_id}/notes/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": ["analyst@example.com"]}'

What to read from the response:
\- uuid: the note id.
\- created_at: when the note was stored.
\- metadata.mentioned_emails: the normalized mention list (empty when nobody was mentioned).

Failure modes:
\- 400: note missing ({"note": ["This field is required."]}) or blank, an invalid email in mentioned_emails, or a mentioned address outside my organization ({"mentioned_emails": ["Mentioned users must belong to this organization and have access to this application."]}).
\- 401: the API key has expired.
\- 403: missing or invalid API key, a scoped key without transactions: write ({"detail": "This API key has no write access to transactions."}), a key with workflow or status limits, or a request from outside the key's IP allowlist.
\- 404: no transaction with this uuid in my application ({"detail": "No Transaction matches the given query."}).
\- 429: more than 300 write requests per minute with this key; wait Retry-After seconds and retry.

Side effects: creates the note and adds a TRANSACTION_NOTE_ADDED entry to the transaction's activities. The transaction's status, score and alerts do not change, no webhook is sent, and nothing is billed.

For the full integration shape, see /integration/integration-prompt.`

\
Paste into A note is context, not a decision: it never changes the transaction's `status`, `score` or alerts. Reviewers see it under **Notes** on the [transaction detail](/transaction-monitoring/console.md#transaction-detail) in the Console, and the transaction's `activities` gain a `TRANSACTION_NOTE_ADDED` entry, which you can read with [Get transaction](/management-api/transactions/get.md).Because the note comes from an API key, it carries no author: `actor_email` and `actor_name` are `null`. If you need to show who wrote it, include that in the note text. Read the full timeline back with [List transaction notes](/management-api/transactions/list-notes.md). ## OpenAPI ````yaml POST /v3/transactions/{transaction_id}/notes/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/transactions/{transaction_id}/notes/: post: tags: - Transactions summary: Create transaction note description: >- Add a plain-text note to a monitored transaction's review timeline, where Console reviewers see it. A note is context, not a decision: the transaction's `status`, `score` and alerts do not change, no webhook is sent, and nothing is billed. The transaction's `activities` gain a `TRANSACTION_NOTE_ADDED` entry. Notes created with an API key have no author: `actor_email` and `actor_name` are `null`, so put the author in the text if you need it. Every address in `mentioned_emails` must belong to a member of your organization, otherwise the whole request fails with `400`; mentions are stored lower-cased and de-duplicated, and this endpoint does not notify the mentioned members. Each call creates a new note, so retrying a timed-out request can add it twice: list the notes before retrying. There is no API endpoint to edit or remove a note. A scoped API key needs `transactions: write`; a key limited to some workflows or to approved sessions cannot call this endpoint. operationId: create_transaction_note parameters: - name: transaction_id in: path required: true description: >- Didit transaction UUID: the `uuid` returned by `POST /v3/transactions/` and `GET /v3/transactions/`. Your own `txn_id` is not accepted. schema: type: string format: uuid example: abcdef12-3456-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: type: object required: - note properties: note: type: string minLength: 1 description: >- Plain-text note. Leading and trailing whitespace is trimmed and a blank note is rejected. No length limit. mentioned_emails: type: array items: type: string format: email default: [] description: >- Emails of members of your organization to mention. Each must be a valid email of an organization member. examples: Note with a mention: value: note: Customer confirmed the withdrawal by phone. mentioned_emails: - analyst@example.com Plain note: value: note: Source of funds document requested by email. responses: '201': description: The note was created. content: application/json: schema: $ref: '#/components/schemas/TransactionNote' examples: Created: value: uuid: c1111111-2222-4333-8444-555555555555 note: Customer confirmed the withdrawal by phone. actor_email: null actor_name: null metadata: mentioned_emails: - analyst@example.com created_at: '2026-10-16T10:05:12.481203Z' '400': description: >- The body is invalid: `note` missing, null or blank, an invalid address in `mentioned_emails` (errors keyed by list position), or a mentioned address that is not a member of your organization. Nothing is created. content: application/json: schema: type: object description: Field errors keyed by field name. additionalProperties: {} examples: Missing note: value: note: - This field is required. Blank note: value: note: - This field may not be blank. Invalid email: value: mentioned_emails: '0': - Enter a valid email address. Not an organization member: value: mentioned_emails: - >- Mentioned users must belong to this organization and have access to this application. '401': description: >- The API key has expired. Only a key created with an expiry date can expire; after that date every request with it answers `401`. content: application/json: schema: type: object properties: detail: type: string examples: Expired key: value: detail: This API key has expired. '403': description: >- The request is not allowed. A missing or invalid API key gets the generic message (never `401`). content: application/json: schema: type: object properties: detail: type: string examples: Missing or invalid key: value: detail: You do not have permission to perform this action. Scoped key without transactions write: value: detail: This API key has no write access to transactions. Key limited to workflows or approved sessions: value: detail: >- This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint. Outside the key's IP list: value: detail: This API key can't be used from this IP address. '404': description: >- No transaction with this UUID exists in the application (never created, deleted, or owned by another application). A `transaction_id` that is not a UUID does not reach the API: it returns a `404` HTML page instead of this JSON body. content: application/json: schema: type: object properties: detail: type: string examples: Not found: value: detail: No Transaction matches the given query. '429': description: >- More than 300 write requests per minute with this API key. Wait the number of seconds in `Retry-After`, then retry. content: application/json: schema: type: object properties: detail: type: string examples: Throttled: value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. headers: Retry-After: description: Seconds until the current one-minute window resets. schema: type: integer example: 23 X-RateLimit-Limit: description: Requests allowed per minute in this budget. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer X-RateLimit-Reset: description: Unix time when the window resets. schema: type: integer security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": ["analyst@example.com"]}' - lang: python label: Python source: |- import os import requests transaction_id = 'abcdef12-3456-7890-abcd-ef1234567890' resp = requests.post( f'https://verification.didit.me/v3/transactions/{transaction_id}/notes/', headers={'x-api-key': os.environ['DIDIT_API_KEY']}, json={ 'note': 'Customer confirmed the withdrawal by phone.', 'mentioned_emails': ['analyst@example.com'], }, timeout=10, ) resp.raise_for_status() note = resp.json() print(note['uuid'], note['created_at']) - lang: javascript label: JavaScript source: >- const transactionId = 'abcdef12-3456-7890-abcd-ef1234567890'; const resp = await fetch(`https://verification.didit.me/v3/transactions/${transactionId}/notes/`, { method: 'POST', headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ note: 'Customer confirmed the withdrawal by phone.', mentioned_emails: ['analyst@example.com'], }), }); if (!resp.ok) throw new Error(`Create note failed: ${resp.status}`); const note = await resp.json(); console.log(note.uuid, note.created_at); components: schemas: TransactionNote: type: object description: One note on a monitored transaction's review timeline. required: - uuid - note - actor_email - actor_name - metadata - created_at properties: uuid: type: string format: uuid description: Note identifier. note: type: string description: Plain-text note body. actor_email: type: string format: email nullable: true description: >- Email of the Console user who wrote the note or changed the status. `null` for notes created with an API key and for notes Didit adds automatically. actor_name: type: string nullable: true description: >- Display name of the Console user (their email when they have no name). `Rule Engine` on notes Didit adds automatically. `null` for notes created with an API key. metadata: type: object description: >- Tells the note types apart. Notes written through the API or the Console carry `mentioned_emails`. A status change made in the Console carries `type: status_change` with `previous_status`, `new_status`, `reason_code` and `reason_label`. Notes Didit adds carry `source`: `rule_action` (with `rule_uuid`) for a rule's `add_note` action, or `remediation_session` for a problem creating the user-action verification session. properties: mentioned_emails: type: array items: type: string format: email description: >- Mentioned organization members, lower-cased and de-duplicated. Empty when nobody was mentioned. type: type: string enum: - status_change description: Present on notes recording a status change made in the Console. previous_status: type: string enum: - APPROVED - IN_REVIEW - DECLINED - AWAITING_USER description: Status before the change. new_status: type: string enum: - APPROVED - IN_REVIEW - DECLINED - AWAITING_USER description: Status after the change. reason_code: type: string nullable: true description: Reason code given with the change. reason_label: type: string nullable: true description: Reason label given with the change. source: type: string enum: - rule_action - remediation_session description: Present on notes Didit adds automatically. rule_uuid: type: string format: uuid description: >- Rule whose `add_note` action wrote the note (with `source: rule_action`). created_at: type: string format: date-time description: When the note was stored. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.