Entity Extra Data

Entity extra data lets an institution attach institution-specific fields to supported CoreWave records without changing the core banking fields.

Use it for institution-specific values such as CRM identifiers, onboarding attributes, document references, tags, risk annotations, and nested integration payloads.

Supported Records

Entity type	Record
account	Current or savings account
casa-product	Current or savings product
corporate-customer	Corporate customer
customer	Individual customer
fixed-deposit	Fixed-deposit entry
fixed-deposit-product	Fixed-deposit product
loan	Loan entry
loan-product	Loan product
ledger	General ledger account
placement	Investment placement

The supported list is also available from:

GET /api/entity-additional-metadata/v1/supported-entity-types

Institution Portal

Institution staff can manage extra data directly from the portal:

1. Open the list page for a supported record.
2. Open the record action menu.
3. Select Extra Data.
4. Select Add field.
5. Enter a field name, choose its type, and enter its value.
6. Optionally use a section name such as crm to group related fields.
7. Select Save to replace the stored value, or Clear to delete it.

Portal users do not need to write JSON. The portal provides text, number, yes/no, and list controls. Repeated objects can be entered with sections such as documents[0] and documents[1].

General-ledger and placement rows also expose Extra Data from their action menus. Existing nested values are displayed as editable section, field-name, type, and value rows rather than raw JSON.

The API representation of portal fields remains structured JSON:

{
  "crm": {
    "customerId": "CRM-10021",
    "segment": "priority"
  },
  "tags": ["salary", "mobile"],
  "documents": [
    {
      "type": "external-reference",
      "value": "DOC-882"
    }
  ]
}

Integration API

Authenticate first using POST /api/auth/v1/authenticate, then pass the API-channel bearer token.

Create a Record With Extra Data

Supported API-channel create requests accept extra data at creation time:

Endpoint	Field
POST /api/account/v1/createcustomeraccount	customerAdditionalMetadata, accountAdditionalMetadata
POST /api/account/v1/createaccount	additionalMetadata
POST /api/account/v1/creategroupcustomerinformation	additionalMetadata
POST /api/loanaccount/v1/add	additionalMetadata
POST /api/fixeddepositaccount/v1/add	additionalMetadata

Example:

{
  "firstName": "Ada",
  "lastName": "Okafor",
  "accountName": "Ada Okafor",
  "branchCode": "1",
  "productCode": "SAV",
  "accountOfficerStaffID": "AO0001",
  "customerAdditionalMetadata": {
    "crm": {
      "customerId": "CRM-CUST-1001"
    }
  },
  "accountAdditionalMetadata": {
    "risk": {
      "segment": "priority"
    }
  }
}

Create-time metadata is stored after the record is created. When API_BYPASS_APPROVALS is disabled and the create request is queued for approval, call the metadata PUT endpoint after approval using the created record ID.

CSV Imports

The portal templates for Batch Individual Customer, Batch Account Creation, and Batch Loan Creation include optional extra-data columns.

For staff-managed imports, use columns starting with extra.:

CSV column	Stored result
extra.crmId	{ "crmId": "..." }
extra.risk.segment	{ "risk": { "segment": "..." } }

For advanced imports, use the optional additionalMetadata column with a JSON object or array. If the CSV value contains commas, quote the CSV cell normally.

Extra-data imports require direct creation. If a create-approval queue is enabled for that batch type, import the record first and add extra data after approval from the portal or metadata API.

Fetch Extra Data

curl --location '{{baseurl}}/api/entity-additional-metadata/v1/account/123' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'request-reference: metadata-read-001' \
--header 'Content-Type: application/json'

Success response:

{
  "status": true,
  "data": {
    "entityType": "account",
    "entityId": 123,
    "additionalMetadata": {
      "crm": {
        "customerId": "CRM-10021"
      }
    }
  }
}

When a record exists but has no extra data yet, additionalMetadata is returned as null.

Add or Replace Extra Data

curl --location --request PUT '{{baseurl}}/api/entity-additional-metadata/v1/account/123' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'request-reference: metadata-save-001' \
--header 'Content-Type: application/json' \
--data '{
  "additionalMetadata": {
    "crm": {
      "customerId": "CRM-10021",
      "segment": "priority"
    },
    "tags": ["salary", "mobile"]
  }
}'

PUT replaces the full stored JSON value. Fetch the current value first if your integration needs to merge individual keys.

Clear Extra Data

curl --location --request DELETE '{{baseurl}}/api/entity-additional-metadata/v1/account/123' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'request-reference: metadata-clear-001' \
--header 'Content-Type: application/json'

Validation and Security Rules

• additionalMetadata must be a JSON object or array.
• Scalar JSON values such as strings, numbers, booleans, and null are rejected by PUT.
• Use DELETE to clear an existing value.
• The compact JSON payload must not exceed 64 KB.
• Records and metadata are always scoped to the institution in the authenticated API token.
• A token cannot fetch or update another institution's metadata.
• Unsupported entity types and unknown record IDs return 404.

API Summary

Method	Endpoint	Purpose
GET	/api/entity-additional-metadata/v1/supported-entity-types	List supported record types
GET	/api/entity-additional-metadata/v1/{entityType}/{entityId}	Fetch stored extra data
PUT	/api/entity-additional-metadata/v1/{entityType}/{entityId}	Add or replace extra data
DELETE	/api/entity-additional-metadata/v1/{entityType}/{entityId}	Clear extra data