Get Mapping

Retrieve a specific mapping between a Kruncher entity and an external provider ID. Use this to verify mappings exist, get bidirectional ID conversions, or integrate with external systems.

Endpoints

Option 1: Get All Mappings (Client-side Filtering)

GET https://api.kruncher.ai/api/integration/map/all

Fetches all mappings. Filter results client-side for your specific lookup.

Option 2: Find by External ID (Server-side Query)

GET https://api.kruncher.ai/api/integration/map/externalid?externalId=<external-id>

Returns mapping for a specific external system ID. Direct server-side lookup.

Option 3: Find by Kruncher ID (Server-side Query)

GET https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=<kruncher-id>

Returns mapping for a specific Kruncher internal ID. Direct server-side lookup.

Recommendation: Use query parameter endpoints (Options 2 & 3) for single lookups. Use Option 1 with client-side filtering when you need to batch lookup multiple mappings or filter by provider.

Headers

Header	Required	Description
`Authorization`	Yes	Your API key (format: `YOUR_API_KEY`)
`Content-Type`	No	Optional `application/json`

Query Parameters

externalId Endpoint

Parameter	Required	Description
`externalId`	Yes	The external system ID to lookup

Example: /api/integration/map/externalid?externalId=affinity_org_456

kruncherId Endpoint

Parameter	Required	Description
`kruncherId`	Yes	The Kruncher internal ID to lookup

Example: /api/integration/map/kruncherid?kruncherId=proj_123

Use Cases

When to Get Mappings

Before Syncing: Verify mapping exists before syncing data
ID Conversion: Convert between Kruncher IDs and external IDs
Mapping Verification: Confirm mapping is active
Integration Checks: Ensure sync is configured
Dependency Lookup: Find related entities in external systems

Quick Start Examples

Get Mapping by External ID

CODE

curl -X GET "https://api.kruncher.ai/api/integration/map/externalid?externalId=affinity_org_456" \
  -H "Authorization: YOUR_API_KEY_HERE"

Response:

CODE

