Update Metadata

Endpoint

POST /:entity-id/metadata

Updates the metadata for any Blnk entity including ledgers, transactions, balances, and identities. The entity type is automatically determined from the entity ID prefix.

Path Parameters

entity-id

string

required

The unique identifier of the entity to update. The entity type is determined by the ID prefix:

ldg_*: Ledger
txn_*: Transaction
bln_*: Balance
idt_*: Identity
acc_*: Account

Request Body

meta_data

object

required

An object containing key-value pairs to store as metadata. This will merge with existing metadata, updating matching keys and adding new ones

Response

metadata

object

The complete updated metadata object after merging

Example Requests

Update Transaction Metadata

curl -X POST "https://api.blnk.io/txn_123abc/metadata" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meta_data": {
      "customer_name": "John Doe",
      "invoice_id": "INV-2024-001",
      "payment_method": "credit_card"
    }
  }'

{
  "meta_data": {
    "customer_name": "John Doe",
    "invoice_id": "INV-2024-001",
    "payment_method": "credit_card"
  }
}

Update Balance Metadata

{
  "meta_data": {
    "account_type": "premium",
    "last_reviewed": "2024-03-04",
    "risk_score": 25
  }
}

Update Ledger Metadata

{
  "meta_data": {
    "department": "sales",
    "region": "us-west",
    "cost_center": "CC-1001"
  }
}

Update Identity Metadata

{
  "meta_data": {
    "kyc_status": "verified",
    "kyc_date": "2024-03-04T12:00:00Z",
    "risk_level": "low",
    "customer_tier": "gold"
  }
}

Example Response

{
  "metadata": {
    "customer_name": "John Doe",
    "invoice_id": "INV-2024-001",
    "payment_method": "credit_card",
    "created_by": "api",
    "source": "web_app"
  }
}

Merging Behavior

Metadata updates are merged with existing metadata:

Initial State

{
  "customer_name": "John Doe",
  "invoice_id": "INV-2024-001"
}

Update Request

{
  "meta_data": {
    "invoice_id": "INV-2024-002",
    "payment_method": "credit_card"
  }
}

Final State

{
  "customer_name": "John Doe",
  "invoice_id": "INV-2024-002",
  "payment_method": "credit_card"
}

Note:

invoice_id was updated
payment_method was added
customer_name remained unchanged

Error Responses

error

string

Error message describing what went wrong

Common Errors

400 Bad Request: Entity ID is missing or request body is invalid
404 Not Found: Entity not found
500 Internal Server Error: Failed to update metadata

Use Cases

Tag Transactions

Add tags and categories to transactions:

const tagTransaction = async (transactionId, tags) => {
  return await fetch(`https://api.blnk.io/${transactionId}/metadata`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meta_data: {
        tags: tags.join(','),
        category: tags[0],
        tagged_at: new Date().toISOString()
      }
    })
  }).then(r => r.json());
};

// Usage
await tagTransaction('txn_123abc', ['revenue', 'subscription', 'monthly']);

Track Processing Status

Update metadata to track processing stages:

const updateProcessingStatus = async (transactionId, status, details) => {
  return await fetch(`https://api.blnk.io/${transactionId}/metadata`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meta_data: {
        processing_status: status,
        processing_details: details,
        last_updated: new Date().toISOString()
      }
    })
  }).then(r => r.json());
};

// Usage
await updateProcessingStatus('txn_123abc', 'completed', 'Payment processed successfully');

Store Custom References

Link Blnk entities to external systems:

const linkToExternalSystem = async (entityId, externalRefs) => {
  return await fetch(`https://api.blnk.io/${entityId}/metadata`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meta_data: {
        external_id: externalRefs.id,
        external_system: externalRefs.system,
        external_url: externalRefs.url,
        linked_at: new Date().toISOString()
      }
    })
  }).then(r => r.json());
};

// Usage
await linkToExternalSystem('txn_123abc', {
  id: 'STRIPE-ch_3abc123',
  system: 'stripe',
  url: 'https://dashboard.stripe.com/payments/ch_3abc123'
});

Add Compliance Information

