Client APIs

Accessible by client_credentials grant. Usually accessed by other microservices in your system.

Access Provisioning

Add or remove scopes in user profiles.

Authentication

Requires client authentication.

Scope

client:profile:access:write

Before You Start

URL

POST /user/client-api/access

Request Body

Parameter	Type	Description	Required / Optional
targets	array	Array of user IDs.	Required
targetType	enum(`user`, `client`)	Type of target.	Required
scope	array	Array of scope names. See full list here	Required
operation	enum(`set`, `add`, `del`)	Specifies the type of modification.	Required

Request Sample (JSON)

{
  "targets": ["507f1f77bcf86cd799439011"],
  "targetType": "user",
  "scope": ["admin:profile:read", "admin:profile:write"],
  "operation": "set"
}

Response Parameters

Parameter	Type	Description
ok	integer	0 or 1

Response Sample

{
  "ok": 1
}

Create Users

Creates users using a given array of user details.

Authentication

Requires client authentication.

Scope

client:profile:create:write

URL

POST /user/client-api/create

Request Body

Parameter	Type	Description	Required / Optional
username	string	Username for the user. Contains text, numbers and _ and at least 8 letters	Required
firstName	string	First name of the user.	Required
lastName	string	Last name of the user.	Required
email	string	Email address of the user.	Required
password	string	Password for the user.	Required
role	string	Role of the user. Target role be ranked less than the user calling the API or must be a super admin.	Optional
phoneCountryCode	string	Valid country code.	Optional
phone	string	Phone number of the user.	Optional

Request Sample (JSON)

[
  {
    "username": "john_doe",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user",
    "phoneCountryCode": "+00",
    "phone": "0000000000",
    "email": "user@example.com",
    "password": "$uper&ecurePassw0rd"
  }
]

Response Parameters

Parameter	Type	Description
ok	integer	0 or 1
insertedCount	integer	Number of users created.

Response Sample

{
  "ok": 1,
  "insertedCount": 1
}

List Users

List users in the system.

Authentication

Requires client authentication.

Scope

client:profile:read

URL

GET /user/client-api/list

Query Parameters

Parameter	Type	Description	Required / Optional
limit	integer	Records per page	Optional
offset	integer	`_id` field of last record in the previous page.	Optional

Response Data Parameters

Parameter	Type	Description
users	array	Array of users.

Response Sample

{
  "ok": 1,
  "data": {
    "users": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "middleName": null,
        "lastName": "Doe",
        "gender": "male",
        "username": "john_doe",
        "role": "user",
        "bio": "Grab a straw, because you suck.",
        "designation": "Software Engineer",
        "profilePictureUrl": "https://image.com/url",
        "pronouns": "he/him",
        "verified": true,
        "verifiedDate": "2023-09-09T13:45:52.505Z",
        "customLink": "https://custom.link",
        "followingCount": 250,
        "followerCount": 1058,
        "isPrivate": true,
        "isSubscribed": true,
        "subscriptionTier": "basic",
        "subscriptionExpiry": "2023-09-09T13:45:52.505Z",
        "isBanned": false,
        "isRestricted": false,
        "email": "john.doe@example.com",
        "phone": "0000000000",
        "customData": {}
      }
    ]
  }
}

Get User Info

Get information about a user from their ID.

Authentication

Requires client authentication.

Scope

client:profile:read

URL

GET /user/client-api/user-info

Query Parameters

Parameter	Type	Description	Required / Optional
targets	string	Comma separated list of user IDs	Required

Response Data Parameters

Parameter	Type	Description
users	array	Array of users.

Response Sample

{
  "ok": 1,
  "data": {
    "users": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "firstName": "John",
        "middleName": null,
        "lastName": "Doe",
        "gender": "male",
        "username": "john_doe",
        "role": "user",
        "bio": "Grab a straw, because you suck.",
        "designation": "Software Engineer",
        "profilePictureUrl": "https://image.com/url",
        "pronouns": "he/him",
        "verified": true,
        "verifiedDate": "2023-09-09T13:45:52.505Z",
        "customLink": "https://custom.link",
        "followingCount": 250,
        "followerCount": 1058,
        "isPrivate": true,
        "isSubscribed": true,
        "subscriptionTier": "basic",
        "subscriptionExpiry": "2023-09-09T13:45:52.505Z",
        "isBanned": false,
        "isRestricted": false,
        "email": "john.doe@example.com",
        "phone": "0000000000",
        "customData": {}
      }
    ]
  }
}

Update User Custom Data

Updates a user's custom data.

Authentication

Requires delegated authentication.

Scope

admin:profile:custom-data:write

Before You Start

Read about custom data here

URL

PUT /user/admin-api/custom-data

Request Body

Parameter	Type	Description	Required / Optional
target	string	`_id` of the user.	Required
customData	object	JSON data object	Required

Request Sample (JSON)