{
  "data": {
    "id": "mapping_abc123",
    "entityType": "company",
    "provider": "affinity",
    "kruncherId": "proj_123",
    "externalId": "affinity_org_456",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Get Mapping by Kruncher ID

CODE

curl -X GET "https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=proj_123" \
  -H "Authorization: YOUR_API_KEY_HERE"

Response:

CODE

{
  "data": {
    "id": "mapping_abc123",
    "entityType": "company",
    "provider": "affinity",
    "kruncherId": "proj_123",
    "externalId": "affinity_org_456",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Code Examples

JavaScript/TypeScript

Query: By Kruncher ID

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
async function getMappingByKruncherId(kruncherId) {
  const url = `${BASE_URL}/integration/map/kruncherid?kruncherId=${encodeURIComponent(kruncherId)}`;
  
  const response = await fetch(url, {
    headers: {
      "Authorization": `${API_KEY}`,
      "Content-Type": "application/json"
    }
  });
 
  if (!response.ok) {
    if (response.status === 404) {
      return null;
    }
    throw new Error(`Failed to fetch mapping: ${response.statusText}`);
  }
 
  const result = await response.json();
  return result.data || null;
}
 
// Usage
const mapping = await getMappingByKruncherId("proj_123");
 
if (mapping) {
  console.log("Mapping found:", mapping);
  console.log("Provider:", mapping.provider);
  console.log("External ID:", mapping.externalId);
  console.log("Created:", mapping.createdAt);
} else {
  console.log("No mapping found for this Kruncher ID");
}

Result: Direct server-side lookup by Kruncher ID. Faster for single lookups.

Query: By External ID

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
async function getMappingByExternalId(externalId) {
  const url = `${BASE_URL}/integration/map/externalid?externalId=${encodeURIComponent(externalId)}`;
  
  const response = await fetch(url, {
    headers: {
      "Authorization": `${API_KEY}`,
      "Content-Type": "application/json"
    }
  });
 
  if (!response.ok) {
    if (response.status === 404) {
      return null;
    }
    throw new Error(`Failed to fetch mapping: ${response.statusText}`);
  }
 
  const result = await response.json();
  return result.data || null;
}
 
// Usage
const mapping = await getMappingByExternalId("affinity_org_456");
 
if (mapping) {
  console.log("Kruncher ID:", mapping.kruncherId);
  console.log("Entity Type:", mapping.entityType);
  console.log("Mapping:", mapping);
} else {
  console.log("No mapping found for this external ID");
}

Result: Direct server-side lookup by external ID. Best for single lookups.

Get All + Filter

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
async function getMappingByKruncherIdFiltered(kruncherId, provider) {
  const response = await fetch(`${BASE_URL}/integration/map/all`, {
    headers: {
      "Authorization": `${API_KEY}`,
      "Content-Type": "application/json"
    }
  });
 
  if (!response.ok) {
    throw new Error(`Failed to fetch mappings: ${response.statusText}`);
  }
 
  const result = await response.json();
  const mapping = result.data.find(m => 
    m.kruncherId === kruncherId && 
    m.provider === provider
  );
 
  return mapping || null;
}
 
async function getMappingsByExternalIds(externalIds, provider) {
  const response = await fetch(`${BASE_URL}/integration/map/all`, {
    headers: {
      "Authorization": `${API_KEY}`,
      "Content-Type": "application/json"
    }
  });
 
  if (!response.ok) {
    throw new Error(`Failed to fetch mappings: ${response.statusText}`);
  }
 
  const result = await response.json();
  const externalIdSet = new Set(externalIds);
  
  return result.data.filter(m => 
    externalIdSet.has(m.externalId) && 
    m.provider === provider
  );
}
 
// Usage - single lookup with provider filter
const mapping = await getMappingByKruncherIdFiltered("proj_123", "affinity");
 
if (mapping) {
  console.log("Mapping found:", mapping);
}
 
// Usage - batch lookup
const externalIds = ["affinity_org_1", "affinity_org_2", "affinity_org_3"];
const mappings = await getMappingsByExternalIds(externalIds, "affinity");
 
console.log(`Found ${mappings.length} mappings`);
mappings.forEach(m => {
  console.log(`${m.externalId} → ${m.kruncherId}`);
});

Result: Use this when you need provider filtering or batch lookups.

Advanced Lookup

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
class MappingLookup {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = BASE_URL;
    this.mappingCache = null;
    this.lastFetch = null;
    this.cacheDuration = 600000; // 10 minutes
    
    // Create indices for fast lookup
    this.byKruncherId = {};
    this.byExternalId = {};
    this.byProvider = {};
  }
 
  async ensureMappingsLoaded(forceRefresh = false) {
    const now = Date.now();
 
    if (!forceRefresh && this.mappingCache && (now - this.lastFetch < this.cacheDuration)) {
      return;
    }
 
    const response = await fetch(`${this.baseURL}/integration/map/all`, {
      headers: {
        "Authorization": `${this.apiKey}`,
        "Content-Type": "application/json"
      }
    });
 
    if (!response.ok) {
      throw new Error(`Failed to fetch mappings: ${response.statusText}`);
    }
 
    const result = await response.json();
    this.mappingCache = result.data;
    this.lastFetch = now;
 
    this.buildIndices();
  }
 
  buildIndices() {
    this.byKruncherId = {};
    this.byExternalId = {};
    this.byProvider = {};
 
    for (const mapping of this.mappingCache) {
      // Index by Kruncher ID + provider
      const kruncherKey = `${mapping.kruncherId}:${mapping.provider}`;
      this.byKruncherId[kruncherKey] = mapping;
 
      // Index by external ID + provider
      const externalKey = `${mapping.externalId}:${mapping.provider}`;
      this.byExternalId[externalKey] = mapping;
 
      // Index by provider
      if (!this.byProvider[mapping.provider]) {
        this.byProvider[mapping.provider] = [];
      }
      this.byProvider[mapping.provider].push(mapping);
    }
  }
 
  async getMapping(kruncherId, provider, forceRefresh = false) {
    await this.ensureMappingsLoaded(forceRefresh);
    const key = `${kruncherId}:${provider}`;
    return this.byKruncherId[key] || null;
  }
 
  async getMappingByExternal(externalId, provider, forceRefresh = false) {
    await this.ensureMappingsLoaded(forceRefresh);
    const key = `${externalId}:${provider}`;
    return this.byExternalId[key] || null;
  }
 
  async getExternalId(kruncherId, provider) {
    const mapping = await this.getMapping(kruncherId, provider);
    return mapping?.externalId || null;
  }
 
  async getKruncherId(externalId, provider) {
    const mapping = await this.getMappingByExternal(externalId, provider);
    return mapping?.kruncherId || null;
  }
 
  async getMappingsForProvider(provider) {
    await this.ensureMappingsLoaded();
    return this.byProvider[provider] || [];
  }
 
  async isMapped(kruncherId, provider) {
    const mapping = await this.getMapping(kruncherId, provider);
    return mapping !== null;
  }
 
  async getMappingInfo(kruncherId, provider) {
    const mapping = await this.getMapping(kruncherId, provider);
    
    if (!mapping) {
      return {
        found: false,
        message: `No mapping found for ${kruncherId} → ${provider}`
      };
    }
 
    return {
      found: true,
      mapping,
      externalId: mapping.externalId,
      createdAt: mapping.createdAt,
      updatedAt: mapping.updatedAt,
      ageInDays: Math.floor((Date.now() - new Date(mapping.createdAt)) / (1000 * 60 * 60 * 24))
    };
  }
 
  clearCache() {
    this.mappingCache = null;
    this.lastFetch = null;
    this.byKruncherId = {};
    this.byExternalId = {};
    this.byProvider = {};
  }
}
 
// Usage examples
const lookup = new MappingLookup("YOUR_API_KEY_HERE");
 
// Get mapping by Kruncher ID
const mapping = await lookup.getMapping("proj_123", "affinity");
console.log("Mapping:", mapping);
 
// Get external ID
const externalId = await lookup.getExternalId("proj_123", "affinity");
console.log("External ID:", externalId);
 
// Get Kruncher ID
const kruncherId = await lookup.getKruncherId("affinity_org_456", "affinity");
console.log("Kruncher ID:", kruncherId);
 
// Check if mapped
const isMapped = await lookup.isMapped("proj_123", "affinity");
console.log("Is mapped:", isMapped);
 
// Get detailed info
const info = await lookup.getMappingInfo("proj_123", "affinity");
console.log("Info:", info);
 
// Get all mappings for provider
const affinityMappings = await lookup.getMappingsForProvider("affinity");
console.log("Affinity mappings:", affinityMappings.length);

Result: Indexed lookup with caching for fast repeated queries.

Python

Query: By Kruncher ID

CODE

import requests
from typing import Optional, Dict
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
def get_mapping_by_kruncher_id(kruncher_id: str) -> Optional[Dict]:
    """Get mapping by Kruncher ID using server-side lookup."""
    url = f"{BASE_URL}/integration/map/kruncherid"
    
    headers = {
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    }
    
    params = {
        "kruncherId": kruncher_id
    }
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 404:
        return None
    
    response.raise_for_status()
    result = response.json()
    
    return result.get('data')
 
# Usage
mapping = get_mapping_by_kruncher_id("proj_123")
 
if mapping:
    print(f"Found mapping: {mapping}")
    print(f"Provider: {mapping['provider']}")
    print(f"External ID: {mapping['externalId']}")
    print(f"Created: {mapping['createdAt']}")
else:
    print("No mapping found for this Kruncher ID")

Result: Direct server-side lookup by Kruncher ID. Faster for single lookups.

Query: By External ID

CODE

import requests
from typing import Optional, Dict
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
def get_mapping_by_external_id(external_id: str) -> Optional[Dict]:
    """Get mapping by external ID using server-side lookup."""
    url = f"{BASE_URL}/integration/map/externalid"
    
    headers = {
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    }
    
    params = {
        "externalId": external_id
    }
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 404:
        return None
    
    response.raise_for_status()
    result = response.json()
    
    return result.get('data')
 
# Usage
mapping = get_mapping_by_external_id("affinity_org_456")
 
if mapping:
    print(f"Kruncher ID: {mapping['kruncherId']}")
    print(f"Entity Type: {mapping['entityType']}")
    print(f"Mapping: {mapping}")
else:
    print("No mapping found for this external ID")

Result: Direct server-side lookup by external ID. Best for single lookups.

Get All + Filter

CODE

import requests
from typing import Optional, Dict, List, Set
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
def get_mapping_by_kruncher_id_filtered(kruncher_id: str, provider: str) -> Optional[Dict]:
    """Get mapping by Kruncher ID with provider filtering."""
    url = f"{BASE_URL}/integration/map/all"
    
    headers = {
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    
    result = response.json()
    
    for mapping in result.get('data', []):
        if mapping['kruncherId'] == kruncher_id and mapping['provider'] == provider:
            return mapping
    
    return None
 
def get_mappings_by_external_ids(external_ids: List[str], provider: str) -> List[Dict]:
    """Get multiple mappings by external IDs."""
    url = f"{BASE_URL}/integration/map/all"
    
    headers = {
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    
    result = response.json()
    external_id_set = set(external_ids)
    
    mappings = [
        m for m in result.get('data', [])
        if m['externalId'] in external_id_set and m['provider'] == provider
    ]
    
    return mappings
 
# Usage - single lookup with provider filter
mapping = get_mapping_by_kruncher_id_filtered("proj_123", "affinity")
 
if mapping:
    print(f"Found mapping: {mapping}")
 
# Usage - batch lookup
external_ids = ["affinity_org_1", "affinity_org_2", "affinity_org_3"]
mappings = get_mappings_by_external_ids(external_ids, "affinity")
 
print(f"Found {len(mappings)} mappings")
for m in mappings:
    print(f"  {m['externalId']} → {m['kruncherId']}")

Result: Use this when you need provider filtering or batch lookups.

Advanced Lookup

CODE

import requests
import time
from typing import Dict, Optional, List
from datetime import datetime, timedelta
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
class MappingLookup:
    """Efficient mapping lookup with indexing and caching."""
    
    def __init__(self, api_key: str = API_KEY, cache_ttl: int = 600):
        self.api_key = api_key
        self.base_url = BASE_URL
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"{api_key}",
            "Content-Type": "application/json"
        })
        
        self.mappings_cache = None
        self.last_fetch = None
        self.cache_ttl = cache_ttl
        
        # Indices for fast lookup
        self.by_kruncher_id = {}
        self.by_external_id = {}
        self.by_provider = {}
    
    async def ensure_loaded(self, force_refresh: bool = False) -> None:
        """Ensure mappings are loaded and up to date."""
        now = time.time()
        
        if not force_refresh and self.mappings_cache and self.last_fetch:
            if (now - self.last_fetch) < self.cache_ttl:
                return
        
        response = self.session.get(f"{self.base_url}/integration/map/all")
        response.raise_for_status()
        
        result = response.json()
        self.mappings_cache = result.get('data', [])
        self.last_fetch = now
        
        self.build_indices()
    
    def build_indices(self) -> None:
        """Build lookup indices for fast access."""
        self.by_kruncher_id = {}
        self.by_external_id = {}
        self.by_provider = {}
        
        for mapping in self.mappings_cache:
            # Index by Kruncher ID + provider
            kruncher_key = f"{mapping['kruncherId']}:{mapping['provider']}"
            self.by_kruncher_id[kruncher_key] = mapping
            
            # Index by external ID + provider
            external_key = f"{mapping['externalId']}:{mapping['provider']}"
            self.by_external_id[external_key] = mapping
            
            # Index by provider
            if mapping['provider'] not in self.by_provider:
                self.by_provider[mapping['provider']] = []
            self.by_provider[mapping['provider']].append(mapping)
    
    def get_mapping(
        self,
        kruncher_id: str,
        provider: str,
        force_refresh: bool = False
    ) -> Optional[Dict]:
        """Get mapping by Kruncher ID and provider."""
        self.ensure_loaded(force_refresh)
        key = f"{kruncher_id}:{provider}"
        return self.by_kruncher_id.get(key)
    
    def get_mapping_by_external(
        self,
        external_id: str,
        provider: str,
        force_refresh: bool = False
    ) -> Optional[Dict]:
        """Get mapping by external ID and provider."""
        self.ensure_loaded(force_refresh)
        key = f"{external_id}:{provider}"
        return self.by_external_id.get(key)
    
    def get_external_id(
        self,
        kruncher_id: str,
        provider: str
    ) -> Optional[str]:
        """Get external ID for a Kruncher ID."""
        mapping = self.get_mapping(kruncher_id, provider)
        return mapping['externalId'] if mapping else None
    
    def get_kruncher_id(
        self,
        external_id: str,
        provider: str
    ) -> Optional[str]:
        """Get Kruncher ID for an external ID."""
        mapping = self.get_mapping_by_external(external_id, provider)
        return mapping['kruncherId'] if mapping else None
    
    def get_mappings_for_provider(self, provider: str) -> List[Dict]:
        """Get all mappings for a provider."""
        self.ensure_loaded()
        return self.by_provider.get(provider, [])
    
    def is_mapped(self, kruncher_id: str, provider: str) -> bool:
        """Check if a Kruncher ID is mapped to a provider."""
        return self.get_mapping(kruncher_id, provider) is not None
    
    def get_mapping_info(
        self,
        kruncher_id: str,
        provider: str
    ) -> Dict:
        """Get detailed mapping information."""
        mapping = self.get_mapping(kruncher_id, provider)
        
        if not mapping:
            return {
                'found': False,
                'message': f"No mapping found for {kruncher_id} → {provider}"
            }
        
        created_at = datetime.fromisoformat(
            mapping['createdAt'].replace('Z', '+00:00')
        )
        age = datetime.now(created_at.tzinfo) - created_at
        
        return {
            'found': True,
            'mapping': mapping,
            'external_id': mapping['externalId'],
            'created_at': mapping['createdAt'],
            'updated_at': mapping['updatedAt'],
            'age_in_days': age.days,
            'is_current': age.days < 30  # Consider recent if < 30 days
        }
    
    def get_mappings_by_entity_type(
        self,
        entity_type: str,
        force_refresh: bool = False
    ) -> List[Dict]:
        """Get all mappings for an entity type."""
        self.ensure_loaded(force_refresh)
        return [
            m for m in self.mappings_cache
            if m['entityType'] == entity_type
        ]
    
    def clear_cache(self) -> None:
        """Clear the mapping cache."""
        self.mappings_cache = None
        self.last_fetch = None
        self.by_kruncher_id = {}
        self.by_external_id = {}
        self.by_provider = {}
 
# Usage examples
lookup = MappingLookup()
 
# Get mapping by Kruncher ID
mapping = lookup.get_mapping("proj_123", "affinity")
print(f"Mapping: {mapping}")
 
# Get external ID
external_id = lookup.get_external_id("proj_123", "affinity")
print(f"External ID: {external_id}")
 
# Get Kruncher ID
kruncher_id = lookup.get_kruncher_id("affinity_org_456", "affinity")
print(f"Kruncher ID: {kruncher_id}")
 
# Check if mapped
is_mapped = lookup.is_mapped("proj_123", "affinity")
print(f"Is mapped: {is_mapped}")
 
# Get detailed info
info = lookup.get_mapping_info("proj_123", "affinity")
print(f"Info: {info}")
 
# Get all mappings for provider
affinity_mappings = lookup.get_mappings_for_provider("affinity")
print(f"Affinity mappings: {len(affinity_mappings)}")
 
# Get mappings by entity type
company_mappings = lookup.get_mappings_by_entity_type("company")
print(f"Company mappings: {len(company_mappings)}")

Result: Production-ready indexed lookup with caching.

cURL

Query: By Kruncher ID

CODE

# Find mapping by Kruncher ID (server-side)
curl -s -X GET "https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=proj_123" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.data'
 
# Pretty print the result
curl -s -X GET "https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=proj_123" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.data | {kruncherId, externalId, provider, createdAt}'

Result: Direct server-side lookup by Kruncher ID.

Query: By External ID

CODE

# Find mapping by external ID (server-side)
curl -s -X GET "https://api.kruncher.ai/api/integration/map/externalid?externalId=affinity_org_456" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.data'
 
# Pretty print the result
curl -s -X GET "https://api.kruncher.ai/api/integration/map/externalid?externalId=affinity_org_456" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.data | {kruncherId, externalId, provider, createdAt}'

Result: Direct server-side lookup by external ID.

Get All + Filter

CODE

# Get all mappings and filter client-side
curl -s -X GET "https://api.kruncher.ai/api/integration/map/all" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.'
 
# Find specific mapping by Kruncher ID
KRUNCHER_ID="proj_123"
PROVIDER="affinity"
 
curl -s -X GET "https://api.kruncher.ai/api/integration/map/all" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq ".data[] | select(.kruncherId == \"$KRUNCHER_ID\" and .provider == \"$PROVIDER\")"
 
# Find mapping by external ID
EXTERNAL_ID="affinity_org_456"
 
curl -s -X GET "https://api.kruncher.ai/api/integration/map/all" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq ".data[] | select(.externalId == \"$EXTERNAL_ID\")"
 
# Get just the external ID
curl -s -X GET "https://api.kruncher.ai/api/integration/map/all" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq -r ".data[] | select(.kruncherId == \"proj_123\" and .provider == \"affinity\") | .externalId"

Result: Use when filtering multiple mappings or by provider.

Script

CODE

#!/bin/bash
 
API_KEY="YOUR_API_KEY_HERE"
KRUNCHER_ID="proj_123"
 
# Get mapping by Kruncher ID (server-side lookup)
MAPPING=$(curl -s -X GET "https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=$KRUNCHER_ID" \
  -H "Authorization: $API_KEY")
 
# Check if found
if [ "$(echo $MAPPING | jq -r '.data')" == "null" ]; then
  echo "No mapping found for Kruncher ID: $KRUNCHER_ID"
  exit 1
fi
 
# Extract IDs
EXTERNAL_ID=$(echo $MAPPING | jq -r '.data.externalId')
PROVIDER=$(echo $MAPPING | jq -r '.data.provider')
CREATED_AT=$(echo $MAPPING | jq -r '.data.createdAt')
 
echo "Found mapping:"
echo "  Kruncher ID: $KRUNCHER_ID"
echo "  External ID: $EXTERNAL_ID"
echo "  Provider: $PROVIDER"
echo "  Created: $CREATED_AT"

Result: Production script for mapping lookup.

Response Structure

Mapping Object

CODE

{
  "id": "mapping_abc123",
  "entityType": "company",
  "provider": "affinity",
  "kruncherId": "proj_123",
  "externalId": "affinity_org_456",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "customerId": "customer_xyz789"
}

Response Fields

Field	Type	Description
`id`	string	Unique mapping identifier
`entityType`	string	Type: `person`, `company`, or `opportunity`
`provider`	string	External provider (affinity, attio, pipedrive, etc.)
`kruncherId`	string	Kruncher internal ID
`externalId`	string	External system ID
`createdAt`	string	ISO 8601 timestamp when created
`updatedAt`	string	ISO 8601 timestamp when last updated
`customerId`	string	Your customer/account ID

Endpoint Comparison

Which Endpoint Should I Use?

Use Case	Endpoint	Pros	Cons
Single lookup by Kruncher ID	`/map/kruncherid?kruncherId=...`	Fast, simple, server-side	Only one ID per request
Single lookup by external ID	`/map/externalid?externalId=...`	Fast, simple, server-side	Only one ID per request
Batch lookups (multiple IDs)	`/map/all` + filter	Get all at once, flexible	Slower, larger response
Filter by provider	`/map/all` + filter	Provider-specific results	Client-side processing
Check mapping exists	`/map/kruncherid` or `/map/externalid`	Quick verification	Need to handle 404
Get all mappings	`/map/all`	Complete dataset	Largest response, slower

Decision Tree:

CODE

Do you need a single ID lookup?
├─ Yes, have Kruncher ID? → Use /map/kruncherid
├─ Yes, have external ID? → Use /map/externalid
└─ No, multiple IDs? → Use /map/all and filter

Performance Characteristics

Endpoint	Request Size	Response Size	Latency	Best For
`/map/kruncherid`	Small	Small	Fast	Single Kruncher lookups
`/map/externalid`	Small	Small	Fast	Single external lookups
`/map/all`	Small	Large	Medium	Batch operations, filtering

Common Patterns

Pattern 1: Before Syncing Data (Direct Lookup)

CODE

// Before updating external system - using direct server-side lookup
async function syncToAffinity(kruncherId, data) {
  const url = `https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=${kruncherId}`;
  
  const response = await fetch(url, {
    headers: {
      "Authorization": `YOUR_API_KEY`,
      "Content-Type": "application/json"
    }
  });
  
  if (!response.ok) {
    console.error("Not mapped to Affinity");
    return;
  }
  
  const result = await response.json();
  const mapping = result.data;
  
  // Sync using external ID
  await updateAffinity(mapping.externalId, data);
  console.log(`Synced to Affinity: ${mapping.externalId}`);
}

When to use: Single sync operations, quick verification before updates.

Pattern 2: Bidirectional ID Lookup (Query Endpoints)

CODE

import requests
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
def get_external_id(kruncher_id):
    """Get external ID from Kruncher ID."""
    url = f"{BASE_URL}/integration/map/kruncherid"
    response = requests.get(url, 
        params={"kruncherId": kruncher_id},
        headers={"Authorization": f"{API_KEY}"}
    )
    if response.status_code == 200:
        return response.json()['data']['externalId']
    return None
 
def get_kruncher_id(external_id):
    """Get Kruncher ID from external ID."""
    url = f"{BASE_URL}/integration/map/externalid"
    response = requests.get(url,
        params={"externalId": external_id},
        headers={"Authorization": f"{API_KEY}"}
    )
    if response.status_code == 200:
        return response.json()['data']['kruncherId']
    return None
 
# Usage: Convert between systems
external_id = get_external_id("proj_123")  # Kruncher → External
kruncher_id = get_kruncher_id("affinity_org_456")  # External → Kruncher
 
if external_id and kruncher_id:
    print(f"Sync data between {kruncher_id} and {external_id}")

When to use: Converting IDs between systems, quick bidirectional lookups.

Pattern 3: Verify Before Processing (Direct Endpoint)

CODE

async function processCompany(kruncherId) {
  const url = `https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=${kruncherId}`;
  
  const response = await fetch(url, {
    headers: {
      "Authorization": `YOUR_API_KEY`,
      "Content-Type": "application/json"
    }
  });
  
  // Check if mapping exists
  if (response.status === 404) {
    console.log("Company not mapped");
    return;
  }
  
  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }
  
  const result = await response.json();
  const mapping = result.data;
  
  // Check mapping age
  const createdDate = new Date(mapping.createdAt);
  const ageInDays = Math.floor((Date.now() - createdDate) / (1000 * 60 * 60 * 24));
  
  if (ageInDays > 90) {
    console.warn(`Warning: Mapping is ${ageInDays} days old`);
  }
  
  // Process company
  await processExternal(mapping);
}

When to use: Validation before processing, checking if entity is mapped.

Performance Tips

When to Use Direct Query Endpoints

Use /map/kruncherid or /map/externalid for:

Single lookups - No need to fetch all mappings
High-frequency calls - Each lookup is independent
Low latency requirements - Smaller response, faster processing
Memory-constrained environments - Don’t cache entire dataset

CODE

// Fast single lookup (recommended)
const mapping = await getMappingByKruncherId("proj_123");

When to Use /map/all

Use /map/all with client-side filtering for:

Batch lookups - 3+ IDs to look up at once
Provider filtering - Need to filter by specific provider
Caching strategy - Cache once, query many times
Complete dataset - Need all mappings anyway

CODE

// Batch lookup with caching (recommended)
const lookup = new MappingLookup(API_KEY);
const ids = ["proj_1", "proj_2", "proj_3"];
const mappings = ids.map(id => lookup.getMapping(id, "affinity"));

Caching Strategy for /map/all

If using /map/all, implement caching:

Cache mappings for 10 minutes
Refresh cache after creating new mappings
Use indices for O(1) lookups
Share cache across requests

CODE

// Indexed lookup with caching
const lookup = new MappingLookup(API_KEY);
const mapping = await lookup.getMapping(kruncherId, provider);

Batch Operations

CODE

// Get all at once, then filter (if needed)
const mappings = await lookup.getMappingsForProvider("affinity");
 
// Or use query endpoint per ID (if only a few)
const externalIds = ["affinity_org_1", "affinity_org_2"];
const batchMappings = await Promise.all(
  externalIds.map(id => getMappingByExternalId(id))
);

Error Handling

Mapping Not Found (Query Endpoints)

Query endpoints return 404 when no mapping exists. This is normal and expected.

CODE

// Using direct query endpoint
const response = await fetch(
  `https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=proj_123`,
  { headers: { "Authorization": `${API_KEY}` } }
);
 
if (response.status === 404) {
  console.log("Mapping not found. Options:");
  console.log("1. Create the mapping first via POST /config/mapping");
  console.log("2. Verify the Kruncher ID is correct");
  console.log("3. Check if mapped to a different provider");
  return;
}
 
if (!response.ok) {
  throw new Error(`Error: ${response.statusText}`);
}
 
const mapping = (await response.json()).data;

Mapping Not Found (Get All Approach)

CODE

lookup = MappingLookup()
mapping = lookup.get_mapping("proj_123", "affinity")
 
if not mapping:
    print("Mapping not found. Options:")
    print("1. Create the mapping first")
    print("2. Check provider name is correct")
    print("3. Verify Kruncher ID exists")

Stale Mapping

CODE

import requests
from datetime import datetime
 
# Get mapping and check age
response = requests.get(
    "https://api.kruncher.ai/api/integration/map/kruncherid",
    params={"kruncherId": "proj_123"},
    headers={"Authorization": f"{API_KEY}"}
)
 
if response.status_code == 200:
    mapping = response.json()['data']
    created_date = datetime.fromisoformat(mapping['createdAt'].replace('Z', '+00:00'))
    age_days = (datetime.now(created_date.tzinfo) - created_date).days
    
    if age_days > 90:
        print(f"Warning: Mapping is {age_days} days old, may need refresh")
        # Re-sync with external system

Invalid Query Parameters

CODE

# Missing required parameter
curl -X GET "https://api.kruncher.ai/api/integration/map/kruncherid" \
  -H "Authorization: YOUR_API_KEY_HERE"
# Response: 400 Bad Request - "kruncherId parameter is required"
 
# Properly formatted request
curl -X GET "https://api.kruncher.ai/api/integration/map/kruncherid?kruncherId=proj_123" \
  -H "Authorization: YOUR_API_KEY_HERE"
# Response: 200 OK with mapping data

Create Mapping - Create new mappings
Get All Mappings - List all mappings
Find Companies - Get Kruncher entity IDs
Integrations - Provider-specific docs

Best Practices

Before Syncing

Verify mapping exists
Check mapping is recent (< 90 days old)
Log sync operations
Handle missing mappings gracefully

Performance

Cache mappings locally
Use indexed lookups
Batch operations when possible
Refresh cache periodically

Error Handling

Handle “not found” gracefully
Provide helpful error messages
Log all mapping lookups
Implement retry logic

Data Integrity

Validate ID format before lookup
Verify entity exists in both systems
Monitor sync success rates
Alert on mapping anomalies

Troubleshooting

Mapping Not Found

Verify mapping was created
Check provider name spelling
Ensure you’re using correct Kruncher ID
Confirm account has access

Performance Issues

Large number of mappings (>10,000)
Implement client-side caching
Use batch lookups
Consider indexing strategy

Stale Data

Cache too old, refresh needed
Recent sync deleted mapping
Verify mapping still exists
Check for conflicts

Need Help?

Can’t find mapping? Check Create Mapping guide
Bulk lookups? Review batch operation examples
Performance? Implement caching pattern above
Sync issues? Debug with mapping info tool

Get Mapping

Endpoints

Option 1: Get All Mappings (Client-side Filtering)

Option 2: Find by External ID (Server-side Query)

Option 3: Find by Kruncher ID (Server-side Query)

Headers

Query Parameters

externalId Endpoint

kruncherId Endpoint

Use Cases

When to Get Mappings

Quick Start Examples

Get Mapping by External ID

Get Mapping by Kruncher ID

Code Examples

JavaScript/TypeScript

Query: By Kruncher ID

Query: By External ID

Get All + Filter

Advanced Lookup

Python

Query: By Kruncher ID

Query: By External ID

Get All + Filter

Advanced Lookup

cURL

Query: By Kruncher ID

Query: By External ID

Get All + Filter

Script

Response Structure

Mapping Object

Response Fields

Endpoint Comparison

Which Endpoint Should I Use?

Performance Characteristics

Common Patterns

Pattern 1: Before Syncing Data (Direct Lookup)

Pattern 2: Bidirectional ID Lookup (Query Endpoints)

Pattern 3: Verify Before Processing (Direct Endpoint)

Performance Tips

When to Use Direct Query Endpoints

When to Use /map/all

Caching Strategy for /map/all

Batch Operations

Error Handling

Mapping Not Found (Query Endpoints)

Mapping Not Found (Get All Approach)

Stale Mapping

Invalid Query Parameters

Related Endpoints

Best Practices

Before Syncing

Performance

Error Handling

Data Integrity

Troubleshooting

Mapping Not Found

Performance Issues

Stale Data

Need Help?