External ID and Metadata

The Issuing API supports two optional fields for enhancing resource management: xid (external identifier) and xmetadata (external metadata). These fields allow you to attach your own identifiers and structured data to resources, simplifying integration and eliminating the need for complex ID mapping between your platform and UTGL.

Overview

Both xid and xmetadata are optional fields that can be attached to resources during creation or updates. They are included in all API responses and webhook events, making them ideal for:

Resource Mapping - Map UTGL resources to your internal systems
Context Storage - Store additional structured information about resources
Search and Query - Use xid to search for resources
Integration Tracking - Track resources across systems without maintaining separate mapping tables

External Identifier (xid)

The xid field allows you to attach your own unique identifier to resources created through the Issuing API.

Characteristics

Type: String
Max Length: 256 characters
Uniqueness: Must be unique across all resources created under your account
Visibility: Visible in the UTGL platform user interface
Included In: All API responses and webhook events

Use Cases

Internal System Mapping - Map UTGL resource IDs to your internal database IDs
Cross-Platform References - Reference resources using your own identifiers
Search and Filtering - Query resources by your external identifiers
Audit Trails - Track resources using your own reference system

Example Usage

Creating a resource with xid:

{
  "name": "My Account",
  "currency": "USD",
  "xid": "account-12345-internal-ref"
}

Response includes xid:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "xid": "account-12345-internal-ref",
  "name": "My Account",
  "currency": "USD"
}

Webhook event includes xid:

{
  "event": "account.created",
  "id": "evt_abc123",
  "time": "2025-01-15T10:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "xid": "account-12345-internal-ref",
    "name": "My Account"
  }
}

Best Practices

Use Consistent Format - Establish a consistent naming convention for your xid values
Include Context - Use prefixes or patterns that indicate resource type (e.g., account-, card-, transfer-)
Avoid Sensitive Data - Don’t include sensitive information in xid values
Keep It Readable - Use human-readable identifiers for easier debugging and support

External Metadata (xmetadata)

The xmetadata field allows you to attach structured key-value pairs to resources for storing additional context and information.

Characteristics

Type: Object with string key-value pairs
Max Keys: 25 key-value pairs per resource
Key Constraints:
- Max length: 40 characters
- Must be strings
Value Constraints:
- Max length: 1024 characters per value
- Must be strings or arrays of strings
Nested Objects: Not supported
Visibility: Visible in the UTGL platform user interface

Schema Definition

{
  "xmetadata": {
    "key1": "value1",
    "key2": ["value2.1", "value2.2"],
    "key3": "value3"
  }
}

Each value can be either:

A string (up to 1024 characters)
An array of strings (each string up to 1024 characters)

Use Cases

Routing Information - Store SMS or OTP routing preferences for cards
Business Context - Attach department, project, or cost center information
Integration Data - Store references to related resources in your system
Custom Attributes - Add domain-specific metadata for your use case
Workflow State - Track processing status or workflow stages

Example Usage

Creating a card with metadata:

{
  "cardAccountId": "acc_1234567890",
  "cardholder": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "xmetadata": {
    "sms_routing": "twilio",
    "department": "sales",
    "cost_center": "CC-2024-Q1",
    "tags": ["premium", "vip"]
  }
}

Response includes merged metadata: If both parent and child resources have metadata, they are merged:

{
  "id": "card_abc123",
  "cardAccountId": "acc_1234567890",
  "xmetadata": {
    "account_department": "finance",
    "card_sms_routing": "twilio",
    "card_department": "sales",
    "cost_center": "CC-2024-Q1"
  }
}

Querying with metadata: Metadata is included in all resource responses, allowing you to filter and process resources based on metadata values:

{
  "id": "card_abc123",
  "xid": "card-internal-456",
  "xmetadata": {
    "department": "sales",
    "region": "us-east"
  }
}

Metadata Merging

When a parent resource (e.g., card account) and child resource (e.g., card) both contain metadata, the metadata is merged in responses: Parent Resource (Card Account):

{
  "id": "acc_123",
  "xmetadata": {
    "account_type": "premium",
    "department": "finance"
  }
}

Child Resource (Card):

{
  "id": "card_456",
  "cardAccountId": "acc_123",
  "xmetadata": {
    "card_type": "virtual",
    "department": "sales"
  }
}

Merged Response:

{
  "id": "card_456",
  "cardAccountId": "acc_123",
  "xmetadata": {
    "account_type": "premium",
    "account_department": "finance",
    "card_type": "virtual",
    "card_department": "sales"
  }
}

Metadata Merging: When metadata keys conflict between parent and child resources, both values are preserved with prefixed keys to avoid overwriting.

Limitations

Constraint	Limit
Maximum keys	25 key-value pairs
Key length	40 characters
Value length (string)	1024 characters
Value length (array item)	1024 characters per item
Nested objects	Not supported

Best Practices

Use Descriptive Keys - Choose clear, descriptive key names that indicate purpose
Keep Values Concise - Stay within the 1024 character limit per value
Avoid Sensitive Data - Never store sensitive information in metadata
Plan Key Names - Establish a naming convention to avoid conflicts
Document Your Schema - Document your metadata structure for your team

Security Considerations

Never store sensitive information in xid or xmetadata fields.Examples of what NOT to store:

Personal Identifiable Information (PII)
Bank account numbers
Card details (PAN, CVV, expiry)
Passwords or credentials
API keys or secrets
Social Security Numbers
Authentication tokens

These fields are:

Visible in the UTGL platform user interface
Included in all API responses
Included in all webhook events
Accessible to anyone with API access to your account

Use these fields only for non-sensitive operational data, routing information, and integration references.

