How can I set a field as null using the SOAP API?

Environment:

SOAP API

Resolution:

A common mistake in SOAP requests is made when attempting to remove information from a field. For example let's take the following SOAP envelope excerpt:

<ns2:GenericFields datatype="DATE" name="FOO_DATE">
    <ns2:DataValue>
        <ns2:DateValue>Null</ns2:DateValue>
    </ns2:DataValue>
</ns2:GenericFields>

In this example an attempt is made at passing "Null" as the value to remove any previous information already populated in the database for the FOO_DATE field. This is incorrect and will return an error as follows:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
      <soapenv:Fault>
        <faultcode>soapenv:Sender</faultcode>
        <faultstring>Data element in the Message is NULL</faultstring>
        <detail>
            <fault>RightNowSyncService|urn:wsdl.ws.rightnow.com/v1_3 failed
                Illegal date specified: Null
                Failure in parsing choice indicator in DataValue element
                Failure in setting value for object GenericField element DataValue of type generic_ws_rightnow_com_v1_3::DataValue
                Failed in constructing object GenericObject : NULL input can not be deserialized
                Failed in setting value for element GenericFields array position 3 of object GenericObject
                Failure in setting value for object DataValue_choice_type element ObjectValue of type generic_ws_rightnow_com_v1_3::GenericObject
                Failure in parsing choice indicator in DataValue element
                Failure in setting value for object GenericField element DataValue of type generic_ws_rightnow_com_v1_3::DataValue
                Failed in constructing object GenericObject : NULL input can not be deserialized
                Failed in setting value for element GenericFields array position 0 of object GenericObject
                Failure in setting value for object Contact element CustomFields of type generic_ws_rightnow_com_v1_3::GenericObject
                Failed in constructing object UpdateMsg : NULL input can not be deserialized
                Failed in setting value for element RNObjects array position 0 of object UpdateMsg
                Failure in setting value for object Update element Update of type messages_ws_rightnow_com_v1_3::UpdateMsg
                NULL returned from the Update deserializer due to missing or invalid XML</fault>
        </detail>
      </soapenv:Fault>
  </soapenv:Body>
</soapenv:Envelope>

This error indicates that a Null value can not be passed because the field type was a date field and "Null" is not a valid date value. Luckily there is a simple solution. Instead, try passing a field as indicated:

Notice the xsi:nil="true" on the <ns2:DataValue> tag. This tells the SOAP envelope to make this field as "NULL". Now the SOAP request should process without issue.