Upsert an entity

Upsert

curl --request PUT \
  --url http://api.gu1.ai/entities/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity": {},
  "options": {},
  "options.conflictResolution": {},
  "options.deduplicationStrategy": {},
  "options.createRelationships": true
}
'

import requests

url = "http://api.gu1.ai/entities/upsert"

payload = {
    "entity": {},
    "options": {},
    "options.conflictResolution": {},
    "options.deduplicationStrategy": {},
    "options.createRelationships": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity: {},
    options: {},
    'options.conflictResolution': {},
    'options.deduplicationStrategy': {},
    'options.createRelationships': true
  })
};

fetch('http://api.gu1.ai/entities/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'entity' => [
        
    ],
    'options' => [
        
    ],
    'options.conflictResolution' => [
        
    ],
    'options.deduplicationStrategy' => [
        
    ],
    'options.createRelationships' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/upsert"

	payload := strings.NewReader("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://api.gu1.ai/entities/upsert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/upsert")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "action": "<string>",
  "entity": {},
  "previousEntity": {},
  "confidence": 123,
  "reasoning": "<string>",
  "conflicts": [
    {}
  ]
}

PUT

entities

upsert

Upsert

curl --request PUT \
  --url http://api.gu1.ai/entities/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity": {},
  "options": {},
  "options.conflictResolution": {},
  "options.deduplicationStrategy": {},
  "options.createRelationships": true
}
'

import requests

url = "http://api.gu1.ai/entities/upsert"

payload = {
    "entity": {},
    "options": {},
    "options.conflictResolution": {},
    "options.deduplicationStrategy": {},
    "options.createRelationships": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity: {},
    options: {},
    'options.conflictResolution': {},
    'options.deduplicationStrategy': {},
    'options.createRelationships': true
  })
};

fetch('http://api.gu1.ai/entities/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'entity' => [
        
    ],
    'options' => [
        
    ],
    'options.conflictResolution' => [
        
    ],
    'options.deduplicationStrategy' => [
        
    ],
    'options.createRelationships' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/upsert"

	payload := strings.NewReader("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://api.gu1.ai/entities/upsert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/upsert")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "action": "<string>",
  "entity": {},
  "previousEntity": {},
  "confidence": 123,
  "reasoning": "<string>",
  "conflicts": [
    {}
  ]
}

Overview

The upsert endpoint intelligently creates a new entity 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

object

required

The entity data (same structure as Create Entity), including optional root fields such as email, phone, and nationality (ISO 3166-1 alpha-2 or mappable label).

The JSON schema may allow the same keys as create (e.g. monitoring, autoExecuteIntegrations). Upsert does not run creation-time auto-enrichments or apply monitoring. Use POST /entities or POST /entities/automatic for watchlist / Regtia op 1 behavior during enrichment.

object

Configuration options for upsert behavior

enum

How to handle conflicts when an existing entity is found:

source_wins - New data overwrites existing data
target_wins - Keep existing data, ignore new data
manual_review - Flag for manual review without updating
smart_merge (default) - Intelligently merge both datasets

enum

Strategy for detecting duplicate entities:

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 detection
hybrid (recommended) - Exact match with fuzzy fallback

boolean

default:"true"

Whether to automatically create relationships between entities

Response

boolean

Indicates if the operation succeeded

string

The action performed: created or updated

object

The final entity state after upsert

object

The entity state before update (null if newly created)

number

Confidence score (0-1) for the duplicate detection match

string

Explanation of why the entity was created/updated

array

Array of field-level conflicts detected during merge (if any)

Deduplication Strategies

Exact Match

Matches entities based on exact field comparison (case-insensitive):

Fields: externalId, taxId
Use case: When you have reliable unique identifiers
Speed: Fastest
Accuracy: 100% for identical values

Fuzzy Match

Uses Levenshtein distance for similarity matching:

Fields: name, taxId
Threshold: 80% similarity
Use case: When dealing with typos or variations
Speed: Moderate
Accuracy: High for similar strings

AI Similarity

AI-powered semantic similarity detection:

Method: Vector embeddings and cosine similarity
Use case: Complex multi-field matching
Speed: Slower
Accuracy: Highest for semantically similar entities

Hybrid (Recommended)

