Phase 1: Organization Registration

Organization registration creates the foundation for all B2B operations including the organization entity, legal information, addresses, and default admin user.

What Gets Created

Component	Status	Description
Organization Record	`PENDING_VERIFICATION`	Core organization entity
Default Admin User	`PENDING_ACTIVATION`	Created via Kafka event
Wallet	`INACTIVE`	Default wallet (activated later)
Categorization	Assigned	Feature-based category (if provided)

Register Organization

Endpoint: POST /api/v2.1/customer/organization/registration

Headers:

http

X-Tenant-ID: fh_api_finsei_ltd_7f957f77
Authorization: Bearer {admin-jwt-token}
Content-Type: application/json

Request Body:

json

{
  "tenantId": "97e7ff29-15f3-49ef-9681-3bbfcce4f6cd",
  "legalName": "Acme Corporation Limited",
  "tradingName": "Acme Corp",
  "businessType": "B2B",
  "registrationNumber": "REG123456789",
  "taxId": "TAX987654321",
  "vatNumber": "GB123456789",
  "incorporationDate": "2010-05-20",
  "legalForm": "LIMITED_LIABILITY_COMPANY",
  "industry": "TECHNOLOGY",
  "sector": "SOFTWARE_DEVELOPMENT",
  "numberOfEmployees": 50,
  "annualRevenue": "5000000",
  "website": "https://www.acme-corp.com",
  "description": "Leading provider of enterprise software solutions",
  "registeredAddress": {
    "street": "456 Business Avenue",
    "streetNumber": "456",
    "building": "Tech Tower",
    "floor": "5th Floor",
    "city": "London",
    "state": "Greater London",
    "postalCode": "EC1A 1BB",
    "country": "GB",
    "addressType": "REGISTERED_OFFICE"
  },
  "tradingAddress": {
    "street": "456 Business Avenue",
    "city": "London",
    "postalCode": "EC1A 1BB",
    "country": "GB",
    "addressType": "TRADING_ADDRESS"
  },
  "contactEmail": "contact@acme-corp.com",
  "contactPhone": "+442071234567",
  "contactPerson": {
    "firstName": "Jane",
    "lastName": "Smith",
    "position": "CEO",
    "email": "jane.smith@acme-corp.com",
    "phone": "+442071234569"
  },
  "representatives": [
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "role": "CEO",
      "email": "jane.smith@acme-corp.com",
      "ownershipPercentage": 60.0,
      "nationality": "GB",
      "dateOfBirth": "1975-03-15",
      "isPEP": false
    },
    {
      "firstName": "John",
      "lastName": "Doe",
      "role": "CFO",
      "email": "john.doe@acme-corp.com",
      "ownershipPercentage": 40.0,
      "nationality": "GB",
      "dateOfBirth": "1978-07-22",
      "isPEP": false
    }
  ],
  "categorization": {
    "id": "org-cat-550e8400-e29b-41d4-a716-446655440100",
    "name": "MEDIUM_RISK_BUSINESS",
    "isActive": true,
    "categoryFeatureRelations": [
      {
        "feature": {
          "id": "org-feat-660e8400-e29b-41d4-a716-446655440101",
          "code": "BUSINESS_TRANSACTION_LIMITS"
        },
        "enabled": true,
        "parametrization": [
          { "name": "riskLevel", "value": "MEDIUM" },
          { "name": "riskScore", "value": "55" },
          { "name": "monthlyLimit", "value": "500000" },
          { "name": "transactionLimit", "value": "100000" },
          { "name": "dailyLimit", "value": "200000" }
        ]
      },
      {
        "feature": {
          "id": "org-feat-770e8400-e29b-41d4-a716-446655440102",
          "code": "INTERNATIONAL_PAYMENTS"
        },
        "enabled": true,
        "parametrization": [
          { "name": "swiftEnabled", "value": "true" },
          { "name": "sepaEnabled", "value": "true" },
          { "name": "crossBorderLimit", "value": "50000" }
        ]
      }
    ]
  }
}

