Account Management API

Note:

The API uses the request header X-API-Key for authentication; refer to the Authentication for details.

Successful API requests will return HTTP status codes 2xx. For error solutions, see the Errors.

Create Account

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

Request Body (Data Type: application/json):

Feild	Description
companyName	[Required] Account company name. Visible to the user. Maximum length: 200 characters.
owner.email	[Required] 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. Note: 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.
creditLimit	[Optional] 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.
remark	[Optional] Account notes, visible only to you. Maximum length: 1024 characters.
externalId	[Optional] External account ID, which can be used to link with your system. Maximum length: 1024 characters.

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": "[e-mail]"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID"
}'

Response example:

{
  "id": "MANAGED-ACCOUNT-ID",
  "status": "pending",
  "companyName": "COMPANY-NAME",
  "owner": {
    "email": "[e-mail]",
    "status": "pending"
  },
  "creditLimit": 100,
  "remark": "Remark!",
  "externalId": "EXTERNAL-ID",
  "createTime": "2024-07-29T09:50:00.000Z"
}

The account statusenum 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": "[e-mail]",
    "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):

Feild	Description
creditLimit	[Optional] 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.
remark	[Optional] Account notes, visible only to you. Maximum length: 1024 characters.
status	[Optional] Account status. Enum values: disabled - Disable an account that is currently active. active - Re-enable an account that is currently disabled.

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:

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.