Documentation Index
Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The upsert endpoint intelligently creates a new person or updates an existing one based on configurable duplicate detection strategies. It automatically handles conflicts and prevents duplicate records using exact matching, fuzzy matching, or AI-powered similarity detection.
Endpoint
PUT http://api.gu1.ai/entities/upsert
Authentication
Requires a valid API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Request Body
The person data (same structure as Create Person endpoint)
Configuration options for upsert behavior
options.conflictResolution
How to handle conflicts when an existing person is found:
source_wins - New data overwrites existing datatarget_wins - Keep existing data, ignore new datamanual_review - Flag for manual review without updatingsmart_merge (default) - Intelligently merge both datasets
options.deduplicationStrategy
Strategy for detecting duplicate persons:
exact_match - Match by externalId and taxId (case-insensitive)fuzzy_match - Similarity matching on name and taxId (80% threshold)ai_similarity - AI-powered semantic similarity detectionhybrid (recommended) - Exact match with fuzzy fallback
options.createRelationships
Whether to automatically create relationships between entities
Response
Indicates if the operation succeeded
The action performed: created or updated
The final person state after upsert
The person state before update (null if newly created)
Confidence score (0-1) for the duplicate detection match
Explanation of why the person was created/updated
Array of field-level conflicts detected during merge (if any)
Examples
Simple Upsert (Default Behavior)
curl -X PUT http://api.gu1.ai/entities/upsert \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entity": {
"type": "person",
"externalId": "customer_12345",
"name": "María González",
"countryCode": "AR",
"taxId": "20-12345678-9",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"occupation": "Software Engineer",
"income": 85000
}
}
}
}'
Upsert with Fuzzy Matching
curl -X PUT http://api.gu1.ai/entities/upsert \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entity": {
"type": "person",
"externalId": "customer_new_123",
"name": "Maria Gonzales",
"countryCode": "AR",
"taxId": "20-12345678-9",
"entityData": {
"person": {
"firstName": "Maria",
"lastName": "Gonzales"
}
}
},
"options": {
"deduplicationStrategy": "fuzzy_match",
"conflictResolution": "smart_merge"
}
}'
Response Examples
Created New Person
{
"success": true,
"action": "created",
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "customer_12345",
"type": "person",
"name": "María González",
...
},
"previousEntity": null,
"confidence": 1.0,
"reasoning": "No existing entity found matching criteria. Created new entity.",
"conflicts": []
}
Updated Existing Person
{
"success": true,
"action": "updated",
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "customer_12345",
"type": "person",
"name": "María González",
"entityData": {
"person": {
"income": 95000
}
},
...
},
"previousEntity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"entityData": {
"person": {
"income": 85000
}
},
...
},
"confidence": 1.0,
"reasoning": "Exact match found on externalId. Updated existing entity with smart merge.",
"conflicts": [
{
"field": "entityData.person.income",
"oldValue": 85000,
"newValue": 95000,
"resolution": "source_wins"
}
]
}
Use Cases
Data Import from CRM
// Import customer data from CRM, avoiding duplicates
async function importCustomer(crmData) {
const response = await fetch('http://api.gu1.ai/entities/upsert', {
method: 'PUT',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
entity: {
type: 'person',
externalId: crmData.customerId,
name: crmData.fullName,
countryCode: crmData.country,
taxId: crmData.taxId,
entityData: {
person: {
firstName: crmData.firstName,
lastName: crmData.lastName,
income: crmData.annualIncome
}
},
attributes: {
source: 'crm_import',
importDate: new Date().toISOString()
}
},
options: {
deduplicationStrategy: 'hybrid',
conflictResolution: 'smart_merge'
}
})
});
return response.json();
}
Progressive Data Enrichment
def enrich_person_data(external_id, new_data):
"""Progressively add data to person as it becomes available"""
response = requests.put(
'http://api.gu1.ai/entities/upsert',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'entity': {
'type': 'person',
'externalId': external_id,
'name': new_data.get('name'),
'countryCode': new_data.get('country'),
'entityData': new_data.get('details', {}),
'attributes': new_data.get('attributes', {})
},
'options': {
'deduplicationStrategy': 'exact_match',
'conflictResolution': 'smart_merge' # Merge new with existing
}
}
)
result = response.json()
if result['action'] == 'updated':
print(f"Enriched existing person with new data")
return result
Best Practices
-
Choose the Right Strategy:
exact_match for clean, structured data with reliable IDsfuzzy_match for user-entered data with potential typoshybrid for most production scenarios
-
Handle Conflicts Gracefully:
- Use
smart_merge for automatic resolution
- Use
manual_review for critical data
- Check
conflicts array in response for important changes
-
Monitor Confidence Scores:
- Scores below 0.7 may indicate weak matches
- Log low-confidence updates for review
Error Responses
400 Bad Request
{
"error": "Invalid tax ID format for country"
}
500 Internal Server Error
{
"error": "Failed to upsert entity"
}
Next Steps
