Introduction

We are listing the available API endpoints for habitate.io. These can be used to build additional feature and create linked services around your community.

In case you need more help you can get in touch with the team, developer-support at habitate.io

Authentication

Your application can use basic auth for APIs(Application Programming Interface) to authenticate access to our services using an unique api key. Your API key can be changed at any time. You can find your api key in your profile page.

Options

Key Description
username The source system that calls this api e.g. backend_app1.
This is useful for debugging/audit purposes.
password Your api key.

Note: Incorrect api key will give 403 Forbidden response.

Common Info

Below are some options that are applicable to all APIs endpoints unless mentioned otherwise.

Base Url

The base url will be your habitate url (e.g. community.habitate.io). If you have configured custom domain then you can also use the same as your base url.

Header Options

Key Description
Content-Type Use application/json
Authorization If using basic auth then it will be similar to Basic <credentials>
User-Agent Using a proper user agent string can help for audit/debugging purposes.

Any endpoints that provide a list of resources will have the paging options as mentioned below.

Paging Options

Query parameters default comments
page 1 page number, starts at 1
page_size 10 number of items returned per page(pp), max input value is 50.
Note: This is the maximum number of items you can get in the response list. At times the response list size can be less than this limit. You will have to check the has_more http header if the there are more items to query.
Http Header Response comments
has_more possible values are “1” or “0”. 1 indicates that there might be more items in next page, 0 indicates otherwise.

Misc information

For most of the responses, the json payload return will only return fields that are not null. If a key in the json response is not present when you query the endpoint you will have to assume it is null.
There is also another case where some fields are skipped from the response json, this happens only if you don’t have enough permissions to view the data.

Default entity statuses

Value comments
15 ACTIVE
4 APPROVAL_REQUIRED
3 APPROVAL_REJECTED
2 DRAFT
0 INACTIVE
-2 REPORTED
-3 SPAM
-100 DELETED

Reference Type List/Entity List

possible types
POST
COMMENT
REPLY
USER

Boards

Create a Board

Endpoint

POST /api/v1/boards

Body parameters

Name Type Req? Comments
board_name string Y  
about string N The details/description of the board
is_private boolean Y Private boards are restricted to users who are part of the board
hidden_type integer Y Should the board be visible to guests?
permission_for integer Y Who can post in this board?
needs_approval boolean Y Does user need approval to post in board?
icon String N The board icon displayed in the ui.

Options for ‘hidden_type’

Possible values Comments
0 Visible to all users.
1 Visible to any members who is logged in.
2 Not visible unless user is part of the board.

Options for ‘permission_for’

Possible values Comments
1 Only admins can post
5 Admins and moderators can post.
10 Any member of the community can post in the board.

Note: ‘permission_for’ parameter will change soon so that you can pass a list of role ids.

Response parameters

{
  "board_id": 0,
  "display_order": 0,
  "board_name": "string",
  "board_type": "string",
  "is_private": true,
  "hidden_type": 0,
  "permission_for": 0,
  "needs_approval": true,
  "pinned_posts": [
    0
  ],
  "post_count": 0,
  "last_posted_at": "2022-02-22T22:22:22.222Z",
  "icon": "string",
  "about": "string"
}

Edit a Board

Endpoint

PUT /api/v1/boards/{board_id}

Url path variables

Possible values Comments
board_id The id of the board to be edited.

Body parameters

Refer to create board

Response parameters

Refer create board

Get Board details

Endpoint

GET /api/v1/boards/{board_id}

Url path variables

Possible values Comments
board_id The id of the board to be viewed.

Response parameters

Refer create board

Get all Boards

Endpoint

GET /api/v1/boards

Response parameters

[
  {
  "board_id": 0,
  "display_order": 0,
  "board_name": "string",
  "board_type": "string",
  "is_private": true,
  "hidden_type": 0,
  "permission_for": 0,
  "needs_approval": true,
  "pinned_posts": [
    0
  ],
  "post_count": 0,
  "last_posted_at": "2022-02-22T22:20:22.222Z",
  "icon": "string",
  "about": "string"
  },
  {
    "board_id": 1,
    "display_order": 1,
    "board_name": "string",
    "board_type": "string",
    "is_private": true,
    "hidden_type": 0,
    "permission_for": 0,
    "needs_approval": true,
    "pinned_posts": [
      0
    ],
    "post_count": 0,
    "last_posted_at": "2022-02-22T22:22:22.222Z",
    "icon": "string",
    "about": "string"
  }
]

