Organisations (/api/v1/organisation)

Multi-user organisation management. Organisations allow teams to collaborate on loan processing, document management, and shared dashboards.

All endpoints require authentication via X-API-Key. Owner-only endpoints are noted.

---

1. Create Organisation

Create a new organisation. The creator becomes the primary owner.

• Method: POST
• Endpoint: /api/v1/organisation

Request Body

Parameter	Type	Description
name	String	Organisation name (required)
organization_address	String	Organisation address
organization_nmlsr_id	String	NMLSR ID
organization_state_license	String	State license
originator_name	String	Originator name
originator_nmlsr_id	String	Originator NMLSR ID
originator_state_license	String	Originator state license
originator_email	String	Originator email
originator_phone	String	Originator phone

{
  "name": "My Lending Company",
  "organization_address": "123 Business Ave, Suite 100",
  "organization_nmlsr_id": "NMLS-12345",
  "organization_state_license": "CA-12345",
  "originator_name": "Jane Agent",
  "originator_nmlsr_id": "NMLS-67890",
  "originator_email": "jane@company.com",
  "originator_phone": "555-0100"
}

Response (201 Created)

{
  "id": "uuid",
  "name": "My Lending Company",
  "orgCode": "a1b2c3d4",
  "ownerId": "uuid",
  "organizationAddress": "123 Business Ave, Suite 100",
  "organizationNmlsrId": "NMLS-12345",
  ...
}

---

2. Join Organisation

Join an existing organisation using its invite code.

• Method: POST
• Endpoint: /api/v1/organisation/join

Request Body

{ "orgCode": "a1b2c3d4" }

Response

{
  "message": "Successfully joined organisation",
  "organisation": { ... }
}

---

3. Get Organisation Details

Retrieve the current user's organisation info.

• Method: GET
• Endpoint: /api/v1/organisation

Response

{
  "id": "uuid",
  "name": "My Lending Company",
  "orgCode": "a1b2c3d4",
  "ownerId": "uuid",
  "currentUserRole": "OWNER",
  ...
}

---

4. Leave Organisation

Leave the current organisation (owners must transfer ownership or demote themselves first).

• Method: POST
• Endpoint: /api/v1/organisation/leave

Response

{ "message": "Left organisation successfully" }

---

5. Get Organisation Dashboard (Owner)

View the organisation dashboard with member list.

• Method: GET
• Endpoint: /api/v1/organisation/dashboard
• Role: Owner only

Response

{
  "id": "uuid",
  "name": "My Lending Company",
  "members": [
    { "id": "uuid", "name": "John Doe", "email": "john@company.com", "orgRole": "OWNER", "createdAt": "..." },
    { "id": "uuid", "name": "Jane Smith", "email": "jane@company.com", "orgRole": "MEMBER", "createdAt": "..." }
  ],
  ...
}

---

6. Update Organisation (Owner)

Update organisation details.

• Method: PUT
• Endpoint: /api/v1/organisation
• Role: Owner only

Request Body

Same fields as Create Organisation.

---

7. Delete Organisation (Owner)

Delete the organisation and remove all members.

• Method: DELETE
• Endpoint: /api/v1/organisation
• Role: Owner only

Response

{ "message": "Organisation deleted successfully" }

---

8. Get Organisation Loans (Owner)

View all loans across the organisation.

• Method: GET
• Endpoint: /api/v1/organisation/loans
• Role: Owner only

Query Parameters

Parameter	Type	Default	Description
page	Number	1	Page number
limit	Number	50	Loans per page

Response

{
  "loans": [
    {
      "id": "uuid",
      "user": { "name": "John Doe", "email": "john@company.com" },
      "loanAmount": 50000,
      "loanPurpose": "Home Improvement",
      "status": "PENDING",
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

---

9. Get Organisation Documents (Owner)

View all documents across the organisation.

• Method: GET
• Endpoint: /api/v1/organisation/documents
• Role: Owner only

---

10. Manage Members (Owner)

Action	Method	Endpoint	Body
Remove member	DELETE	/organisation/members	{ "memberId": "uuid" }
Promote to owner	POST	/organisation/members/promote	{ "memberId": "uuid" }
Demote owner to member	POST	/organisation/members/demote	{ "ownerId": "uuid" }
View member profile	GET	/organisation/members/:memberId	—
View member loans	GET	/organisation/members/:memberId/loans	—
View member documents	GET	/organisation/members/:memberId/documents	—

---

11. Regenerate Invite Code (Owner)

Generate a new organisation invite code. The old code becomes invalid.

• Method: POST
• Endpoint: /api/v1/organisation/code/refresh
• Role: Owner only

Response

{
  "message": "Organisation code regenerated",
  "orgCode": "x9y8z7w6"
}