Skip to main content

Institution Endpoints

Complete reference for institution and organization management endpoints.

Base URL​

https://api.govalid.org/api/v1/institution/

Institution Settings​

Get Settings​

GET /api/v1/institution/settings/

Response​

{
  "id": "inst-001",
  "name": "Acme Corporation",
  "type": "business",
  "departments_count": 5,
  "staff_count": 50,
  "settings": {
    "default_security_level": "verified",
    "require_approval": true,
    "quota_enabled": true
  }
}

Update Settings​

PATCH /api/v1/institution/settings/

Departments​

List Departments​

GET /api/v1/institution/departments/

Response​

{
  "count": 5,
  "results": [
    {
      "id": "dept-001",
      "name": "Quality Assurance",
      "staff_count": 10,
      "quota": {
        "qr_codes_per_month": 500,
        "used": 250
      },
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Department​

POST /api/v1/institution/departments/

Request Body​

{
  "name": "Quality Assurance",
  "description": "Product quality and verification",
  "quota": {
    "qr_codes_per_month": 500
  }
}

Update Department​

PATCH /api/v1/institution/departments/{id}/

Delete Department​

DELETE /api/v1/institution/departments/{id}/

Roles​

List Roles​

GET /api/v1/institution/roles/

Response​

{
  "count": 4,
  "results": [
    {
      "id": "role-001",
      "name": "Admin",
      "permissions": ["create_qr", "manage_staff", "view_analytics", "manage_billing"],
      "staff_count": 3
    },
    {
      "id": "role-002",
      "name": "Operator",
      "permissions": ["create_qr", "view_analytics"],
      "staff_count": 20
    }
  ]
}

Create Role​

POST /api/v1/institution/roles/

Request Body​

{
  "name": "Verifier",
  "permissions": ["create_qr", "verify_qr"]
}

Numbering Patterns​

List Patterns​

GET /api/v1/institution/patterns/

Create Pattern​

POST /api/v1/institution/patterns/

Request Body​

{
  "name": "Certificate Pattern",
  "pattern": "CERT-{YYYY}-{SEQ}",
  "prefix": "CERT",
  "sequence_length": 4
}

Document Types​

List Document Types​

GET /api/v1/institution/document-types/

Create Document Type​

POST /api/v1/institution/document-types/

Request Body​

{
  "name": "Certificate",
  "description": "Product certification documents",
  "numbering_pattern": "pattern-001",
  "required_fields": ["product_name", "batch", "issue_date"]
}

Quota Settings​

Get Quota Settings​

GET /api/v1/institution/quota/

Update Quota​

PATCH /api/v1/institution/quota/

Request Body​

{
  "department_id": "dept-001",
  "qr_codes_per_month": 1000
}

Staff Management​

List Staff Members​

GET /api/v1/institution/staff/

Invite Staff Member​

POST /api/v1/institution/staff/invite/

Request Body​

{
  "email": "[email protected]",
  "role_id": "role-002",
  "department_id": "dept-001"
}

Approve/Reject Staff Verification​

POST /api/v1/institution/staff/{id}/approve/
POST /api/v1/institution/staff/{id}/reject/