Lookup Mapping

Look up an integration mapping by entity type, provider, and either external ID or Kruncher ID. Useful for checking if a mapping exists before creating a new one, or for retrieving mapping details with flexible query criteria.

Endpoint

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

This is a flexible lookup endpoint that searches for a mapping by criteria. Different from the POST endpoint (which creates mappings) and the specific /map/externalid and /map/kruncherid endpoints.

Headers

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

Query Parameters

Parameters can also be sent as a JSON request body.

Parameter	Type	Required	Description
`entityType`	string	Yes	Entity type: `"person"`, `"company"`, or `"opportunity"`
`provider`	string	Yes	External provider name (e.g., `"affinity"`, `"attio"`)
`externalId`	string	No	External system ID to look up
`kruncherId`	string	No	Kruncher internal ID to look up

Note: At least one of externalId or kruncherId must be provided.

Code Examples

JavaScript/TypeScript

By External ID

CODE

const API_KEY = "YOUR_API_KEY_HERE";
 
const params = new URLSearchParams({
  entityType: "company",
  provider: "affinity",
  externalId: "ext-123"
});
 
const response = await fetch(
  `https://api.kruncher.ai/api/integration/map?${params}`,
  {
    headers: {
      "Authorization": `${API_KEY}`
    }
  }
);
 
const result = await response.json();
console.log("Mapping:", result.data);

Result: Returns the mapping matching the entity type, provider, and external ID.

By Kruncher ID

CODE

const API_KEY = "YOUR_API_KEY_HERE";
 
const params = new URLSearchParams({
  entityType: "company",
  provider: "affinity",
  kruncherId: "proj_abc123"
});
 
const response = await fetch(
  `https://api.kruncher.ai/api/integration/map?${params}`,
  {
    headers: {
      "Authorization": `${API_KEY}`
    }
  }
);
 
const result = await response.json();
 
if (result.data) {
  console.log("External ID:", result.data.externalId);
  console.log("Updated:", result.data.updatedAt);
} else {
  console.log("No mapping found");
}

Result: Returns the mapping matching the entity type, provider, and Kruncher ID.

With Error Handling

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
async function lookupMapping(entityType, provider, { externalId, kruncherId } = {}) {
  const params = new URLSearchParams({ entityType, provider });
 
  if (externalId) params.set("externalId", externalId);
  if (kruncherId) params.set("kruncherId", kruncherId);
 
  const response = await fetch(`${BASE_URL}/integration/map?${params}`, {
    headers: {
      "Authorization": `${API_KEY}`
    }
  });
 
  if (!response.ok) {
    if (response.status === 404) return null;
    throw new Error(`Lookup failed: ${response.status} ${response.statusText}`);
  }
 
  const result = await response.json();
  return result.data || null;
}
 
// Check if mapping exists before creating
const existing = await lookupMapping("company", "affinity", {
  externalId: "ext-123"
});
 
if (existing) {
  console.log("Mapping already exists:", existing.kruncherId);
} else {
  console.log("No mapping found, safe to create");
}

Result: Reusable lookup function with null return for missing mappings.

Python

By External ID

CODE

import requests
 
API_KEY = "YOUR_API_KEY_HERE"
url = "https://api.kruncher.ai/api/integration/map"
 
headers = {
    "Authorization": f"{API_KEY}"
}
 
params = {
    "entityType": "company",
    "provider": "affinity",
    "externalId": "ext-123"
}
 
response = requests.get(url, headers=headers, params=params)
result = response.json()
 
print(f"Mapping: {result['data']}")

Result: Returns the mapping matching the entity type, provider, and external ID.

By Kruncher ID

CODE

import requests
 
API_KEY = "YOUR_API_KEY_HERE"
url = "https://api.kruncher.ai/api/integration/map"
 
headers = {
    "Authorization": f"{API_KEY}"
}
 
params = {
    "entityType": "company",
    "provider": "affinity",
    "kruncherId": "proj_abc123"
}
 
response = requests.get(url, headers=headers, params=params)
result = response.json()
 
if result.get("data"):
    print(f"External ID: {result['data']['externalId']}")
    print(f"Updated: {result['data']['updatedAt']}")
else:
    print("No mapping found")

Result: Returns the mapping matching the entity type, provider, and Kruncher ID.

With Error Handling

CODE

import requests
from typing import Optional, Dict
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
def lookup_mapping(
    entity_type: str,
    provider: str,
    external_id: Optional[str] = None,
    kruncher_id: Optional[str] = None
) -> Optional[Dict]:
    url = f"{BASE_URL}/integration/map"
 
    headers = {
        "Authorization": f"{API_KEY}"
    }
 
    params = {
        "entityType": entity_type,
        "provider": provider
    }
 
    if external_id:
        params["externalId"] = external_id
    if kruncher_id:
        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")
 
# Check if mapping exists before creating
existing = lookup_mapping("company", "affinity", external_id="ext-123")
 
if existing:
    print(f"Mapping already exists: {existing['kruncherId']}")
else:
    print("No mapping found, safe to create")

Result: Reusable lookup function with None return for missing mappings.

cURL

By External ID

CODE

curl -s -X GET "https://api.kruncher.ai/api/integration/map?entityType=company&provider=affinity&externalId=ext-123" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.data'

Response

Success Response (200 OK)

CODE

{
  "metadata": {
    "code": "1000",
    "title": "Successful",
    "description": ""
  },
  "data": {
    "entityType": "company",
    "provider": "affinity",
    "externalId": "ext-123",
    "kruncherId": "proj_abc123",
    "createdAt": "2024-01-10T14:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Response Fields

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

Create Mapping - Create a new mapping
Get All Mappings - List all mappings
Get by External ID - Look up by external ID only

Lookup Mapping

Endpoint

Headers

Query Parameters

Code Examples

JavaScript/TypeScript

By External ID

By Kruncher ID

With Error Handling

Python

By External ID

By Kruncher ID

With Error Handling

cURL

By External ID

By Kruncher ID

Response

Success Response (200 OK)

Response Fields

Related Endpoints