Combines exact and fuzzy matching:

Primary: Exact match on identifiers
Fallback: Fuzzy match on names
Confidence threshold: 80%
Use case: Best balance of speed and accuracy

Conflict Resolution Strategies

smart_merge (Default)

Intelligently merges data from both sources:

Priority: Newer data for simple fields
Arrays: Merges and deduplicates
Objects: Deep merge with conflict detection
Empty values: Preserves non-empty existing values

source_wins

New data completely replaces existing:

Use case: When incoming data is authoritative
Behavior: All fields from source
Risk: May lose valuable existing data

target_wins

Keeps existing data, ignores incoming:

Use case: When existing data is authoritative
Behavior: No updates performed
Risk: May miss important updates

manual_review

Flags conflicts without auto-resolution:

Use case: High-stakes data requiring human review
Behavior: Creates review task
Result: Entity marked for manual resolution

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
        }
      }
    }
  }'

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: '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
        }
      }
    }
  })
});

const result = await response.json();
console.log(`Action: ${result.action}`); // 'created' or 'updated'
console.log(`Confidence: ${result.confidence}`);

import requests

response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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
                }
            }
        }
    }
)

result = response.json()
print(f"Action: {result['action']}")
print(f"Confidence: {result['confidence']}")

Upsert with Exact Match Strategy

curl -X PUT http://api.gu1.ai/entities/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": {
      "type": "company",
      "externalId": "company_789",
      "name": "Tech Solutions S.A.",
      "countryCode": "BR",
      "taxId": "12.345.678/0001-90",
      "entityData": {
        "company": {
          "legalName": "Tech Solutions Sociedade Anônima",
          "revenue": 7500000
        }
      }
    },
    "options": {
      "deduplicationStrategy": "exact_match",
      "conflictResolution": "smart_merge"
    }
  }'

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: 'company',
      externalId: 'company_789',
      name: 'Tech Solutions S.A.',
      countryCode: 'BR',
      taxId: '12.345.678/0001-90',
      entityData: {
        company: {
          legalName: 'Tech Solutions Sociedade Anônima',
          revenue: 7500000
        }
      }
    },
    options: {
      deduplicationStrategy: 'exact_match',
      conflictResolution: 'smart_merge'
    }
  })
});

const result = await response.json();
if (result.action === 'updated') {
  console.log('Found and updated existing company');
  console.log('Conflicts:', result.conflicts);
}

import requests

response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entity': {
            'type': 'company',
            'externalId': 'company_789',
            'name': 'Tech Solutions S.A.',
            'countryCode': 'BR',
            'taxId': '12.345.678/0001-90',
            'entityData': {
                'company': {
                    'legalName': 'Tech Solutions Sociedade Anônima',
                    'revenue': 7500000
                }
            }
        },
        'options': {
            'deduplicationStrategy': 'exact_match',
            'conflictResolution': 'smart_merge'
        }
    }
)

result = response.json()
if result['action'] == 'updated':
    print("Found and updated existing company")
    print(f"Conflicts: {result['conflicts']}")

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"
    }
  }'

// Will match "Maria Gonzales" with existing "María González"
// due to 80%+ similarity threshold

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: 'customer_new_123',
      name: 'Maria Gonzales', // Slight variation in spelling
      countryCode: 'AR',
      taxId: '20-12345678-9',
      entityData: {
        person: {
          firstName: 'Maria',
          lastName: 'Gonzales'
        }
      }
    },
    options: {
      deduplicationStrategy: 'fuzzy_match',
      conflictResolution: 'smart_merge'
    }
  })
});

const result = await response.json();
console.log(`Matched with confidence: ${result.confidence}`);
console.log(`Reasoning: ${result.reasoning}`);

import requests

# Will match "Maria Gonzales" with existing "María González"
response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entity': {
            'type': 'person',
            'externalId': 'customer_new_123',
            'name': 'Maria Gonzales',  # Slight variation
            'countryCode': 'AR',
            'taxId': '20-12345678-9',
            'entityData': {
                'person': {
                    'firstName': 'Maria',
                    'lastName': 'Gonzales'
                }
            }
        },
        'options': {
            'deduplicationStrategy': 'fuzzy_match',
            'conflictResolution': 'smart_merge'
        }
    }
)

