> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Users

> Covers the day-to-day management that follows user creation: querying a user's current transaction restrictions (whether withdrawals or card transactions are blocked, GET /account/v1/user-status), and acting as the navigation hub for every capability across the user lifecycle.

## 📄 Guide

In the DeCard-Managed model, the user (Account) is the identity baseline of the whole issuing stack: it carries the end user's `externalUserId`, compliance status and transaction restrictions, and every capability — card issuance, deposits and withdrawals, spending — is anchored to it. As a licensed issuer with its own BINs, DCS manages user transaction restrictions centrally on the risk and compliance side and exposes them to you through a standard endpoint you can query at any time.

This page is about **the day-to-day management that follows user creation**: reading a user's current transaction restrictions (withdrawals blocked / card transactions blocked), and serving as the navigation hub for the rest of the user lifecycle. To register a user, go to [Signing Up a Customer](../signing-up-a-customer/overview).

## User lifecycle at a glance

Capabilities for an end user, from registration through ongoing management, live on different pages. This page focuses on user status and transaction restrictions; for everything else, go to the page listed below.

| Stage                      | What you do                                                                          | Where to go                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Register a user            | Register with phone number + OTP, which generates `externalUserId`                   | [Signing Up a Customer › Overview](../signing-up-a-customer/overview)                                          |
| KYC and status             | KYC guidance page, status queries, state machine                                     | [Compliance › Overview](../../basic-concepts/compliance-kyc-flow)                                              |
| Travel Rule                | Submit or update compliance information such as source of funds and source of wealth | [Compliance › Travel Rule](../virtual-accounts/travel-rule)                                                    |
| Extended information / EDD | Update extended information, pre-upload files, upload EDD documents                  | [Integration Resources › H5 KYC / Card Application Guidance Page](../../integration-resources/h5-kyc-guidance) |
| Balances and assets        | Query available and frozen balances, credit and debit funds, review asset records    | [Managing Transactions › User Balance](../managing-transactions/user-balance)                                  |
| Account and asset model    | Dedicated accounts, the `free` / `freeze` / `total` concepts                         | [Basic Concepts › Ledgering](../../basic-concepts/ledgering-system)                                            |

## What we do

To keep financial operations on the platform compliant and secure, DCS applies transaction restrictions to users (for example, blocking withdrawals or card transactions) and provides a standard endpoint so you can read a user's current restriction status at any time. **The rules and trigger conditions behind these restrictions are managed by DCS risk and compliance**; the partner reads the outcome through this endpoint and guides the user accordingly in its own system.

## Query user status

Use the query endpoint to read a user's current transaction restrictions: whether withdrawals are blocked, and whether card transactions are blocked.

### Prerequisites

* You hold your Enterprise `ApiKey` / `SecretKey`. If you have not received them yet, see [First Steps](../../getting-started/first-steps).
* You have the target user's `externalUserId` (generated by DCS at registration).

### Endpoint

**`GET /account/v1/user-status`**

#### Query parameters

| Parameter        | In    | Type   | Required | Description                         |
| ---------------- | ----- | ------ | -------- | ----------------------------------- |
| `externalUserId` | query | string | ✓        | User ID (generated at registration) |

#### Request example

```
GET /account/v1/user-status?externalUserId=u_***** HTTP/1.1
Host: <api-base>
<!-- A GET request has no body, so no Content-Type header is needed -->
```

> For how to build the authentication headers, see [First Steps](../../getting-started/first-steps).

<Warning>
  The example uses the masked placeholder `u_*****` for `externalUserId`; replace it with a real user ID (never record real PII in documentation or logs).
</Warning>

#### Response example (200)

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "forbidWithdraw": false,
    "forbidCardTransaction": false
  }
}
```

#### `data` fields (user status / transaction restrictions)

| Field                   | Type    | Description                                                                             |
| ----------------------- | ------- | --------------------------------------------------------------------------------------- |
| `forbidWithdraw`        | boolean | Whether withdrawals are blocked for the user: `true` = blocked, `false` = allowed       |
| `forbidCardTransaction` | boolean | Whether card transactions are blocked for the user: `true` = blocked, `false` = allowed |

> **How to use this**: when `forbidWithdraw=true`, block or hide the withdrawal entry point in your own system; when `forbidCardTransaction=true`, tell the user that card transactions are currently restricted. The two flags are independent of each other.

### Common response envelope

Every `/account/` endpoint returns the same envelope; the business payload of this endpoint sits in `data`.

| Field           | Type           | Description                                                                                                                              |
| --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `code`          | string         | System-level return code; `SYS_SUCCESS` on success                                                                                       |
| `message`       | string         | Return message (for example, `success`)                                                                                                  |
| `messageDetail` | object \| null | Content intended for display to the end user (`title`/`message`/`type`/`icon`/`action`/`linkTitle`/`linkUrl`); usually `null` on success |
| `data`          | object         | Business payload; see the field table above                                                                                              |

> When integrating, use `code` (`SYS_SUCCESS`) to decide whether the call itself succeeded, and the fields inside `data` to decide the user's business status.

### Error handling

Every `/account/` endpoint uses the common response envelope. **Use the `code` field to decide whether the call succeeded**:

* `code` = `SYS_SUCCESS` → the call succeeded and the business payload is in `data`
* `code` ≠ `SYS_SUCCESS` → the call failed; read `message` and `messageDetail` (`title` / `message` / `type`, and so on) to understand why

#### Typical error scenarios

| HTTP status   | Typical cause                                                                         | Where to look                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `400`         | A request parameter is missing or malformed (for example, `externalUserId` is absent) | Check that all query parameters are present and that values match the expected format                                     |
| `401` / `403` | Authentication failed (invalid ApiKey, bad signature, expired secret)                 | Review how you build the authentication headers; see the [authentication guide](../../integration-resources/overview)     |
| `404`         | The user does not exist (`externalUserId` was never registered, or has been closed)   | Verify that `externalUserId` is correct and that the user has completed [registration](../signing-up-a-customer/overview) |
| `500`         | Server-side error                                                                     | Retry; if it persists, contact DCS technical support                                                                      |

<Warning>
  **Note**: the HTTP statuses above group typical scenarios only. The exact error code and the `messageDetail` content returned in production take precedence; do not hard-code checks against codes that are not listed here.
</Warning>

## Assets and balances

This page covers **user status and transaction restrictions** only. A user's funding account (available balance `free` / frozen balance `freeze` / total `total`, credits, debits, asset records) belongs to the balance domain and is not repeated here. Instead, go to:

* Full endpoint and field tables plus runnable examples: [Managing Transactions › User Balance](../managing-transactions/user-balance)
* The account and asset model (dedicated accounts, the `free` / `freeze` / `total` concepts): [Basic Concepts › Ledgering](../../basic-concepts/ledgering-system)

## Next steps

* Register a user: [Signing Up a Customer › Overview](../signing-up-a-customer/overview)
* Travel Rule: [Compliance › Travel Rule](../virtual-accounts/travel-rule)
* User balance: [Managing Transactions › User Balance](../managing-transactions/user-balance)
* Account and asset model: [Basic Concepts › Ledgering](../../basic-concepts/ledgering-system)