{
  "target": "507f1f77bcf86cd799439011",
  "customData": {
    "themePreference": "dark",
    "nestedKey": {
      "integer": 1
    }
  }
}

Response Parameters

Parameter	Type	Description
ok	integer	0 or 1

Response Sample

{
  "ok": 1
}

Ban User

Suspend a user from logging into Liquid.

Authentication

Requires client authentication.

Scope

client:profile:ban:write

URL

POST /user/client-api/ban

Response Data Parameters

Parameter	Type	Description
target	array	`_id` of the user to be banned or unbanned.
state	boolean	Ban status.

Request Sample

{
  "target": "507f1f77bcf86cd799439011",
  "state": true
}

Response Sample

{
  "ok": 1
}

Restrict User

Marks a user as restricted.

Authentication

Requires client authentication.

Scope

client:profile:restrict:write

URL

POST /user/client-api/restrict

Response Data Parameters

Parameter	Type	Description
target	array	`_id` of the user to be restricted or unrestricted.
state	boolean	Ban status.

Request Sample

{
  "target": "507f1f77bcf86cd799439011",
  "state": true
}

Response Sample

{
  "ok": 1
}

Update User Credits

Update credits of a user. Credits are usually similar to virtual money that you can use for controlling paid features. You can also use this as a reward points system.

Authentication

Requires client authentication.

Scope

client:profile:credits:write

Special Instructions

Adjust the number of credits that a user has while signing up using the option user.account-creation.initial-credit-count.

URL

POST /user/client-api/credits

Response Data Parameters

Parameter	Type	Description
target	array	`_id` of the user to be verified or unverified.
operation	enum(`increment`, `decrement`, `set`)	Operation to be performed on the credit value.

Request Sample

{
  "target": "6291396efe7079829e49b723",
  "operation": "increment",
  "value": 50
}

Response Sample

{
  "ok": 1
}

Read Block Status

Check if a given source user has blocked the target user.

Authentication

Requires client authentication.

Scope

client:social:block:read

URL

GET /user/client-api/block-status

Query Parameters

Parameter	Type	Description
source	string	`_id` of the source user.
target	string	`_id` of the target user.

Response Data Parameters

Parameter	Type	Description
blocked	boolean	Specifies if the source user blocked the target user.

Response Sample

{
  "data": {
    "blocked": true
  }
}

Read Follow Status

Check if a given source user is following the target user.

Authentication

Requires client authentication.

Scope

client:social:follow:read

URL

GET /user/client-api/follow-status

Query Parameters

Parameter	Type	Description
source	string	`_id` of the source user.
target	string	`_id` of the target user.

Response Data Parameters

Parameter	Type	Description
following	boolean	Specifies if the source user is following the target user.

Response Sample

{
  "data": {
    "following": true
  }
}

User Followers

Get followers of a user.

Authentication

Requires client authentication.

Scope

client:social:follow:read

URL

GET /user/client-api/followers

Query Parameters

Parameter	Type	Description	Required / Optional
target	integer	`_id` of the user.	Optional
limit	integer	Records per page.	Optional
offset	integer	`_id` field of last record in the previous page.	Optional

Response Data Parameters

Parameter	Type	Description
records	array	Array of follower records.

Response Sample

{
  "ok": 1,
  "data": {
    "records": [
      {
        "_id": "507f191e810c19729de860ea",
        "approved": true,
        "source": {
          "_id": "507f1f77bcf86cd799439011",
          "firstName": "Rick",
          "middleName": null,
          "lastName": "Asthley",
          "gender": "male",
          "username": "rick_asthley",
          "role": "user",
          "bio": "Grab a straw, because you suck.",
          "designation": "Software Engineer",
          "profilePictureUrl": "https://image.com/url",
          "pronouns": "he/him",
          "verified": true,
          "verifiedDate": "2023-09-09T13:45:52.505Z",
          "customLink": "https://custom.link",
          "followingCount": 250,
          "followerCount": 1058,
          "isPrivate": true,
          "isSubscribed": true,
          "subscriptionTier": "basic",
          "subscriptionExpiry": "2023-09-09T13:45:52.505Z",
          "isBanned": false,
          "isRestricted": false,
          "email": "rick_asthley@example.com",
          "phone": "0000000000"
        }
      }
    ]
  }
}

User Following

Get the list of users that a user is following.

Authentication

Requires client authentication.

Scope

client:social:follow:read

URL

GET /user/client-api/following

Query Parameters

Parameter	Type	Description	Required / Optional
target	integer	`_id` of the user.	Optional
limit	integer	Records per page.	Optional
offset	integer	`_id` field of last record in the previous page.	Optional

Response Data Parameters

Parameter	Type	Description
records	array	Array of users.

Response Sample

