URL: /baas/api/integration/flows/organization-customer/registration

---
title: 'Phase 1: Organization Registration'
description: 'Register organization with legal information and representatives'
---

# 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) |

<Info>
  **Important:** Employees, directors, and shareholders arrays in the registration request are **ignored**. Use separate endpoints to add these entities.
</Info>

---

## Register Organization

<Tabs>
  <Tab title="Request">
    **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" }
            ]
          }
        ]
      }
    }
    ```
  </Tab>
  <Tab title="Success Response">
    **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)
  </Tab>
  <Tab title="Error Responses">
    **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..."
      }
    }
    ```
  </Tab>
</Tabs>

---

## 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

<Tabs>
  <Tab title="Request">
    **Endpoint:** `GET /api/v2.1/customer/organization/{organizationId}`

    **Headers:**
    ```http
    Authorization: Bearer {jwt-token}
    ```
  </Tab>
  <Tab title="Response">
    **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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

---

## Next Step

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

<Card title="Phase 2: Personnel Management" icon="arrow-right" href="/baas/api/integration/flows/organization-customer/personnel-management">
  Add directors, shareholders, and employees
</Card>