5. Data Action

• URL:

/RestApi/DataAction/<objectName>?authToken=<authToken>&action=<insert|update|upsert|delete>&matchingFieldName=<matchingFieldName>&useExternalId=<false|true>

• Method: POST
• URL Params:
  • objectName [string] [Required]=the name of the object that the user wants to insert/update/upsert/delete records from
  • authToken [string] [Required]=the authentication token
  • action [string] [Required]=the action that the user wants to apply (insert, update, upsert or delete)
  • matchingFieldName [string] [Required]=the name of the field that is considered to be the unique field in the sent records
  • The “useExternalId” parameter is optional. And if not sent in the URL it will take the default value which is “true”.
    If “useExternalId”=true then when importing data through the Rest API, the lookup fields will have to be set to the value in the “External Id” field of the lookup record.
    
    If “useExternalId”=false or there are no “External Id” field set on the parent object, then when importing data through the Rest API, the lookup fields will have to be set to the “Id” field of the lookup record.

Example:

If we want to import following Contact record through the Rest API (field “Account” is a lookup field to the “Account” parent object and the “Name” field on the “Account” object is an “External Id” field):

1- If useExternalId is not set or set to “true”:

<Data><Contact><FirstName>Sarah</FirstName><LastName>Johnson</LastName><Account>Test Account 1</Account></Contact></Data>

2- If useExternalId is set to “false”:

<Data><Contact><FirstName>Sarah</FirstName><LastName>Johnson</LastName><Account>2458939956261816452</Account></Contact></Data>

where lookup record “Account” is:

Id	Name
2458939956261816452	Test Account 1

• Data Params:
  • xmlData [XML]=the data records to insert/update/upsert/delete

Example:

<Data>
<Account>
<Name>

Account Test 1

</Name>

<Address>

Address Test 1

</Address>
</Account>

<Account>
<Name>

Account Test 2

</Name>

<Address>

Address Test 2

</Address>
</Account>
</Data>

When sending data parameters from a php page and having a field of type « Datetime », we must put this function urlencode() in order not to lose the “+” sign on the server side and to be saved correctly in the database.

If the function is not used, the value will saved without the “+” sign like this “2017-06-12 15:40: 47 02 ” instead of “2017-06-12 15:40: 47+02 “.

Example of using urlencode() :

$ xmlData =  urlencode (
"<Data>"

"<Campaign>"

"<Name> Campagne-". $ CampaignID. "</Name>"

"<Campaign_ID>". $ CampaignID. "</Campaign_ID>"

"<TestDateTime>"2017-06-12 15: 40: 47 + 02"."</TestDateTime>"

"<OwnerId>".$ OwnerID. "</OwnerId>"


"<Campaign>"


"<Data>"


);

• Success Response:
  • Status Code=200 (OK)
  • Returned Data [in XML or JSON]=a list of the data records sent in the HTTP Post Request body with 2 additional fields for each record (1- Success (to indicate if the operation (insert/update/upsert/delete) applied on the corresponding record was successful or not), 2- ErrorMessage (to indicate what is the error that caused the operation applied on this record to fail (in case of unsuccessful operation)))

Example of returned data:

<Data>
<Account>
<Name>

Account Test 1

</Name>

<Address>

Address Test 1

</Address>

<Success>

FALSE

</Success>

<ErrorMessage>

Some of the Lookup Fields contain invalid values

</ErrorMessage>
</Account>

<Account>
<Name>

Account Test 2

</Name>

<Address>

Address Test 2

</Address>

<Success >

TRUE

</Success>

<ErrorMessage />
</Account>
</Data>

• Error Response:
  • Status Code=401 (Unauthorized) (in case of a wrong authentication token)
  • Or
  • Status Code=400 (BadRequest) (in case no object name was specified or no action was specified or there is an error in the xml data records sent in the HTTP Post Request body or if one record or more could not be inserted/updated/upserted/deleted)