{
  "ok": 1,
  "data": {
    "records": [
      {
        "_id": "507f191e810c19729de860ea",
        "approved": true,
        "target": {
          "_id": "507f1f77bcf86cd799439011",
          "firstName": "Rick",
          "middleName": null,
          "lastName": "Asthley",
          "gender": "male",
          "username": "rick_asthley",
          "role": "user",
          "bio": "Grab a straw, because you suck.",
          "designation": "Software Engineer",
          "profilePictureUrl": "https://image.com/url",
          "pronouns": "he/him",
          "verified": true,
          "verifiedDate": "2023-09-09T13:45:52.505Z",
          "customLink": "https://custom.link",
          "followingCount": 250,
          "followerCount": 1058,
          "isPrivate": true,
          "isSubscribed": true,
          "subscriptionTier": "basic",
          "subscriptionExpiry": "2023-09-09T13:45:52.505Z",
          "isBanned": false,
          "isRestricted": false,
          "email": "rick_asthley@example.com",
          "phone": "0000000000"
        }
      }
    ]
  }
}

Get Invite Codes

Retrieves invite codes for a user.

Authentication

Requires a client authentication

Scope

client:social:invite-code:read

URL

GET /user/client-api/invite-codes

Before You Start

Read more about the Invite-Only system here.

Request Parameters

Parameter	Type	Description
target	array	Array of invite codes. Absence of `targetId` parameter in objects means the invite code is not used.

Response Sample

{
  "ok": 1,
  "data": {
    "inviteCodes": [
      {
        "code": "GU-2526-1687389089010",
        "createdAt": "2023-06-21T16:31:29.012Z",
        "updatedAt": "2023-09-06T15:07:42.794Z",
        "targetId": "64f895bec011931326757de6"
      },
      {
        "code": "IE-2949-1687895089010",
        "createdAt": "2023-06-21T16:31:29.012Z",
        "updatedAt": "2023-06-21T16:31:29.012Z"
      },
      {
        "code": "RN-9486-1687365089009",
        "createdAt": "2023-06-21T16:31:29.012Z",
        "updatedAt": "2023-06-22T16:48:48.622Z"
      },
      {
        "code": "AX-4751-1687286989010",
        "createdAt": "2023-06-21T16:31:29.012Z",
        "updatedAt": "2023-06-21T16:31:29.012Z"
      },
      {
        "code": "PJ-5631-1689673089010",
        "createdAt": "2023-06-21T16:31:29.012Z",
        "updatedAt": "2023-06-21T16:31:29.012Z"
      }
    ]
  }
}

Access Provisioning​

Authentication​

Scope​

Before You Start​

URL​

Request Body​

Request Sample (JSON)​

Response Parameters​

Response Sample​

Create Users​

Authentication​

Scope​

URL​

Request Body​

Request Sample (JSON)​

Response Parameters​

Response Sample​

List Users​

Authentication​

Scope​

URL​

Query Parameters​

Response Data Parameters​

Response Sample​

Get User Info​

Authentication​

Scope​

URL​

Query Parameters​

Response Data Parameters​

Response Sample​

Update User Custom Data​

Authentication​

Scope​

Before You Start​

URL​

Request Body​

Request Sample (JSON)​

Response Parameters​

Response Sample​

Ban User​

Authentication​

Scope​

URL​

Response Data Parameters​

Request Sample​

Response Sample​

Restrict User​

Authentication​

Scope​

URL​

Response Data Parameters​

Request Sample​

Response Sample​

Update User Credits​

Authentication​

Scope​

Special Instructions​

URL​

Response Data Parameters​

Request Sample​

Response Sample​

Read Block Status​

Authentication​

Scope​

URL​

Query Parameters​

Response Data Parameters​

Response Sample​

Read Follow Status​

Authentication​

Scope​

URL​

Query Parameters​

Response Data Parameters​

Response Sample​

User Followers​

Authentication​

Scope​

URL​

Access Provisioning

Authentication

Scope

Before You Start

URL

Request Body

Request Sample (JSON)

Response Parameters

Response Sample

Create Users

Authentication

Scope

URL

Request Body

Request Sample (JSON)

Response Parameters

Response Sample

List Users

Authentication

Scope

URL

Query Parameters

Response Data Parameters

Response Sample

Get User Info

Authentication

Scope

URL

Query Parameters

Response Data Parameters

Response Sample

Update User Custom Data

Authentication

Scope

Before You Start

URL

Request Body

Request Sample (JSON)

Response Parameters

Response Sample

Ban User

Authentication

Scope

URL

Response Data Parameters

Request Sample

Response Sample

Restrict User

Authentication

Scope

URL

Response Data Parameters

Request Sample

Response Sample

Update User Credits

Authentication

Scope

Special Instructions

URL

Response Data Parameters

Request Sample

Response Sample

Read Block Status

Authentication

Scope

URL

Query Parameters

Response Data Parameters

Response Sample

Read Follow Status

Authentication

Scope

URL

Query Parameters

Response Data Parameters

Response Sample

User Followers

Authentication

Scope

URL