API documentation

API Error codes

• 401: Invalid token (Unauthorised)
• 403: Access error
• 400: Validation error
• 422: Unprocessable entity
• 500: Internal server error

API success codes

• 201: Status created (POST Requests)
• 200: Status ok

Error Response:

{
 error: {
   code: "invalid_data"
   message: "Please provide valid form data"

   fields: {
     "field_name": "Error message",
     "field_name": "Error message"
   }
 }
}

Note: fields section in error response will be present only when token is valid and there are form validation errors

Request Headers:

{
  "Content-Type": "application/json",
  "Accept": "application/vnd.peerly.v1",
  "Authorization": `Bearer ${apiToken}`
}

API Endpoints

1. Google login

POST /oauth/google

Payload:

access_token: "" (required)

Note: Validation must be present to check if signin email used for login belongs to valid organisation domain

Success Response:

Status code: 200 (ok)

{
  data: {
    token: <string>
  }
}

### Claims inside JWT token:

iss: "node.peerly.com"
sub: <user-id> or <uuid> to uniquely identify a user
aud: <base url of react ui> (for now it can be "peerly.com")
exp: epoch (seconds) - on or after which it will not be accepted
nbf: epoch (seconds) - token older than this time won't be accepted
iat: epoch (seconds) - time of issuing the token
"https://peerly.com": {
   "roleId": <role-id>,
   "orgId": <org-id>,
   "orgName": "<name of org>"
 }

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 500 (InternalServerError)

{ 
  "error": {
     message: "internal server error"
  }
}

---

2. Logout

POST /logout

Success Response:

Status code: 200 (ok)

Error Response:

Status Code: 500 (InternalServerError)

{ 
  "error": {
     message: "internal server error"
  }
}

---

3. Core Values

POST /core_values

Payload:

"description": "" (required)
"text": "" (required)
"parent_core_value_id": null (optional)

Success Response:

Status code: 201 (created)

{
  data: {
    "id": <id>,
    "description": <description>,
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id> (default null)
    "org_id": <organisation_id>
  } 
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

Status Code: 400 (Invalid request)

{
 error: {
   code: "invalid_data"
   message: "Invalid core value data"

   fields: {
     "field_name": "Error message",
     "field_name": "Error message"
   }
 }
}

---

PUT /core_values/:id

Payload:

"description": "" (required)
"text": "" (required)

Success Response:

Status code: 200 (ok)

{
  data: {
    "id": <id>
    "description": <description>
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>
    "org_id": <organisation_id>
  }
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

Status Code: 400 (Invalid request)

{
 error: {
   code: "invalid_data"
   message: "Invalid core value data"

   fields: {
     "field_name": "Error message",
     "field_name": "Error message"
   }
 }
}

---

GET /core_values

Success Response:

Status code: 200 (ok)

{
  data: [{
    "id":<id>
    "description": <description>
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>
    "org_id": <organisation_id>
  }.
  {
    "id":<id> 
    "description": <description>
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>
    "org_id": <organisation_id>
  }]
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

---

GET /core_values/:id

Success Response:

Status code: 200 (ok)

{
  data: {
    "id":<id>
    "description": <description>
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>
    "org_id": <organisation_id>
  }
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

---

4. Users

GET /users

Query Params

• limit (optional)
• offset (optional)
• starts_with (optional) search by text
• org_id (optional only for super admin access)

Success Response:

Status code: 200 (ok)

{
  data: [{
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
    "soft_delete_by": <user_id>
    "soft_delete_at": <timestamp>
  }.
  {
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
    "soft_delete_by": <user_id>
    "soft_delete_at": <timestamp>
  }]
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

---

GET /users/:id

Success Response:

Status code: 200 (ok)

{
  data: {
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
  }
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

---

PUT /users/:id

Payload

"first_name": <first_name> (required)
"last_name": <last_name> (required)
"display_name": <display_name> (required)
"profile_image_url": <profile_image_url> (optional)

Success Response:

Status code: 200 (ok)

{
  data: {
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
  }
}

Note: No POST API for users they will be created by login

---

5. Recognitions

GET /recognitions

Query params

• given_by (optional)
• given_for (optional)
• core_value_id (optional)
• limit (optional)
• offset (optional)

Success Response:

Status code: 200 (ok)

{
  data: [{
    "id":<id>
    "core_values_id": <core_value_id>
    "text": <recognition_text>,
    "given_for": <user_id>
    "given_by": <user_id>
    "given_at": <timestamp>
  }.
  {
    "id":<id>
    "core_values_id": <core_value_id>
    "text": <recognition_text>,
    "given_for": <user_id>
    "given_by": <user_id>
    "given_at": <timestamp>
 
  }]
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

---

POST /recognitions

Payload

• given_for (required)
• core_value_id (required)
• text (required)

Success Response:

Status code: 201 (created)

{
  data: {
    "id":<id>
    "core_values_id": <core_value_id>
    "text": <recognition_text>,
    "given_for": <user_id>
    "given_by": <user_id>
    "given_at": <timestamp>
  } 
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

---

6. Recognition Hi5

POST /recognitions/:recognition_id/hi5

Payload

• comment (optional)

Success Response:

Status code: 201 (created)

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

Status Code: 400

{ 
  "error": {
     code: "insufficient_hi5_balance"
     message: "Hi5 quota balance is insufficient for this action"
  }
}

---