result = response.json()
print(f"Matched with confidence: {result['confidence']}")
print(f"Reasoning: {result['reasoning']}")

Hybrid Strategy (Recommended)

curl -X PUT http://api.gu1.ai/entities/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": {
      "type": "company",
      "externalId": "comp_456",
      "name": "TechSolutions SA",
      "countryCode": "BR",
      "taxId": "12.345.678/0001-90",
      "entityData": {
        "company": {
          "employeeCount": 100
        }
      }
    },
    "options": {
      "deduplicationStrategy": "hybrid"
    }
  }'

// Tries exact match first, falls back to fuzzy if needed
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: 'company',
      externalId: 'comp_456',
      name: 'TechSolutions SA', // Variation of "Tech Solutions S.A."
      countryCode: 'BR',
      taxId: '12.345.678/0001-90', // Exact match on tax ID
      entityData: {
        company: {
          employeeCount: 100
        }
      }
    },
    options: {
      deduplicationStrategy: 'hybrid' // Best of both worlds
    }
  })
});

const result = await response.json();
// Will match on taxId (exact) or name (fuzzy)
console.log(`Strategy used: ${result.reasoning}`);

import requests

# Hybrid: tries exact match first, fuzzy as fallback
response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entity': {
            'type': 'company',
            'externalId': 'comp_456',
            'name': 'TechSolutions SA',
            'countryCode': 'BR',
            'taxId': '12.345.678/0001-90',
            'entityData': {
                'company': {
                    'employeeCount': 100
                }
            }
        },
        'options': {
            'deduplicationStrategy': 'hybrid'
        }
    }
)

result = response.json()
print(f"Strategy used: {result['reasoning']}")

Response Examples

Created New Entity

{
  "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 Entity

{
  "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 External System

// 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_entity_data(external_id, new_data):
    """Progressively add data to entity 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 entity with new data")
    return result

Best Practices

Choose the Right Strategy:
- exact_match for clean, structured data with reliable IDs
- fuzzy_match for user-entered data with potential typos
- hybrid for most production scenarios
Handle Conflicts Gracefully:
- Use smart_merge for automatic resolution
- Use manual_review for critical financial 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
- Consider manual review threshold
Relationship Management:
- Set createRelationships: true to auto-link related entities
- Useful for transaction-customer, company-person relationships

Error Responses

400 Bad Request

{
  "error": "Invalid tax ID format for country"
}

400 Missing Required Fields

{
  "error": "Missing required fields",
  "missingFields": ["legalName"],
  "requiredFields": ["legalName", "industry"]
}

500 Internal Server Error

{
  "error": "Failed to upsert entity"
}

Next Steps

Batch Upsert - Process multiple entities at once
List Entities - Query upserted entities
Update Entity - Make targeted updates
Get Entity - Retrieve full entity details

​Overview

​Endpoint

​Authentication

​Request Body

​Response

​Deduplication Strategies

​Exact Match

​Fuzzy Match

​AI Similarity

​Hybrid (Recommended)

​Conflict Resolution Strategies

​smart_merge (Default)

​source_wins

​target_wins

​manual_review

​Examples

​Simple Upsert (Default Behavior)

​Upsert with Exact Match Strategy

​Upsert with Fuzzy Matching

​Hybrid Strategy (Recommended)

​Response Examples

​Created New Entity

​Updated Existing Entity

​Use Cases

​Data Import from External System

​Progressive Data Enrichment

​Best Practices

​Error Responses

​400 Bad Request

​400 Missing Required Fields

​500 Internal Server Error

​Next Steps

Overview

Endpoint

Authentication

Request Body

Response

Deduplication Strategies

Exact Match

Fuzzy Match

AI Similarity

Hybrid (Recommended)

Conflict Resolution Strategies

smart_merge (Default)

source_wins

target_wins

manual_review

Examples

Simple Upsert (Default Behavior)

Upsert with Exact Match Strategy

Upsert with Fuzzy Matching

Hybrid Strategy (Recommended)

Response Examples

Created New Entity

Updated Existing Entity

Use Cases

Data Import from External System

Progressive Data Enrichment

Best Practices

Error Responses

400 Bad Request

400 Missing Required Fields

500 Internal Server Error

Next Steps