Partial Updates

All PUT endpoints in the API follow a partial update pattern — send only the fields you want to change, not the entire resource.

Unlike standard PUT semantics

In traditional REST (RFC 7231), PUT replaces the entire resource. GeoTareas PUT behaves as a merge/patch — omitted fields keep their current value. This design avoids accidental data loss when you only need to change one or two fields.

How It Works

1. Only send fields you want to change — omitted fields retain their current value.
2. Send null to clear a field — this sets the value to NULL in the database.
3. The resource ID goes in the URL, never in the body — including id in the body returns a VALIDATION_ERROR.
4. Same validations as POST — field constraints (type, format, required) apply equally to updates. An invalid email is rejected whether you're creating or updating.
5. Read-only fields are ignored — if you send a field that is not editable (e.g., createdAt, id), the server silently ignores it. No error is raised, but the field is not changed.

Examples

Update a single field

cURL

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com"}' \
  "https://$TENANT/apidev/v1/clients/104820579301"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/clients/104820579301`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': API_KEY,
      'tenant': TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email: 'new@example.com' }),
  }
);
const result = await res.json();
console.log(result.data.updated_fields); // ["email"]

Python

response = requests.put(
    f"https://{TENANT}/apidev/v1/clients/104820579301",
    headers={**headers, "Content-Type": "application/json"},
    json={"email": "new@example.com"},
)
print(response.json()["data"]["updated_fields"])  # ["email"]

Only email changes. Name, phone, address — everything else stays as-is.

Response:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["email"]
  }
}

Update multiple fields at once

PUT /apidev/v1/clients/104820579301
Content-Type: application/json

{
  "email": "new@example.com",
  "phone": "+5491155551234",
  "address": "Av. Corrientes 1234, CABA"
}

Response:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["email", "phone", "address"]
  }
}

Clear a field with null

To explicitly remove a value, send null:

PUT /apidev/v1/clients/104820579301
Content-Type: application/json

{
  "phone": null
}

The phone field is set to NULL in the database. All other fields remain unchanged.

Response:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["phone"]
  }
}

Difference between omitting and sending null

• Omitting a field: field keeps its current value (no change)
• Sending null: field is explicitly cleared (set to NULL)

These are not the same. {} changes nothing; {"phone": null} deletes the phone number.

Response Format

All PUT endpoints return a consistent response indicating which fields were actually modified:

Field	Type	Description
success	boolean	true if the update completed without errors
data.id	string	The ID of the updated resource
data.updated_fields	array	List of field names that were changed

tip

Use updated_fields to confirm your update was applied. If a field you sent is missing from this list, the new value was identical to the existing one — no change was needed.

Common Pitfalls

Mistake	What happens	Fix
Sending id in the body	VALIDATION_ERROR	Put the ID in the URL path only
Sending an invalid email format	VALIDATION_ERROR — same validations as POST	Check field constraints in the endpoint docs
Omitting a field to "clear" it	Nothing happens — field keeps current value	Send null explicitly to clear
Sending the full resource from a GET	Works, but risks overwriting concurrent changes	Send only the fields you intend to change