Store compliance and audit data:

const addComplianceData = async (identityId, complianceInfo) => {
  return await fetch(`https://api.blnk.io/${identityId}/metadata`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meta_data: {
        kyc_status: complianceInfo.kycStatus,
        kyc_provider: complianceInfo.provider,
        kyc_date: complianceInfo.date,
        aml_check: complianceInfo.amlPassed,
        sanctions_check: complianceInfo.sanctionsPassed,
        verified_by: complianceInfo.verifiedBy
      }
    })
  }).then(r => r.json());
};

// Usage
await addComplianceData('idt_123abc', {
  kycStatus: 'verified',
  provider: 'Onfido',
  date: '2024-03-04T12:00:00Z',
  amlPassed: true,
  sanctionsPassed: true,
  verifiedBy: 'compliance_team'
});

Track Analytics Data

Store analytics and metrics:

const updateAnalytics = async (balanceId, analytics) => {
  return await fetch(`https://api.blnk.io/${balanceId}/metadata`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      meta_data: {
        monthly_volume: analytics.monthlyVolume,
        transaction_count: analytics.txnCount,
        avg_transaction_size: analytics.avgSize,
        last_analyzed: new Date().toISOString()
      }
    })
  }).then(r => r.json());
};

Metadata Best Practices

Use Consistent Naming

Adopt a consistent naming convention:

// Good: snake_case
{
  "customer_name": "John Doe",
  "invoice_id": "INV-001",
  "payment_method": "card"
}

// Avoid: Mixed conventions
{
  "customerName": "John Doe",
  "invoice_id": "INV-001",
  "PaymentMethod": "card"
}

Store Searchable Data

Keep data you’ll search for in metadata:

{
  "customer_email": "john@example.com",
  "product_sku": "PROD-123",
  "campaign_id": "SPRING2024"
}

Include Timestamps

Track when metadata was added or updated:

{
  "status": "completed",
  "status_updated_at": "2024-03-04T12:00:00Z",
  "updated_by": "user_123"
}

Avoid Large Values

Don’t store large objects or arrays:

// Good: Store references
{
  "document_id": "DOC-123",
  "document_url": "https://docs.example.com/DOC-123"
}

// Avoid: Large embedded data
{
  "document_content": "...large base64 string..."
}

Use Structured Data

Organize related data:

{
  "shipping": {
    "address": "123 Main St",
    "city": "New York",
    "tracking_number": "TRK-123"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Supported Entity Types

Entity Type	ID Prefix	Example ID	Use Cases
Ledger	`ldg_`	`ldg_123abc`	Department, region, cost center
Transaction	`txn_`	`txn_456def`	Invoice ID, customer info, tags
Balance	`bln_`	`bln_789ghi`	Account type, risk score, limits
Identity	`idt_`	`idt_012jkl`	KYC status, compliance data
Account	`acc_`	`acc_345mno`	External IDs, custom flags

Security Considerations

Don’t store sensitive data: Avoid storing passwords, full credit card numbers, or SSNs in metadata
Use encryption: For sensitive information, encrypt before storing
Validate input: Sanitize metadata values to prevent injection attacks
Limit size: Keep metadata objects reasonably sized (< 10KB)
Audit changes: Track who updates metadata and when

Overview

Ledgers

Balances

Balance Monitors

Transactions

Identities

Accounts

Reconciliation

Search

Webhooks

API Keys

Metadata

Backup

​Endpoint

​Path Parameters

​Request Body

​Response

​Example Requests

​Update Transaction Metadata

​Update Balance Metadata

​Update Ledger Metadata

​Update Identity Metadata

​Example Response

​Merging Behavior

​Initial State

​Update Request

​Final State

​Error Responses

​Common Errors

​Use Cases

​Tag Transactions

​Track Processing Status

​Store Custom References

​Add Compliance Information

​Track Analytics Data

​Metadata Best Practices

​Use Consistent Naming

​Store Searchable Data

​Include Timestamps

​Avoid Large Values

​Use Structured Data

​Supported Entity Types

​Security Considerations

Build docs developers (and LLMs) love