Update Agent

post/extensions/roboledger/{graph_id}/operations/update-agent

Patch counterparty fields. Only supplied fields are updated. Set is_active=false to deactivate (agents are never deleted — they are reference data referenced by events and transactions). classification_element_id sets the account this counterparty's bank lines are suggested (an empty string clears it), and classification_mode='always_ask' stops suggesting one for a counterparty whose lines go to different accounts; its still-open lines are re-suggested at once. Each entity of a group keeps its own default, on its own chart: classification_entity_id names the one these fields are for, omitted the group parent. A default is also learned as lines are committed, so set one by hand only to correct it.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`agent_id`required	string	The agent to update.
`name`optional	string
`legal_name`optional	string
`tax_id`optional	string
`registration_number`optional	string
`duns`optional	string
`lei`optional	string
`email`optional	string
`phone`optional	string
`address`optional	object
`is_active`optional	boolean	Toggle activation. Inactive agents are hidden from new-transaction pickers.
`is_1099_recipient`optional	boolean
`classification_element_id`optional	string	The chart account this counterparty's bank lines are usually classified to, suggested on each new line. An empty string clears it. Its still-open lines are re-suggested at once. Omit to keep.
`classification_mode`optional	string	`suggest` offers the default on each line; `always_ask` offers none, for a counterparty whose lines go to different accounts. Omit to keep. One of: `suggest`, `always_ask`
`classification_entity_id`optional	string	The entity whose bank lines the default above is for. Each entity keeps its own default, on its own chart. Omit for the group parent.
`metadata_patch`optional	object	Deep-merged into agent.metadata. Pass `{}` to leave unchanged. The default classification is set with the fields above, not here.

Example request

curl · example 1 of 2

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-agent" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agt_01HVF8T0M2YTAY3BBNRH0V0",
  "is_1099_recipient": true,
  "tax_id": "12-3456789"
}'

curl · example 2 of 2

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-agent" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agt_01HVF8T0M2YTAY3BBNRH0V0",
  "is_active": false
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

LedgerAgentResponse

Command-specific result payload

LedgerAgentResponse fields

Field Type Description

idrequired string

agent_typerequired string

namerequired string

legal_nameoptional string

tax_idoptional string

registration_numberoptional string

dunsoptional string

leioptional string

emailoptional string

phoneoptional string

addressoptional object

sourcerequired string

external_idoptional string

is_activerequired boolean

is_1099_recipientrequired boolean

classificationoptional

AgentClassification

The default account the group parent's bank lines are suggested.

AgentClassification fields

Field	Type	Description
`entity_id`required	string	The entity whose lines it is for.
`element_id`required	string	The default chart account.
`account_name`optional	string	The account's name.
`mode`required	string	`suggest`: offered on each new line. `always_ask`: never offered.
`confirmations`required	integer	Committed lines that went to this account.
`overrides`required	integer	Committed lines that went elsewhere while it was the default.
`set_by`optional	string	Who set or last moved it.
`set_at`optional	string	When it was set or last moved.
`learned_from`optional	string	The committed line it was learned from, when it was.

classificationsoptional

AgentClassification[]

The default account for each entity's bank lines, one per entity.

AgentClassification fields

Field	Type	Description
`entity_id`required	string	The entity whose lines it is for.
`element_id`required	string	The default chart account.
`account_name`optional	string	The account's name.
`mode`required	string	`suggest`: offered on each new line. `always_ask`: never offered.
`confirmations`required	integer	Committed lines that went to this account.
`overrides`required	integer	Committed lines that went elsewhere while it was the default.
`set_by`optional	string	Who set or last moved it.
`set_at`optional	string	When it was set or last moved.
`learned_from`optional	string	The committed line it was learned from, when it was.

created_atoptional string (date-time)

updated_atoptional string (date-time)

created_byoptional string

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error