POST/api/public/v1/object/upsert

Upsert Object

Create or update an object with properties without creating an event. Use this to enrich objects with metadata before they appear in process events, or to update object properties at any time. Uses upsert semantics — creates if not exists, merges properties if exists.

Request Body

Name
type
Type
string
Required
required
Description
The object type (1-100 characters). Examples: "Customer", "Order", "Product"
Name
id
Type
string
Required
required
Description
Unique identifier within the type (1-500 characters). This is your external ID.
Name
properties
Type
object
Description
Object attributes to set or update. Properties are merged with existing properties, not replaced entirely.

Request

POST

/api/public/v1/object/upsert

curl -X POST 'https://api.flowmyna.com/api/public/v1/object/upsert' \
-H 'Authorization: Bearer fm_live_xxx' \
-H 'Content-Type: application/json' \
-d '{
    "type": "Customer",
    "id": "CUST-456",
    "properties": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "tier": "gold",
      "lifetime_value": 5420.00,
      "signup_date": "2023-01-15"
    }
  }'

Response

{
  "success": true,
  "object_id": "550e8400-e29b-41d4-a716-446655440000",
  "object_type": "Customer",
  "external_id": "CUST-456",
  "created": true,
  "message": "Object 'Customer/CUST-456' created successfully"
}

Upsert Semantics

This endpoint is idempotent and uses upsert semantics:

Create: If the object doesn't exist (same type + id), it's created
Update: If the object exists, its properties are merged with the provided properties

The response includes a created field indicating whether the object was newly created (true) or updated (false).

Property Merging

When you upsert an object that already exists, properties are merged, not replaced. This lets you incrementally add information without losing existing data.

Property Merging Example

// First call: creates object
{
  "type": "Customer",
  "id": "CUST-123",
  "properties": {
    "name": "John Smith"
  }
}
// Result: { "name": "John Smith" }

To update a property value, simply set it again. To remove a property, set it to null.

Common Use Cases

1. Enrich Objects Before Events

Upsert customers or entities with rich properties before they appear in process events:

Pre-Registration Pattern

# Step 1: Register customer with full details
client.upsert_object(
    type="Customer",
    id="CUST-456",
    properties={
        "name": "Jane Doe",
        "email": "jane@example.com",
        "tier": "gold",
        "region": "US-WEST"
    }
)


# Step 2: Record events (customer already has properties)
client.record_event(
    event="Order Created",
    objects=[
        {"type": "Order", "id": "ORD-789"},
        {"type": "Customer", "id": "CUST-456"}  # Already enriched!
    ]
)

2. Sync External Data

Keep object properties in sync with your CRM, ERP, or other systems:

Data Sync Pattern

# Daily sync from CRM
for customer in crm.get_updated_customers():
    client.upsert_object(
        type="Customer",
        id=customer.id,
        properties={
            "name": customer.name,
            "tier": customer.tier,
            "lifetime_value": customer.ltv,
            "last_updated": datetime.now().isoformat()
        }
    )

3. Update Properties Mid-Process

Update object properties as they change during a process:

Mid-Process Update

// Order status changed
await client.upsertObject({
  type: 'Order',
  id: 'ORD-123',
  properties: {
    status: 'shipped',
    shipped_at: new Date().toISOString(),
    tracking_number: '1Z999AA10123456784'
  }
});


// Then record the event
await client.recordEvent({
  event: 'Order Shipped',
  objects: [{ type: 'Order', id: 'ORD-123' }]
});

SDK Examples

Upsert with SDKs

from flowmyna import FlowMyna


client = FlowMyna(api_key="fm_live_xxx")


# Upsert a customer
result = client.upsert_object(
    type="Customer",
    id="CUST-456",
    properties={
        "name": "Jane Doe",
        "email": "jane@example.com",
        "tier": "gold"
    }
)


print(f"Object {'created' if result.created else 'updated'}: {result.object_id}")

Learn about batch upsert for multiple objects