Organisation Service API

The Organisation Service handles organisation records, master/reference data, and assessment-related features. It runs on internal port 9107 and is exposed through the gateway at the /organisation prefix.

Base paths:

All endpoints require a valid Bearer token unless otherwise noted.

The Service Request module also lives in this service (under /admin/service-requests/* and /hub/service-requests/*). It has its own dedicated docs:

• Service Request Service API
• Admin Guide
• Hub Guide

---

Organisation Endpoints

GET /organisation/organisation

Retrieves a list of all organisations.

Authentication: Required.

Success response – 200 OK

[
  {
    "_id": "64c3d4e5f6a7b8c9d0e1f2a3",
    "name": "Acme Corp",
    "industry": "64d4e5f6a7b8c9d0e1f2a3b4",
    "country": "64e5f6a7b8c9d0e1f2a3b4c5",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
]

---

POST /organisation/organisation

Creates a new organisation. Accepts multipart/form-data (not JSON).

Authentication: Required.

Request — multipart/form-data

⚠️ All boolean and number fields must be sent as strings in multipart form data (e.g. "true", "false", "50"). Do not set Content-Type: application/json.

Example (curl)

curl -X POST https://api.zeswa.com/organisation/organisation \
  -H "Authorization: Bearer <accessToken>" \
  -F "name=Acme Corp" \
  -F "urlName=acme-corp" \
  -F "isPublic=true" \
  -F "licenses=50" \
  -F "logo=@/path/to/logo.png"

Success response — 200 OK

{
  "organisation": {
    "id": "a1b2c3d4-...",
    "name": "Acme Corp",
    "urlName": "acme-corp",
    "logo": "https://res.cloudinary.com/your-cloud/image/upload/v.../zeswa/xxx.png",
    "isPublic": true,
    "licenses": 50,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Error responses

---

GET /organisation/organisation/:id

Retrieves a single organisation by ID.

Authentication: Required.

Path parameters

Success response — 200 OK

Returns the organisation object.

Error responses

---

PUT /organisation/organisation/:id

Updates an existing organisation. Accepts multipart/form-data (not JSON). Include only the fields you want to change.

Authentication: Required.

Path parameters

Request — multipart/form-data

All fields are optional. Same field definitions as POST above, except:

Example (curl)

# Update name only
curl -X PUT https://api.zeswa.com/organisation/organisation/a1b2c3d4-... \
  -H "Authorization: Bearer <accessToken>" \
  -F "name=Acme Corporation"

# Update logo only
curl -X PUT https://api.zeswa.com/organisation/organisation/a1b2c3d4-... \
  -H "Authorization: Bearer <accessToken>" \
  -F "logo=@/path/to/new-logo.jpg"

Success response — 200 OK

Returns the updated organisation object.

Error responses

---

DELETE /organisation/organisation/:id

Deletes an organisation.

Authentication: Required.

Path parameters

Success response – 200 OK

{
  "message": "Organisation deleted successfully"
}

Error responses

---

Account Endpoints

GET /organisation/account

Retrieves a list of accounts.

Authentication: Required.

POST /organisation/account

Creates a new account.

Authentication: Required.

GET /organisation/account/:id

Retrieves a single account by ID.

Authentication: Required.

PUT /organisation/account/:id

Updates an existing account.

Authentication: Required.

DELETE /organisation/account/:id

Deletes an account.

Authentication: Required.

All account endpoints follow the same request/response patterns as the organisation endpoints above.

---

Master Data Endpoints

The Organisation Service manages several collections of reference data. Each collection follows a consistent CRUD pattern with the same endpoint structure. All master data endpoints require authentication.

Common Pattern

For each master data type, the following endpoints are available:

Available Master Data Types

---

Country

Path prefix: /organisation/country

Manages the list of countries available in the platform.

{
  "_id": "64e5f6a7b8c9d0e1f2a3b4c5",
  "name": "Australia",
  "code": "AU"
}

---

Industry

Path prefix: /organisation/industry

Manages industry classifications.

{
  "_id": "64d4e5f6a7b8c9d0e1f2a3b4",
  "name": "Technology"
}

---

Function

Path prefix: /organisation/function

Manages business function classifications (e.g., Engineering, Marketing, Sales).

{
  "_id": "64f6a7b8c9d0e1f2a3b4c5d6",
  "name": "Engineering"
}

---

Education Level

Path prefix: /organisation/education-level

Manages education level options (e.g., Bachelor’s, Master’s, PhD).

{
  "_id": "64a7b8c9d0e1f2a3b4c5d6e7",
  "name": "Master's Degree"
}

---

Study Major

Path prefix: /organisation/study-major

Manages academic study major options.

{
  "_id": "64b8c9d0e1f2a3b4c5d6e7f8",
  "name": "Computer Science"
}

---

Skill

Path prefix: /organisation/skill

Manages the skills taxonomy used for teammate profiles and assessments.

{
  "_id": "64c9d0e1f2a3b4c5d6e7f8a9",
  "name": "TypeScript"
}

---

Location

Path prefix: /organisation/location

Manages location records (offices, sites, or regions).

{
  "_id": "64d0e1f2a3b4c5d6e7f8a9b0",
  "name": "Sydney Office",
  "country": "64e5f6a7b8c9d0e1f2a3b4c5"
}

---

Master Data – Example Requests

List all countries:

curl -X GET https://api.zeswa.com/organisation/country \
  -H "Authorization: Bearer <accessToken>"

Create a new skill:

curl -X POST https://api.zeswa.com/organisation/skill \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name": "TypeScript"}'

Update an industry:

curl -X PUT https://api.zeswa.com/organisation/industry/64d4e5f6a7b8c9d0e1f2a3b4 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Information Technology"}'

Delete a location:

curl -X DELETE https://api.zeswa.com/organisation/location/64d0e1f2a3b4c5d6e7f8a9b0 \
  -H "Authorization: Bearer <accessToken>"

---

Assessment Data Endpoints

The Organisation Service also manages assessment-related data: questions, question groups, and question answers. These entities use auto-generated numeric IDs. All endpoints require authentication.

Common Pattern

For each assessment data type, the following endpoints are available:

---

Question

Path prefix: /organisation/question

Manages assessment questions. Each question belongs to a question group.

{
  "id": 1,
  "questionGroupId": 1,
  "orderIndex": 1,
  "type": "LIKERT",
  "text": "I enjoy working in a team environment",
  "summary": "Measures how much a person values and enjoys collaborative work. High scorers tend to thrive in group settings and prioritise shared effort over solo achievement.",
  "likertAnswerSet": "agree",
  "metadata": null,
  "faking": false,
  "reverseScore": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

List query parameters:

---

Question Group

Path prefix: /organisation/question-group

Manages groups of questions used in assessments. Each group defines a scoring type.

{
  "id": 1,
  "name": "teamwork",
  "title": "Teamwork Assessment",
  "strapline": "Evaluate your teamwork capabilities",
  "scoreType": "COMPLEMENTARY",
  "questionIds": [1, 2, 3, 4, 5],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

List query parameters:

---

Question Answer

Path prefix: /organisation/question-answer

Manages answer options for questions. Each answer belongs to a specific question.

{
  "id": 1,
  "orderIndex": 1,
  "text": "Strongly Agree",
  "value": 5,
  "questionId": 1,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

List query parameters:

Unique constraints: A question cannot have duplicate value entries or duplicate orderIndex entries.

---

Assessment Data – Example Requests

List all questions in a group:

curl -X GET "https://api.zeswa.com/organisation/question?questionGroupId=1" \
  -H "Authorization: Bearer <accessToken>"

Create a new question group:

curl -X POST https://api.zeswa.com/organisation/question-group \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name": "leadership", "title": "Leadership Assessment", "strapline": "Evaluate leadership skills", "scoreType": "COMPLEMENTARY", "questionIds": [1, 2, 3]}'

Add an answer to a question:

curl -X POST https://api.zeswa.com/organisation/question-answer \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"orderIndex": 1, "text": "Strongly Agree", "value": 5, "questionId": 1}'

Update a question:

curl -X PUT https://api.zeswa.com/organisation/question/1 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"questionGroupId": 1, "type": "LIKERT", "text": "Updated question text", "faking": false, "reverseScore": true}'

Delete an answer:

curl -X DELETE https://api.zeswa.com/organisation/question-answer/1 \
  -H "Authorization: Bearer <accessToken>"

---

Utility Endpoints

GET /organisation/stats

Returns aggregated dashboard statistics across all platform entities in a single request. All counts are executed in parallel for optimal performance.

Authentication: Required.

Success response — 200 OK

{
  "organisation": {
    "totalNumberOfOrganisation": 12
  },
  "user": {
    "totalActiveUsers": 340,
    "totalInactiveUsers": 58
  },
  "evaluations": {
    "totalEvaluations": 720,
    "totalEvaluationsInProgress": 45,
    "totalEvaluationsCompleted": 620
  },
  "persona": {
    "totalNumberOfPersonas": 398,
    "totalNumberOfCandidates": 120,
    "totalNumberOfEmployee": 210,
    "totalNumberOfHR": 18,
    "totalNumberOfTeamManager": 30,
    "totalNumberOfManager": 20
  },
  "team": {
    "totalNumberOfTeam": 55
  }
}

Field reference

Note: A single Persona can hold multiple roles (e.g., both EMPLOYEE and TEAM_MANAGER), so role counts may overlap and their sum can exceed totalNumberOfPersonas.

Example

curl -X GET https://api.zeswa.com/organisation/stats \
  -H "Authorization: Bearer <accessToken>"

Error responses

---

GET /organisation/stats/visitors

Returns daily API call counts grouped by device type for the last 90 days, sorted by date ascending.

Authentication: Required.

Device type classification

Device type is determined by inspecting the User-Agent header of each logged API request:

Only device types that have data on a given day will appear as keys in that day’s object.

Success response — 200 OK

[
  { "date": "2024-04-01", "desktop": 222, "mobile": 150 },
  { "date": "2024-04-02", "desktop": 97,  "mobile": 180, "unknown": 5 },
  { "date": "2024-04-03", "desktop": 167, "mobile": 120 },
  { "date": "2024-06-30", "desktop": 446, "mobile": 400, "unknown": 12 }
]

Example

curl -X GET https://api.zeswa.com/organisation/stats/visitors \
  -H "Authorization: Bearer <accessToken>"

Error responses

---

GET /organisation/stats/byapp

Returns daily API call counts grouped by calling application (callerApp field) for the last 90 days, sorted by date ascending.

Authentication: Required.

callerApp values

Keys in the response are dynamic — only apps with calls on that day will appear. New callerApp values will appear automatically without any backend changes.

Success response — 200 OK

[
  { "date": "2024-04-01", "hub": 222, "admin": 150 },
  { "date": "2024-04-02", "hub": 97,  "admin": 180 },
  { "date": "2024-04-03", "hub": 167, "admin": 120 },
  { "date": "2024-06-30", "hub": 446, "admin": 400, "postman": 12 }
]

Example

curl -X GET https://api.zeswa.com/organisation/stats/byapp \
  -H "Authorization: Bearer <accessToken>"

Error responses

---

GET /organisation/health

Returns the health status of the Organisation Service.

Authentication: None required.

GET /organisation/_ping

Lightweight liveness probe.

Authentication: None required.