Status: 201 Created

json

{
  "code": 201,
  "message": "Organization registered successfully. Default admin will be created automatically. Use separate endpoints to add employees, directors, and shareholders.",
  "data": {
    "id": "org-880e8400-e29b-41d4-a716-446655440110",
    "legalName": "Acme Corporation Limited",
    "tradingName": "Acme Corp",
    "businessType": "B2B",
    "status": "PENDING_VERIFICATION",
    "registrationNumber": "REG123456789",
    "taxId": "TAX987654321",
    "incorporationDate": "2010-05-20",
    "industry": "TECHNOLOGY",
    "categorization": {
      "id": "org-cat-550e8400-e29b-41d4-a716-446655440100",
      "name": "MEDIUM_RISK_BUSINESS"
    },
    "addresses": {
      "registered": {...},
      "trading": {...}
    },
    "contacts": {
      "email": "contact@acme-corp.com",
      "phone": "+442071234567"
    },
    "representatives": [...],
    "employees": [],
    "directors": [],
    "shareholders": [],
    "createdAt": "2026-01-13T10:00:00.000Z"
  }
}

Key ID to Store:

id → Organization ID (for all subsequent calls)

400 - Missing Required Fields:

json

{
  "code": 400,
  "message": "Validation failed",
  "data": {
    "errors": [
      {
        "field": "registrationNumber",
        "message": "Registration number is required"
      },
      {
        "field": "taxId",
        "message": "Tax ID is required"
      }
    ]
  }
}

409 - Organization Already Exists:

json

{
  "code": 409,
  "message": "Organization already exists",
  "data": {
    "error": "Duplicate organization",
    "registrationNumber": "REG123456789",
    "existingOrganizationId": "org-880e8400..."
  }
}

Required Fields

Field	Required	Description
`legalName`	✅	Official legal name
`businessType`	✅	B2B, B2C, etc.
`registrationNumber`	✅	Company registration number
`taxId`	✅	Tax identification number
`incorporationDate`	✅	Date of incorporation
`registeredAddress`	✅	Official registered address
`contactEmail`	✅	Primary contact email
`vatNumber`	Conditional	Required if VAT registered

Ownership Validation

Representatives’ ownership must total 100%:

javascript

function validateOwnership(representatives) {
  const totalOwnership = representatives.reduce(
    (sum, rep) => sum + rep.ownershipPercentage, 0
  );
  
  if (totalOwnership !== 100) {
    throw new ValidationError(
      `Total ownership must equal 100%. Current: ${totalOwnership}%`
    );
  }
}

Default Admin Creation

After organization creation, a Kafka event triggers automatic admin user creation:

OrganizationCreatedEvent → Create Admin User
                         → Send Activation Email

The default admin receives:

Email: contactEmail from registration
Roles: ADMIN, ADMIN_USER
Status: PENDING_ACTIVATION

Get Organization Details

Endpoint: GET /api/v2.1/customer/organization/{organizationId}

Headers:

http

Authorization: Bearer {jwt-token}

Status: 200 OK

json

{
  "code": 200,
  "message": "Organization retrieved successfully",
  "data": {
    "id": "org-880e8400-e29b-41d4-a716-446655440110",
    "legalName": "Acme Corporation Limited",
    "status": "PENDING_VERIFICATION",
    "employees": [],
    "directors": [],
    "shareholders": [],
    "verificationStatus": null,
    "activationStatus": null,
    "wallet": {
      "id": "wallet-aa0e8400...",
      "status": "INACTIVE",
      "iban": null
    },
    "metadata": {
      "personnelCount": {
        "employees": 0,
        "directors": 0,
        "shareholders": 0
      },
      "complianceStatus": {
        "verification": "NOT_STARTED",
        "consents": "NOT_STARTED",
        "activation": "NOT_ELIGIBLE"
      }
    }
  }
}

Next Step

After registration, proceed to Phase 2: Personnel Management to add directors, shareholders, and employees.

Phase 2: Personnel Management

Add directors, shareholders, and employees