> ## Documentation Index
> Fetch the complete documentation index at: https://docs.command.cleargrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Account Status
> Update account statuses such as disputed or do-not-contact
This endpoint is used for updating account-level statuses, such as marking an account as **disputed** or flagging a customer as **do not contact**. Unlike the [Create & Update Account](/api-reference/accounts/create-update) endpoint which handles financial data, this endpoint specifically manages operational statuses that affect how accounts are handled within Command.
## Request
### Endpoint
```
POST {{base_url}}/lenders/{{lenderPublicId}}/accounts/update-status
```
| Environment | Base URL |
| -------------- | -------------------------------------------- |
| **Production** | `https://v3-api.cleargrid.ai/admin/v3` |
| **Staging** | `https://stage-v3-api.cleargrid.ai/admin/v3` |
### Headers
Bearer token obtained from the [Lender Login](/api-reference/authentication/lender-login) endpoint. Format: `Bearer `
### Body Parameters
An array of account status update objects.
The new status to apply to the account.
| Value | Status | Description |
| ----- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `5` | **Disputed** | Marks the specified account as disputed. The account will be flagged in Command and collection activity may be paused pending resolution. |
| `6` | **Do Not Contact** | Marks the specified customer as do-not-contact. All communication channels will be blocked for this customer across all their accounts. |
The unique identifier for the debtor/customer in your system.
The main account identifier to update.
## Example Request
```json theme={null}
{
"accounts": [
{
"status": 5,
"debtorCompanyId": "customer_001",
"accountId": "ORD-2025-001"
},
{
"status": 6,
"debtorCompanyId": "customer_002",
"accountId": "ORD-2025-045"
}
]
}
```
```bash cURL theme={null}
curl -X POST https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts/update-status \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"accounts": [
{
"status": 5,
"debtorCompanyId": "customer_001",
"accountId": "ORD-2025-001"
}
]
}'
```
```javascript JavaScript (fetch) theme={null}
const response = await fetch(
`https://v3-api.cleargrid.ai/admin/v3/lenders/${lenderPublicId}/accounts/update-status`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
accounts: [
{
status: 5,
debtorCompanyId: 'customer_001',
accountId: 'ORD-2025-001'
}
]
})
}
);
const data = await response.json();
console.log(data);
```
```python Python (requests) theme={null}
import requests
response = requests.post(
f"https://v3-api.cleargrid.ai/admin/v3/lenders/{lender_public_id}/accounts/update-status",
headers={
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
},
json={
"accounts": [
{
"status": 5,
"debtorCompanyId": "customer_001",
"accountId": "ORD-2025-001"
}
]
}
)
data = response.json()
print(data)
```
## Status Definitions
Marks the specified account as **disputed**. When an account is flagged as disputed:
* The account is visually flagged in Command's CRM interface
* Collection agents are alerted to the dispute status
* Depending on your organization's configuration, automated communications may be paused
* The dispute should be resolved before collection activities resume
Marks the specified customer as **do not contact**. This is a customer-level flag that:
* Blocks all outbound communication channels (WhatsApp, Email, SMS, Voice) for the customer
* Applies across all accounts belonging to this customer
* Overrides any automated communication workflows
* Remains in effect until explicitly removed
The **Do Not Contact** (status `6`) flag applies at the **customer level**, meaning it affects all accounts linked to that `debtorCompanyId`, not just the specified `accountId`. Use this status carefully, as it will halt all outbound communications across the customer's entire portfolio.
## Response
Status updates have been accepted and processing has started in the background.
```json theme={null}
{
"code": 200,
"message": "success",
"body": "Processing started successfully",
"errors": []
}
```
One or more accounts in the request failed validation.
```json theme={null}
{
"code": 400,
"message": null,
"body": "",
"errors": [
{
"accountId": "ORD-2025-001",
"errors": [
"Invalid status value. Accepted values: 5, 6"
]
}
]
}
```
```json theme={null}
{
"error": "Unauthorized"
}
```
The access token is missing, invalid, or expired. Re-authenticate using the [Lender Login](/api-reference/authentication/lender-login) or [Refresh Token](/api-reference/authentication/refresh-token) endpoint.
```json theme={null}
{
"error": "Something went wrong. Please try again later."
}
```
An unexpected server error occurred. If this persists, contact ClearGrid support.
## OpenAPI
````yaml /api-reference/openapi.json POST /admin/v3/lenders/{lenderPublicId}/accounts/update-status
openapi: 3.1.0
info:
title: Command API
description: >-
RESTful API for lenders to manage accounts and borrower data in the Command
platform.
version: 3.0.0
servers:
- url: https://v3-api.cleargrid.ai
description: Production
- url: https://stage-v3-api.cleargrid.ai
description: Staging
security: []
paths:
/admin/v3/lenders/{lenderPublicId}/accounts/update-status:
post:
tags:
- Lender Accounts
summary: Update account status
description: >-
Update account-level operational statuses such as marking an account as
disputed or flagging a customer as do-not-contact.
operationId: updateAccountStatus
parameters:
- in: path
name: lenderPublicId
required: true
schema:
type: string
description: Lender public ID (UUID) returned by the Lender Login endpoint.
example: 550e8400-e29b-41d4-a716-446655440000
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- accounts
properties:
accounts:
type: array
description: Array of account status update objects.
items:
type: object
required:
- accountId
- status
- debtorCompanyId
properties:
accountId:
type: string
example: ORD-2025-001
description: The main account identifier to update.
status:
type: integer
enum:
- 5
- 6
example: 5
description: 5 = Disputed, 6 = Do Not Contact
debtorCompanyId:
type: string
example: customer_001
description: >-
The unique identifier for the debtor/customer in your
system.
example:
accounts:
- status: 5
debtorCompanyId: customer_001
accountId: ORD-2025-001
- status: 6
debtorCompanyId: customer_002
accountId: ORD-2025-045
responses:
'200':
description: Processing started successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StandardError'
example:
code: 200
message: success
body: Processing started successfully
errors: []
'400':
description: Bad request — validation error
content:
application/json:
schema:
$ref: '#/components/schemas/StandardError'
example:
code: 400
message: null
body: ''
errors:
- accountId: ORD-2025-001
errors:
- 'Invalid status value. Accepted values: 5, 6'
'401':
description: Unauthorized — missing, invalid, or expired token
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: Unauthorized
security:
- bearerAuth: []
components:
schemas:
StandardError:
type: object
properties:
code:
type: integer
message:
type: string
nullable: true
body:
type: string
errors:
type: array
items:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````