Change display order

Endpoint

PATCH /api/v1/boards/reorder

Body parameters

Name Type Req? Comments
display_order Map Y Map of board Id associated with the display order starting at 1.

sample payload

{
  "display_order": {
    "1": 2,
    "2": 1,
    "3": 3
  }
}

Response parameters

{
  "message": "OK"
}

Modify private board members

Endpoint

PUT /api/v1/boards/{board_id}/members

Url path variables

Possible values Comments
board_id The id of the board.

Body parameters

Name Type Req? Comments
member_changes Map Y Map of user key as MSID with value as boolean. true to provide access to user, false to remove access to the board.

sample payload

{
  "member_changes": {
    "101.N8vf3FFtbXIhQMAkCve320FaG": true,
    "555.37AInaiO4R5UiGnuuNwjP07sw": true,
    "222.NHJSm4JzQWsLYIIuJmGTK2moL": false
  }
}

Response parameters

{
  "message": "OK"
}
Additional Notes

You should also be adding admins to private boards if they want to have the same experience as a member.

Users

Details about self

Endpoint

GET /api/v1/users/me

Response parameters

{
  "user_id": 200,
  "username": "string",
  "user_avatar": "string",
  "first_name": "string",
  "last_name": "string",
  "middle_name": "string",
  "sid": "string",
  "role_id": 0,
  "is_bot": true,
  "user_status": "string",
  "email": "string",
  "msid": "string",
  "created_at": "2022-03-23T05:23:19.845Z",
  "last_modified_at": "2022-03-23T05:23:19.845Z"
}

Options for ‘user_status’

Possible values ENUM Comments
0 INACTIVE  
4 WAITLIST User is has joined your wait-list
5 INVITED  
6 UNVERIFIED  
10 ACTIVE  
-3 BANNED  
-100 DELETED  


Additional Notes

Some endpoint params might need msid value of the user. This value can be constructed from the user details. The format is user_id.sid
Example: if user_id is 500 and sid is MN88KMZ6KxvEAqOsrp26G then the value of msid is 500.MN88KMZ6KxvEAqOsrp26G

Create a user

Endpoint

POST /api/v1/users

Body parameters

Name Type Req? Comments
first_name string Y  
middle_name string N  
last_name boolean N  
username integer N case-insensitive value. Can not have spaces or special characters.
email integer Y  
sso_id boolean N If using sso then make sure to provide this value else there is a possibility of duplicate account creation.
user_avatar string N  
lang string N Default is en. Please follow this format
timezone string N Default is UTC. Supported list


Additional Notes

Make sure the email is verified before creating the user.
New Language support will be added based on requests.

Please validate your use case before creating users via api as this is only reserved for certain cases.

Response parameters

Response parameters

{
  "user_id": 200,
  "username": "string",
  "user_avatar": "string",
  "first_name": "string",
  "last_name": "string",
  "middle_name": "string",
  "sid": "string",
  "role_id": 0,
  "is_bot": true,
  "user_status": "string",
  "email": "string",
  "msid": "string",
  "created_at": "2022-03-23T05:23:19.845Z",
  "last_modified_at": "2022-03-23T05:23:19.845Z"
}

Update user details

Endpoint

PUT /api/v1/users/{msid}

Url path variables

Possible values Comments
msid The msid value of the user to be edited.

Body parameters

Name Type Req? Comments
first_name string Y  
middle_name string N  
last_name boolean N  
username integer N case-insensitive value. Can not have spaces or special characters except _.
user_avatar string N Url value
lang string N Default is en. Please follow this format
timezone string N Default is UTC. Supported list
user_description String N Can accept HTML.
banner String N Url of the user banner image.
social_media_links object N  
key type Req? Comments
Twitter url N Link to your twitter profile
Linkedin url N Your LinkedIn profile url.

