Search & metadata

Metadata

Add custom fields to a ledger, balance, transaction, identity, or balance monitor, and update them later.

meta_data is a key-value object on a ledger, balance, transaction, identity, or balance monitor. Add it when you create the record. Change it later on a ledger, balance, transaction, or identity with Update metadata.

Updating a parent also updates its children. An inflight transaction and its applied or void child share the same metadata.

Add metadata

Include meta_data in the create body. The key is the field name, and the value is what you store.

{
  "precise_amount": 102912,
  "precision": 100,
  "currency": "USD",
  "reference": "ref_00a8f264-6367-4617-abc8-e661431d3b7b",
  "source": "@Deposit_USD",
  "destination": "bln_d0cb79eb-cdc4-4a0d-af00-f5aaf15721ae",
  "allow_overdraft": true,
  "description": "Payment for services",
  "meta_data": {
    "invoice_id": "INV-12345",
    "initiated_by": "Jason Burke",
    "timestamp": "2023-10-01T12:00:00Z",
    "sender_name": "Oakley Stationeries",
    "sender_bank": "12345678901234",
    "routing_number": "123456789",
    "source_country": "United States"
  }
}

A later read of that record includes meta_data with the rest of the fields. Use the record’s GET endpoint, or the Filter API.

{
  "id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "source": "@FundingPool",
  "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
  "reference": "ref_001adcfgf",
  "amount": 750,
  "precision": 100,
  "precise_amount": 75000,
  "currency": "USD",
  "description": "Fund with starting balance amount",
  "allow_overdraft": true,
  "status": "QUEUED",
  "created_at": "2024-12-21T01:36:46.997063436Z",
  "meta_data": {
    "sender_name": "John Doe",
    "sender_account": "00000000000"
  }
}

Update metadata

Send POST /{id}/metadata. {id} is the ledger, balance, transaction, or identity you already created. A scoped key needs metadata:write. See Scopes.

{
  "meta_data": {
    "first_name": "Jason"
  }
}

curl -X POST "http://localhost:5001/{id}/metadata" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "meta_data": {
      "last_name": "Brooks",
      "verification_status": "Pending"
    }
  }'

const response = await blnk.Metadata.update(
  '{id}',
  {
    meta_data: {
      last_name: 'Brooks',
      verification_status: 'Pending',
    },
  },
);

meta, _, _ := client.Metadata.UpdateMetadata(
  "{id}",
  blnkgo.UpdateMetaDataRequest{
    MetaData: blnkgo.MetaData{
      "last_name":            "Brooks",
      "verification_status": "Pending",
    },
  },
)

response = blnk.metadata.update(
  "{id}",
  {
    "meta_data": {
      "last_name": "Brooks",
      "verification_status": "Pending",
    },
  },
)

ApiResponse<JsonNode> response = blnk.metadata().update(
    "{id}",
    UpdateMetadataData.create()
        .metaData(Map.of(
            "last_name", "Brooks",
            "verification_status", "Pending"
        )));

{
  "meta_data": {
    "first_name": "Jason",
    "last_name": "Brooks",
    "verification_status": "Pending"
  }
}

curl -X POST "http://localhost:5001/{id}/metadata" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "meta_data": {
      "verification_status": "Approved"
    }
  }'

const response = await blnk.Metadata.update(
  '{id}',
  {
    meta_data: {
      verification_status: 'Approved',
    },
  },
);

meta, _, _ := client.Metadata.UpdateMetadata(
  "{id}",
  blnkgo.UpdateMetaDataRequest{
    MetaData: blnkgo.MetaData{
      "verification_status": "Approved",
    },
  },
)

response = blnk.metadata.update(
  "{id}",
  {
    "meta_data": {
      "verification_status": "Approved",
    },
  },
)

ApiResponse<JsonNode> response = blnk.metadata().update(
    "{id}",
    UpdateMetadataData.create()
        .metaData(Map.of("verification_status", "Approved")));

{
  "meta_data": {
    "first_name": "Jason",
    "last_name": "Brooks",
    "verification_status": "Approved"
  }
}