Code Examples

JavaScript/TypeScript

// Create account with xid and metadata
const createAccount = async () => {
  const response = await fetch('https://access.utgl.io/v1/accounts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      name: 'Business Account',
      currency: 'USD',
      xid: 'account-internal-ref-12345',
      xmetadata: {
        department: 'operations',
        cost_center: 'CC-2024-Q1',
        region: 'us-east'
      }
    })
  });
  
  const account = await response.json();
  console.log('Created account:', account.xid);
  console.log('Metadata:', account.xmetadata);
};

Python

import requests

def create_account():
    url = 'https://access.utgl.io/v1/accounts'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}'
    }
    data = {
        'name': 'Business Account',
        'currency': 'USD',
        'xid': 'account-internal-ref-12345',
        'xmetadata': {
            'department': 'operations',
            'cost_center': 'CC-2024-Q1',
            'region': 'us-east'
        }
    }
    
    response = requests.post(url, json=data, headers=headers)
    account = response.json()
    print(f'Created account: {account["xid"]}')
    print(f'Metadata: {account["xmetadata"]}')

Using xid for Resource Lookup

// Search for account by xid
const findAccountByXid = async (xid) => {
  const response = await fetch(
    `https://access.utgl.io/v1/accounts?xid=${encodeURIComponent(xid)}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  const accounts = await response.json();
  return accounts.data.find(acc => acc.xid === xid);
};

Common Patterns

Pattern 1: Internal Reference Mapping

Use xid to maintain a direct mapping between your internal IDs and UTGL resources:

// Store mapping: internal_id -> utgl_resource_id
const resourceMap = {
  'internal-account-123': '550e8400-e29b-41d4-a716-446655440000',
  'internal-card-456': '660e8400-e29b-41d4-a716-446655440001'
};

// Or use xid directly
const account = await createAccount({
  name: 'Account',
  xid: 'internal-account-123' // Use your internal ID
});

Pattern 2: Routing Configuration

Store routing preferences in metadata:

{
  "xmetadata": {
    "sms_provider": "twilio",
    "sms_phone": "+1234567890",
    "email_provider": "sendgrid",
    "email_address": "[email protected]"
  }
}

Pattern 3: Business Context

Attach business context to resources:

{
  "xmetadata": {
    "department": "sales",
    "region": "us-east",
    "cost_center": "CC-2024-Q1",
    "project_id": "project-abc-123"
  }
}

Pattern 4: Integration References

Store references to related resources in your system:

{
  "xmetadata": {
    "user_id": "user-12345",
    "order_id": "order-67890",
    "subscription_id": "sub-abc-def"
  }
}

API Endpoints Supporting xid and xmetadata

Most POST endpoints support xid and xmetadata:

Account creation
Card account creation
Card issuance
Transfer creation
Payout creation
Fee charging
And more…

Check individual endpoint documentation in the API Reference for specific support.

Troubleshooting

Common Issues

Issue: xid already exists

Solution: Ensure xid values are unique across all resources. Use a prefix or namespace to avoid conflicts.

Issue: Metadata key too long

Solution: Keep key names under 40 characters. Use abbreviations if necessary.

Issue: Metadata value too long

Solution: Split long values into multiple keys or use arrays for related values.

Issue: Too many metadata keys

Solution: Consolidate related information into fewer keys. Maximum is 25 key-value pairs.

Issue: Metadata not appearing in response

Solution: Verify metadata was included in the creation request. Check that you’re reading the correct resource response.

Next Steps

Review API Reference for endpoint-specific xid and xmetadata support
Learn about Webhook Events to see how metadata is included in events
Explore Resource Management for more integration patterns

Introduction

Authentication & Security

API Fundamentals

Overview

External Identifier (xid)

Characteristics

Use Cases

Example Usage

Best Practices

External Metadata (xmetadata)

Characteristics

Schema Definition

Use Cases

Example Usage

Metadata Merging

Limitations

Best Practices

Security Considerations

Code Examples

JavaScript/TypeScript

Python

Using xid for Resource Lookup

Common Patterns

Pattern 1: Internal Reference Mapping

Pattern 2: Routing Configuration

Pattern 3: Business Context

Pattern 4: Integration References

API Endpoints Supporting xid and xmetadata

Troubleshooting

Common Issues

Next Steps

Introduction

Authentication & Security

API Fundamentals

​Overview

​External Identifier (xid)

​Characteristics

​Use Cases

​Example Usage

​Best Practices

​External Metadata (xmetadata)

​Characteristics

​Schema Definition

​Use Cases

​Example Usage

​Metadata Merging

​Limitations

​Best Practices

​Security Considerations

​Code Examples

​JavaScript/TypeScript

​Python

​Using xid for Resource Lookup

​Common Patterns

​Pattern 1: Internal Reference Mapping

​Pattern 2: Routing Configuration

​Pattern 3: Business Context

​Pattern 4: Integration References

​API Endpoints Supporting xid and xmetadata

​Troubleshooting

​Common Issues

​Next Steps

Overview

External Identifier (xid)

Characteristics

Use Cases

Example Usage

Best Practices

External Metadata (xmetadata)

Characteristics

Schema Definition

Use Cases

Example Usage

Metadata Merging

Limitations

Best Practices

Security Considerations

Code Examples

JavaScript/TypeScript

Python

Using xid for Resource Lookup

Common Patterns

Pattern 1: Internal Reference Mapping

Pattern 2: Routing Configuration

Pattern 3: Business Context

Pattern 4: Integration References

API Endpoints Supporting xid and xmetadata

Troubleshooting

Common Issues

Next Steps