# Account Management API

**Note:**

The API uses the request header `X-API-Key` for authentication; refer to the [Authentication](https://docs.ycloud.com/reference/authentication) for details.

Successful API requests will return HTTP status codes `2xx`. For error solutions, see the [Errors](https://docs.ycloud.com/reference/errors).

## Create Account

**Request:** `POST https://api.ycloud.com/v2/partner/managedAccounts`

Request Body (Data Type: `application/json`):

<table><thead><tr><th width="162">Feild</th><th>Description</th></tr></thead><tbody><tr><td><code>companyName</code></td><td><strong>[Required]</strong> Account company name. Visible to the user. Maximum length: 200 characters.</td></tr><tr><td><code>owner.email</code></td><td><p><strong>[Required]</strong> User email address. You must assign an owner to the newly created account. If the email is not registered, an invitation email will be sent automatically. If the email is already registered, it will automatically be set as the owner of the new account.</p><p><strong>Note:</strong> An account refers to a workspace, while a user represents a real person. An account can be managed by multiple users, and a user can own multiple accounts.</p></td></tr><tr><td><code>creditLimit</code></td><td><strong>[Optional]</strong> Credit limit, with a range of 0-1,000,000 USD. This defines the amount the account can spend each month. The spending limit resets on the 1st of each month based on the UTC+8 time zone.</td></tr><tr><td><code>remark</code></td><td><strong>[Optional]</strong> Account notes, visible only to you. Maximum length: 1024 characters.</td></tr><tr><td><code>externalId</code></td><td><strong>[Optional]</strong> External account ID, which can be used to link with your system. Maximum length: 1024 characters.</td></tr></tbody></table>

Request example:

```
curl 'http://api.ycloud.com/v2/partner/managedAccounts' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "your@example.com"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID"
}'
```

Response example:

```
{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "pending",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "your@example.com",
    "status": "pending"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID",
  "createTime": "2024-07-29T09:50:00.000Z"
}
```

The account `status`enum values are:

* `pending` - The user is awaiting to accept the invitation to become the owner of the account.
* `active` - The user has accepted the invitation and is now the owner of the account.
* `disabled` - The account has been disabled.

**Note:** When the `owner.email` field points to an already registered user, the account status automatically changes to `active`.

User status (`owner.status`) enum values are:

* `pending` - User is pending registration.
* `active` - User is registered.

## Acquire Account

**Function Description:** Retrieve basic account information, including owner details and the credit limit usage for the current month.

**Request:** `GET https://api.ycloud.com/v2/partner/managedAccounts/{accountId}`

Request example:

```
curl 'http://api.ycloud.com/v2/partner/managedAccounts/MANAGED-ACCOUNT-ID' \
-H 'X-API-Key: YOUR_API_KEY'
```

Response example:

```
{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "active",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "your@example.com",
    "status": "active",
    "firstName": "FISRT-NAME",
    "lastName": "LAST-NAME"
  },
  "creditLimit": 100,
  "creditUsage": {
    "consumedBalance": 10,
    "frozenBalance": 20,
    "availableBalance": 70
  },
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID",
  "createTime": "2024-07-29T09:50:00.000Z"
}
```

In this context:

* `creditUsage.consumedBalance` represents the amount spent and billed for the current month.
* `creditUsage.frozenBalance` indicates the frozen balance for the current month (usually a portion of the credit is frozen when WhatsApp messages are sent but not yet delivered).
* `availableBalance` represents the actual available credit for the current month, calculated as:

  ```
  availableBalance = creditLimit - consumedBalance - frozenBalance
  ```

## Update Account

**Function Description:** Update basic account information, or disable or enable the account.

**Request:** `PATCH https://api.ycloud.com/v2/partner/managedAccounts/{accountId}`

Request Body (Data Type: `application/json`):

<table><thead><tr><th width="164">Feild</th><th>Description</th></tr></thead><tbody><tr><td><code>creditLimit</code></td><td><strong>[Optional]</strong> Credit limit, with a range of 0-1,000,000 USD. This defines the amount the account can spend each month. The spending limit resets on the 1st of each month based on the UTC+8 time zone.</td></tr><tr><td><code>remark</code></td><td><strong>[Optional]</strong> Account notes, visible only to you. Maximum length: 1024 characters.</td></tr><tr><td><code>status</code></td><td><p></p><p><strong>[Optional]</strong> Account status. Enum values:</p><ul><li><code>disabled</code> - Disable an account that is currently <code>active</code>.</li><li><code>active</code> - Re-enable an account that is currently <code>disabled</code>.</li></ul></td></tr></tbody></table>

Request example:

```
curl -X PATCH 'http://api.ycloud.com/v2/partner/managedAccounts/MANAGED-ACCOUNT-ID
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
  "remark": "reMark",
  "creditLimit": 150,
  "status": "active"
}'
```

## Send Invitation Email

**Function Description:** After creating an account, an invitation email is automatically sent. If the user did not receive it, this API can be called to resend the invitation.

**Request:** `POST https://api.ycloud.com/v2/partner/managedAccounts/{accountId}/sendInvitation`

Request Example:

```bash
curl -X POST 'http://api.ycloud.com/v2/partner/managedAccounts/MANAGED-ACCOUNT-ID/sendInvitation' \
-H 'X-API-Key: YOUR_API_KEY'
```

A response with HTTP status code 200 indicates success.