Skip to main content

Learn More

The Id Field​

There are three possible behaviors regarding the Id field when creating or updating a record:

Field ValueOutcome
Id is omittedA new record will be created, and a new ID will be returned.
A valid Id is providedThe existing record matching the ID will be updated.
The provided Id does not existA new record will be created using the given ID.

Updating a Record​

When updating a record, it’s important to understand how the provided values affect the data:

  1. Fields set to null:

    Behavior: If a field is set to null, the existing value for that field will remain unchanged.
    Example: If a donor's current suffix is שליטא, and the request sets the suffixHebrew field to null, the suffix will not be removed or updated; it will stay as שליטא.

  2. Fields set to an empty string or empty array:

    Behavior: If a field is set to an empty string or an empty array, the existing value will be deleted.
    Example: If the title is set to Mr. and a request is made with the title set to an empty string, the title will now be an empty field.

  3. All other provided fields:

    Behavior: Any other field that is provided with a value will update the existing value for that field.
    Example: If the current firstName is Dovid and the request provides a new value like Avi, the name will be updated to Avi.

  4. Handling Arrays of Objects:

    Behavior: Fields within arrays (such as lists of phones, emails, or addresses) will be updated based on a unique identifier for each object in the array, like phoneLabel, addressLabel, or emailLabel.
    Example: If there are multiple phone numbers stored for a user, each with a unique phoneLabel, the correct phone will be updated based on the label provided in the request. If a label is missing from the request, the corresponding object will be deleted.
    Additional Rule: If the label is not present in the update, the entire corresponding object (such as the phone number) will be removed from the record.