Response parameters

{
  "user_id": 177,
  "sid": "TwM0e5z2gGE7VyDcY5c6ZeObphM",
  "msid": "177.TwM0e5z2gGE7VyDcY5c6ZeObphM",
  "username": "Maryam5",
  "user_avatar": "http://placeimg.com/640/480/nature",
  "first_name": "Ayana",
  "role_id": 2,
  "is_bot": false,
  "user_status": 10,
  "created_at": "2022-04-05T01:15:57Z",
  "user_description": "",
  "meta": {},
  "login_count": 0,
  "post_count": 0,
  "comment_count": 0,
  "reply_count": 0
}

Get user details

Endpoint

GET /api/v1/users/{msid}

Url path variables

Possible values Comments
msid The msid value of the user. user_id can also be used if the LIST permission is granted. 
{
    "user_id": 177,
    "sid": "TwM0e5z2gGE7VyDcY5c6ZeObphM",
    "msid": "177.TwM0e5z2gGE7VyDcY5c6ZeObphM",
    "username": "Joshuah_Frami",
    "user_avatar": "http://placeimg.com/640/480/nature",
    "first_name": "Dovie",
    "email": "Josiane.Baumbach@example.com",
    "role_id": 2,
    "is_bot": false,
    "user_status": 10,
    "created_at": "2022-04-05T01:15:57Z",
    "user_description": "",
    "meta": {},
    "login_count": 0,
    "post_count": 0,
    "comment_count": 0,
    "reply_count": 0
}

Understanding user_status values

Value comments
10 ACTIVE
6 UNVERIFIED
5 INVITED
4 WAITLIST
0 INACTIVE
-3 BANNED
-100 DELETED

Get user list

Endpoint

GET /api/v1/users/{msid}

Query param options

For common paging options refer this

Query parameters default comments
sort_by user_id available options are user_id, joined, name.
order desc possible values asc or desc
status 10 To filter records by status, default is Active records. Other status options

Note: Listing records is a slow operation, make sure your code can handle it appropriately.

Response parameters

[
  {
    "user_id": 177,
    "sid": "TwM0e5z2gGE7VyDcY5c6ZeObphM",
    "msid": "177.TwM0e5z2gGE7VyDcY5c6ZeObphM",
    "username": "Joshuah_Frami",
    "user_avatar": "http://placeimg.com/640/480/nature",
    "first_name": "Dovie",
    "role_id": 2,
    "user_status": 10,
    "created_at": "2022-04-05T01:15:57Z"
  },
  {
    "user_id": 176,
    "sid": "Dm0f0T0syODtqfQ0HP4Tp1TX8VD",
    "msid": "176.Dm0f0T0syODtqfQ0HP4Tp1TX8VD",
    "username": "Esperanza",
    "user_avatar": "http://placeimg.com/640/480/nature",
    "first_name": "Esperanza",
    "role_id": 4,
    "user_status": 10,
    "created_at": "2022-04-05T01:15:53Z"
  }
]

Patch user details

Endpoint

PATCH /api/v1/users/{msid}

Url path variables

Possible values Comments
msid The msid value of the user to be edited.

Body parameters

Name Type Req? Comments
action int Y  
data object Y  
details string N  

‘action’ options

options Comments
101 for update::role

‘data’ parameters

Name Type Req? Comments
role_id int N The role id of the role you want to change to. You can get the role from roles api.

Roles

Get list of roles

Endpoint

GET /api/v1/roles

Response parameters

[
  {
    "role_id": 3,
    "role_name": "Moderator",
    "role_details": "Moderator role has additional permissions compared to members, to keep discussions organized",
    "is_default": true
  },
  {
    "role_id": 4,
    "role_name": "Member",
    "role_details": "Member role with default permissions",
    "is_default": true
  }
]

Posts

Get a post

Endpoint

GET /api/v1/posts/{post_id}

Url path variables

Possible values Comments
post_id The post_id to be viewed.


Additional Notes

The checks and conditional on who can post in what board, will be evaluated against the API user rather than the author of the post.

Response parameters

