Portfolio

As the name suggests, users are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your users. On this page, we'll dive into the different user endpoints you can use to manage users programmatically. We'll look at how to query, create, update, and delete users.

The user model

The user model contains all the information about your users, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the user and information about when they were last active on Protocol.

Properties

  • Name
    _id
    Type
    objectId
    Description

    Unique identifier for the user.

  • Name
    username
    Type
    string
    Description

    Unique username for login.

  • Name
    email
    Type
    string
    Description

    Email should be verified and used for sending notification.

  • Name
    name
    Type
    string
    Description

    User real full name.

  • Name
    name_alias
    Type
    string
    Description

    User name that company choose, used for approval name, etc...

  • Name
    role_id
    Type
    objectId
    Description

    User has role, list of permissions that they had.

  • Name
    branchDefault_id
    Type
    objectId
    Description

    For determine which branch created the form.

  • Name
    branchAccess_id
    Type
    objectId
    Description

    For separate data from other user from other branch.

  • Name
    isArchived
    Type
    boolean
    Description
  • Name
    createdBy_id
    Type
    objectId
    Description

    For tracking who create the data.

  • Name
    updatedBy_id
    Type
    objectId
    Description

    For tracking who update the data.

  • Name
    createdAt
    Type
    datetime
    Description
  • Name
    updatedAt
    Type
    datetime
    Description
  • Name
    isActive
    Type
    boolean
    Description

    Check if user fully activated, if not user cannot log in.

  • Name
    warehouseDefault_id
    Type
    objectId
    Description

    For input transaction related to stock.

  • Name
    warehouseAccess_id
    Type
    objectId
    Description

    For input transaction related to stock.

GET/v1/users

Market Status

This endpoint allows you to retrieve a paginated list of all your users.

Request

GET
/v1/users
curl -G https://api.protocol.chat/v1/users \
  -H "Authorization: Bearer {token}" \
  -d active=true \

Response

{
  "data": [
    {
      "_id": "WAz8eIbvDR60rouK",
      "name": "Aini",
      "email": "[email protected]",
      "role_permission": "admin purchase",
      "branch_access": "Surabaya",
      "warehouse_access": null,
      "isActive": true
    },
    {
      "_id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}
POST/v1/users

Invite a user

This endpoint allows you to add a new user to your user list in Protocol. To add a user, you must provide their Protocol username and phone number.

Required attributes

  • Name
    name
    Type
    string
    Description

    User real full name.

  • Name
    name_alias
    Type
    string
    Description

    user name that company choose, used for approval name, etc...

  • Name
    email
    Type
    string
    Description

    Email should be verified and used for sending notification.

  • Name
    role_id
    Type
    string
    Description

    User has role, list of permissions that they had.

  • Name
    branch_access
    Type
    array
    Description

    For separate data from other user from other branch.

Request

POST
/v1/users
curl https://api.protocol.chat/v1/users \
  -H "Authorization: Bearer {token}" \
  -d name="Aini" \
  -d name_alias="Aini" \
  -d email="[email protected]" \
  -d role_id="hSIhXBhNe8X1d8Et" \
  -d branchAccess_id=["hSIhXBhNe8X1d8Et"]

Response

{
  "_id": "WAz8eIbvDR60rouK",
  "name": "Aini",
  "email": "[email protected]",
  "role": {
    "_id": "hSIhXBhNe8X1d8Et",
    "name": "Admin Pembelian"
  },
  "branch_access": [
    "0": {
      "_id": "hSIhXBhNe8X1d8Et",
      "name": "Surabaya"
    }
  ]
}
GET/v1/users/:id

Retrieve a user

This endpoint allows you to retrieve a user by providing their Protocol id. Refer to the list at the top of this page to see which properties are included with user objects.

Request

GET
/v1/users/WAz8eIbvDR60rouK
curl https://api.protocol.chat/v1/users/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "Aini",
  "email": "[email protected]",
  "role": {
    "_id": "hSIhXBhNe8X1d8Et",
    "name": "Admin Pembelian"
  "branch_access": [
    "0": {
      "_id": "hSIhXBhNe8X1d8Et",
      "name": "Surabaya"
    }
  ],
  "warehouse_access": [
    "0": {
      "_id": "hSIhXBhNe8X1d8Et",
      "name": "Surabaya"
    }
  ]
}
PUT/v1/users/:id

Update a user

This endpoint allows you to perform an update on a user. Currently, the only attribute that can be updated on users is the display_name attribute which controls how a user appears in your user list in Protocol.

Required attributes

  • Name
    role_id
    Type
    string
    Description

    User has role, list of permissions that they had.

  • Name
    branch_access
    Type
    array
    Description

    For separate data from other user from other branch.

Request

PUT
/v1/users/WAz8eIbvDR60rouK
curl -X PUT https://api.protocol.chat/v1/users/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d role_id="hSIhXBhNe8X1d8Et" \
  -d branch_access=["hSIhXBhNe8X1d8Et"]

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "Aini",
  "email": "[email protected]",
  "role": {
    "_id": "hSIhXBhNe8X1d8Et",
    "name": "Admin Pembelian"
  },
  "branch_access": [
    "0": {
      "_id": "hSIhXBhNe8X1d8Et",
      "name": "Surabaya"
    }
  ]
}
DELETE/v1/users/:id

Delete a user

This endpoint allows you to delete users from your user list in Protocol. Note: This will also delete your conversation with the given user.

Request

DELETE
/v1/users/WAz8eIbvDR60rouK
curl -X DELETE https://api.protocol.chat/v1/users/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"