{
  "post_id": 163,
  "board_id": 1,
  "headline": "Upgradable secondary concept Mouse",
  "post_short_text": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt",
  "content": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt aut ut ab recusandae facilis reprehenderit. Et qui et debitis itaque odit. Cum animi qui qui sunt. Fish",
  "clean_text": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt aut ut ab recusandae facilis reprehenderit. Et qui et debitis itaque odit. Cum animi qui qui sunt. Fish",
  "post_status": 15,
  "comment_count": 0,
  "reply_count": 0,
  "react_count": 1,
  "reactions": {
    "s2": 1
  },
  "view_count": 1,
  "last_edited_at": "2022-04-21T12:49:20.356592Z",
  "created_at": "2022-04-21T12:49:20.095Z",
  "last_modified_at": "2022-04-21T12:48:41Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

user and other user info corresponds to the primary author of the post.

Understanding post_status values

Refer to this section

Understanding reactions object

The object has keys which represents the slots, i.e. the first emoji reaction is considered as slot 1 and the corresponding key is s1. The value of these keys represent the reaction count for the respective emoji(consider here a slot). The reason for considering the emoji reaction as slots is because the icons shown on the ui are configurable.

  "reactions": {
    "s2": 1,
    "s3": 2,
    "s4": 300
  }

Create a post

Endpoint

POST /api/v1/posts

Body parameters

Name Type Req? Comments
board_id string Y  
headline string Y  
content boolean Y  
authors List Y list of msid of authors. currently only the first item in the list is used to assign an author to the post


Additional Notes

The checks and conditional on who can post in what board will be evaluated against the API user rather than the author of the post.

Response parameters

{
  "post_id": 163,
  "board_id": 1,
  "headline": "Upgradable secondary concept Mouse",
  "post_short_text": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt",
  "content": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt aut ut ab recusandae facilis reprehenderit. Et qui et debitis itaque odit. Cum animi qui qui sunt. Fish",
  "clean_text": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt aut ut ab recusandae facilis reprehenderit. Et qui et debitis itaque odit. Cum animi qui qui sunt. Fish",
  "post_status": 15,
  "comment_count": 0,
  "reply_count": 0,
  "react_count": 0,
  "view_count": 0,
  "created_at": "2022-05-08T09:30:57.205862Z",
  "last_modified_at": "2022-05-08T09:30:57.205864Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Understanding post_status values

refer to this section

Edit a post

Endpoint

PUT /api/v1/posts/{post_id}

Url path variables

Possible values Comments
post_id The post_id to be edited.

Body parameters

Name Type Req? Comments
board_id string Y  
headline string Y  
content boolean Y  
authors List Y list of msid of authors. currently only the first item in the list is used to assign an author to the post


Additional Notes

The checks and conditional on who can post in what board, will be evaluated against the API user rather than the author of the post.

Response parameters

{
  "post_id": 163,
  "board_id": 1,
  "headline": "Upgradable secondary concept Mouse",
  "post_short_text": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt",
  "content": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt aut ut ab recusandae facilis reprehenderit. Et qui et debitis itaque odit. Cum animi qui qui sunt. Fish",
  "clean_text": "Delectus aut deserunt in aliquid. Dolorem totam suscipit ab. Veniam saepe sit. Animi totam inventore deserunt aut ut ab recusandae facilis reprehenderit. Et qui et debitis itaque odit. Cum animi qui qui sunt. Fish",
  "post_status": 15,
  "comment_count": 0,
  "reply_count": 0,
  "react_count": 1,
  "reactions": {
    "s2": 1
  },
  "view_count": 1,
  "last_edited_at": "2022-04-21T12:49:20.356592Z",
  "created_at": "2022-04-21T12:49:20.095Z",
  "last_modified_at": "2022-04-21T12:48:41Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Understanding post_status values

refer to this section

Comments

Get a comment

Endpoint

GET /api/v1/comments/{comment_id}

Url path variables

Possible values Comments
comment_id The comment_id to be view data.


Additional Notes

The checks and conditions on who can comment, will be evaluated against the API user rather than the author of the comment.

Response parameters

{
  "post_id": 157,
  "comment_id": 24,
  "content": "Et doloribus aperiam ex qui architecto minima iste corrupti. Culpa voluptas quaerat aut molestiae eligendi harum consequatur. Et cum autem nostrum consequatur placeat et velit aspernatur. Voluptatem sed voluptatem molestiae magnam iure impedit non in et. Et voluptates totam possimus voluptatem rerum velit magni quisquam earum. Tempore dolor qui dolorem et accusamus voluptatem amet. Soap",
  "clean_text": "Et doloribus aperiam ex qui architecto minima iste corrupti. Culpa voluptas quaerat aut molestiae eligendi harum consequatur. Et cum autem nostrum consequatur placeat et velit aspernatur. Voluptatem sed voluptatem molestiae magnam iure impedit non in et. Et voluptates totam possimus voluptatem rerum velit magni quisquam earum. Tempore dolor qui dolorem et accusamus voluptatem amet. Soap",
  "react_count": 0,
  "reply_count": 0,
  "reactions": {
    "s2": 1
  },
  "comment_status": 15,
  "state": 0,
  "last_edited_at": "2022-05-06T11:25:16Z",
  "created_at": "2022-05-06T11:24:59Z",
  "last_modified_at": "2022-05-06T11:25:16Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Understanding comment_status values

Refer to this section


Understanding state values

Value comments
11 ARCHIVED
10 LOCKED
9 MODERATED
5 USER_REPORTED
0 DEFAULT
-2 REPORTED
-3 SPAM
-100 DELETED

Understanding reactions object

Refer to this section

Create a comment

Endpoint

POST /api/v1/comments

Body parameters

Name Type Req? Comments
post_id string Y  
content boolean Y  
author string Y msid of author


Additional Notes

The checks and conditional on who can comment will be evaluated against the API user rather than the author of the comment.

Response parameters

{
  "post_id": 157,
  "comment_id": 33,
  "content": "Quia eos ducimus odio quod eos. Fuga facere amet voluptas qui dolores eum quo vel suscipit. Accusamus unde voluptatem ut impedit laboriosam. Voluptatem laboriosam rerum eos fugit. Non id nihil quia quo et excepturi aut omnis. Tenetur debitis voluptatem voluptatibus quo accusamus. Table",
  "clean_text": "Quia eos ducimus odio quod eos. Fuga facere amet voluptas qui dolores eum quo vel suscipit. Accusamus unde voluptatem ut impedit laboriosam. Voluptatem laboriosam rerum eos fugit. Non id nihil quia quo et excepturi aut omnis. Tenetur debitis voluptatem voluptatibus quo accusamus. Table",
  "react_count": 0,
  "reply_count": 0,
  "comment_status": 15,
  "state": 0,
  "created_at": "2022-05-07T10:25:10.987109Z",
  "last_modified_at": "2022-05-07T10:25:10.987111Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Edit a comments

Endpoint

PUT /api/v1/comments/{comment_id}

Url path variables

Possible values Comments
comment_id The comment_id to be edited.

Body parameters

Name Type Req? Comments
content boolean Y  


Response parameters

{
  "post_id": 157,
  "comment_id": 34,
  "content": "Excepturi aut optio impedit fugiat sed est. Impedit accusamus earum ut et voluptatem. Dolore autem neque et eaque facilis aspernatur maxime et autem. In magnam voluptas dolor est aliquam fugit maiores. Voluptatum sed cum quia dolore. Consequatur doloremque accusantium consequatur. Chair",
  "clean_text": "Excepturi aut optio impedit fugiat sed est. Impedit accusamus earum ut et voluptatem. Dolore autem neque et eaque facilis aspernatur maxime et autem. In magnam voluptas dolor est aliquam fugit maiores. Voluptatum sed cum quia dolore. Consequatur doloremque accusantium consequatur. Chair",
  "react_count": 2,
  "reply_count": 0,
  "reactions": {
    "s4": 0,
    "s5": 1
  },
  "comment_status": 15,
  "state": 0,
  "last_edited_at": "2022-05-07T12:23:17.481925Z",
  "created_at": "2022-05-07T12:21:59Z",
  "last_modified_at": "2022-05-07T12:23:04Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Replies

Get a reply

Endpoint

GET /api/v1/replies/{reply_id}

Url path variables

Possible values Comments
reply_id The reply_id to be view data.

Response parameters

{
  "post_id": 15,
  "comment_id": 37,
  "reply_id": 8,
  "content": "Fugit possimus iste consequatur culpa quia. Minima sapiente beatae mollitia esse rerum similique eos. Eveniet consequuntur et itaque vero sed. Aut ut minus ullam voluptas. Quisquam nemo dicta quo voluptas est facilis. Ad ipsa assumenda perspiciatis qui aut ad quam. Aut soluta et suscipit non. Consectetur voluptas ab. Expedita quas neque illo dicta. Id fugiat iste cupiditate voluptas non qui provident expedita. Aliquam perferendis vel molestiae hic vitae eaque fugit sunt. Soap",
  "clean_text": "Fugit possimus iste consequatur culpa quia. Minima sapiente beatae mollitia esse rerum similique eos. Eveniet consequuntur et itaque vero sed. Aut ut minus ullam voluptas. Quisquam nemo dicta quo voluptas est facilis. Ad ipsa assumenda perspiciatis qui aut ad quam. Aut soluta et suscipit non. Consectetur voluptas ab. Expedita quas neque illo dicta. Id fugiat iste cupiditate voluptas non qui provident expedita. Aliquam perferendis vel molestiae hic vitae eaque fugit sunt. Soap",
  "react_count": 1,
  "reactions": {
    "s4": 1
  },
  "status": 15,
  "state": 0,
  "last_edited_at": "2022-05-08T18:01:56Z",
  "created_at": "2022-05-08T18:01:00Z",
  "last_modified_at": "2022-05-08T18:01:57Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Understanding comment_status values

Refer to this section

Understanding state values

Refer to this section

Understanding reactions object

Refer to this section

Create a reply

Endpoint

POST /api/v1/replies

Body parameters

Name Type Req? Comments
comment_id string Y  
content boolean Y  
author string Y msid of author


Additional Notes

The checks and conditional on who can reply to a comment, will be evaluated against the API user rather than the author.

Response parameters

{
  "post_id": 15,
  "comment_id": 37,
  "reply_id": 8,
  "content": "Architecto culpa rerum quis rem dolorem. Provident ipsum omnis quis qui culpa delectus voluptas voluptatem. Qui eum sit autem id provident nesciunt atque dolorem. Dolorum dolores eaque consequatur necessitatibus. Aut voluptates exercitationem itaque corrupti vel aut aperiam eveniet. Tempore magni rerum voluptatem laboriosam magnam molestiae dignissimos et quia. Quam deserunt dolores tempore amet nesciunt tempore est ut. Salad",
  "clean_text": "Architecto culpa rerum quis rem dolorem. Provident ipsum omnis quis qui culpa delectus voluptas voluptatem. Qui eum sit autem id provident nesciunt atque dolorem. Dolorum dolores eaque consequatur necessitatibus. Aut voluptates exercitationem itaque corrupti vel aut aperiam eveniet. Tempore magni rerum voluptatem laboriosam magnam molestiae dignissimos et quia. Quam deserunt dolores tempore amet nesciunt tempore est ut. Salad",
  "react_count": 0,
  "status": 15,
  "state": 0,
  "created_at": "2022-05-08T18:00:59.598882Z",
  "last_modified_at": "2022-05-08T18:00:59.598885Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Edit a reply

Endpoint

PUT /api/v1/replies/{comment_id}

Url path variables

Possible values Comments
reply_id The reply_id to edit data.

Body parameters

Name Type Req? Comments
content boolean Y  


Response parameters

{
  "post_id": 15,
  "comment_id": 37,
  "reply_id": 8,
  "content": "Fugit possimus iste consequatur culpa quia. Minima sapiente beatae mollitia esse rerum similique eos. Eveniet consequuntur et itaque vero sed. Aut ut minus ullam voluptas. Quisquam nemo dicta quo voluptas est facilis. Ad ipsa assumenda perspiciatis qui aut ad quam. Aut soluta et suscipit non. Consectetur voluptas ab. Expedita quas neque illo dicta. Id fugiat iste cupiditate voluptas non qui provident expedita. Aliquam perferendis vel molestiae hic vitae eaque fugit sunt. Soap",
  "clean_text": "Fugit possimus iste consequatur culpa quia. Minima sapiente beatae mollitia esse rerum similique eos. Eveniet consequuntur et itaque vero sed. Aut ut minus ullam voluptas. Quisquam nemo dicta quo voluptas est facilis. Ad ipsa assumenda perspiciatis qui aut ad quam. Aut soluta et suscipit non. Consectetur voluptas ab. Expedita quas neque illo dicta. Id fugiat iste cupiditate voluptas non qui provident expedita. Aliquam perferendis vel molestiae hic vitae eaque fugit sunt. Soap",
  "react_count": 1,
  "reactions": {
    "s4": 1
  },
  "status": 15,
  "state": 0,
  "last_edited_at": "2022-05-08T18:01:56.289679Z",
  "created_at": "2022-05-08T18:01:00Z",
  "last_modified_at": "2022-05-08T18:01:41Z",
  "user": {
    "user_id": 146,
    "user_avatar": "https://images.unsplash.com/photo-1558244661-d248897f7bc4",
    "username": "Alexandra",
    "msid": "146.VijCxex1IKckmzUDzYXlQycufs3"
  }
}

Tags

View a tag

Endpoint

GET /api/v1/tags/{tag_id}

Url path variables

Possible values Comments  
tag_id The tag_id to be viewed.  

Response parameters

{
  "tag_id": 18,
  "name": "administrator",
  "display_name": "Administrator",
  "description": "Chips",
  "image": "http://placeimg.com/640/480/food",
  "og_image": "http://placeimg.com/640/480/food",
  "og_title": "Chief Usability Director",
  "og_description": "bottom-line",
  "back_color": "#ffffff",
  "text_color": "#330000"
}

Understanding display_name and name values

The display_name tries to be similar to what the user has specified, on the other hand name will try parse the display_name into a hashtag for better search and familiarity. It is always stored in lowercase.

View all tags

Endpoint

GET /api/v1/tags

Query param options

For common paging options refer this

Query parameters default comments
sort_by unsorted available options are id,name.
order asc possible values asc or desc

Note: Listing records is a slow operation, make sure your code can handle it appropriately.

Response parameters

[
  {
    "tag_id": 18,
    "name": "administrator",
    "display_name": "Administrator",
    "back_color": "#ffffff",
    "text_color": "#330000"
  },
  {
    "tag_id": 13,
    "name": "architect",
    "display_name": "Architect",
    "back_color": "#ffffff",
    "text_color": "#330000"
  },
  {
    "tag_id": 1,
    "name": "asd",
    "display_name": "asd",
    "back_color": "#ffffff",
    "text_color": "#1b95e0"
  }
]

View some tags

Endpoint

GET /api/v1/tags

Query param options

For common paging options refer this

Query parameters default comments
ids   You can specify a list of tag_id values to get more details about them. e.g /api/v1/tags?ids=1,13,18

Response parameters

[
  {
    "tag_id": 18,
    "name": "administrator",
    "display_name": "Administrator",
    "back_color": "#ffffff",
    "text_color": "#330000"
  },
  {
    "tag_id": 13,
    "name": "architect",
    "display_name": "Architect",
    "back_color": "#ffffff",
    "text_color": "#330000"
  },
  {
    "tag_id": 1,
    "name": "asd",
    "display_name": "asd",
    "back_color": "#ffffff",
    "text_color": "#1b95e0"
  }
]

Create a tag

Endpoint

POST /api/v1/tags

Body parameters

Name Type Req? Comments
name string Y similar format as hashtags
description boolean N  
image string N url of image, displayed as banner in UI(future scope)
og_image string N image url
og_title string N  
og_description string N  
back_color string N hex color code, defaults to #ffffff
text_color string N hex color code, defaults to #330000

Note: Ensure that the name is unique across tags.

Response parameters

{
  "tag_id": 5,
  "name": "coordinator",
  "display_name": "Coordinator",
  "description": "Cheese",
  "image": "http://placeimg.com/640/480/food",
  "og_image": "http://placeimg.com/640/480/food",
  "og_title": "Product Optimization Technician",
  "og_description": "homogeneous",
  "back_color": "#ffffff",
  "text_color": "#330000"
}

Edit a tag

Endpoint

PUT /api/v1/tags/{tag_id}

Url path variables

Possible values Comments
tag_id The tag_id to be edited.

Body parameters

Name Type Req? Comments
name string Y similar format as hashtags
description boolean N  
image string N url of image, displayed as banner in UI(future scope)
og_image string N image url
og_title string N  
og_description string N  
back_color string N hex color code, defaults to #ffffff
text_color string N hex color code, defaults to #330000

Note: Ensure that the name is unique across tags.

Response parameters

{
  "tag_id": 5,
  "name": "associate",
  "display_name": "Associate",
  "description": "Table",
  "image": "http://placeimg.com/640/480/food",
  "og_image": "http://placeimg.com/640/480/food",
  "og_title": "Forward Mobility Coordinator",
  "og_description": "high-level",
  "back_color": "#ffffff",
  "text_color": "#330000"
}

View tags for entity

Endpoint

GET /api/v1/tags/mapping

Query param options

Query parameters default comments
ref_type   the value(string) for the entity type refer here
ref_id   the id value of the entity

Response parameters

[
  {
    "tag_id": 13,
    "name": "architect",
    "display_name": "Architect",
    "back_color": "#ffffff",
    "text_color": "#330000"
  },
  {
    "tag_id": 4,
    "name": "engineer",
    "display_name": "Engineer",
    "back_color": "#ffffff00",
    "text_color": "#1b95e0"
  },
  {
    "tag_id": 7,
    "name": "facilitator",
    "display_name": "Facilitator",
    "back_color": "#ffffff",
    "text_color": "#330000"
  }
]

Endpoint

GET /api/v1/tags/search

Query param options

Query parameters comments
q the q value will search against the tag name

Response parameters

[
  {
    "tag_id": 11,
    "name": "officer",
    "display_name": "Officer",
    "back_color": "#ffffff",
    "text_color": "#330000"
  }
]

Webhooks

Two options are available to configure webhooks

  1. Rest hooks which is based on subscriptions.
  2. Advanced configuration via UI

Following events are available for configuration

Event Comments
member.joined  
member.joined_waitlist  

We Also support zapier integration. Contact support team for more information.

Note: We keep adding more events, do check with us from time to time.

Webhook Sample

Response parameters

{
  "event": "member.joined",
  "job_id": 164,
  "entities": {
    "user": [
      {
        "sid": "JO7Rv1B4bEBUawd3d2DXsE2DA",
        "msid": "206.JO7Rv1B4bEBUawd3d2DXsE2DA",
        "email": "sample@example.com",
        "role_id": 4,
        "user_id": 206,
        "username": "sample",
        "last_name": "free",
        "created_at": "2022-09-14T06:16:26Z",
        "first_name": "Sample",
        "user_avatar": "string",
        "user_status": 10
      }
    ]
  }
}

response parameters explanation

Please refer to the respective entity endpoint to understand the response details. The structure above is standardized for all the webhook events. Different entities are keys under the entities object in json and each key will have an array of objects even in case of single object. In the sample above the entities object has a key user which is an array of user objects. Since the event is member.joined the array will have only one object. Also, in the above case to understand the params refer to the user endpoint.

Errors

Common errors and format is listed below.

Sample Response

{
  "id": "1sVIyJhyVLC_5PG5vCsY",
  "status": "BAD_REQUEST",
  "time": "2022-02-22T22:22:22.222222Z",
  "message": "ERR_V1█Request payload validation errors"
}

Possible errors

400 BAD_REQUEST

403 FORBIDDEN 

404 NOT_FOUND

405 METHOD_NOT_ALLOWED

409 CONFLICT

418 I_AM_A_TEAPOT

429 TOO_MANY_REQUESTS

500 SERVER_ERROR

503 SERVICE_UNAVAILABLE

SSO

Refer here