Creating and Updating Data
Pepperi API uses HTTP POST as Upsert - the API checks the existence of a record by the InternalID or ExternalID and performs update or insert accordingly.
Pepperi API provides 2 types of data update methods -
- POST of a single record with the same structure you retrieve on the GET request, to update the data using POST method.
- POST of multiple records made for large sets of data using Async bulk upload resource - which gets a "flat data model" in the form of headers and lines, starts a new bulk upload job, and returns the Job ID to request the status of the upload job.
Updating Nested Objects and Parent Objects
The API allows updating of relations between an object and its Parent objects such as Transaction>>Account or Nested objects such as Account>>Users.
That means you can change the assignment of a transaction to a different account , but cannot change the account's name through the transaction.
Data relations updates are supported both through the InternalID and the ExternalID , so that for example you can change the account's default Price Level to a different one using either the account's InternalID or ExternalID.
The only exception is Transaction>>Transaction Lines, it's the only POST method we enabled updating nested resource = transaction_lines from its parent resoure = transaction, and the reason for it is the nature of transaction resource that usually has no meaning without its lines.
include_nested Query Parameter
Nested objects - one to many relation - such as Transaction>>TransactionLines - has to be updated by overwriting the entire nested list by a new one , or setting the list to null or empty list to remove the entire list from the Parent object.
If you wish to avoid updating nested objects through the Parent, you need to set
include_nested=false (default is true) , this is useful when you perform GET with
include_nested=false and wish to use the result s and update Parent object fields only, in such case not setting the include_nested to false will result in detaching all relations to the Parent object.
Bulk upload of customizable resources
Since bulk upload structure is a flat tabular structure - and the user defined fields of each customizable resource is different from one sub type to the other, such as Transaction>>Sales Order , and Transaction>>Invoice - therefore, you must specify the subTypeId within each bulk upload request to: transaction, transaction_lines, activities. e.g:
You should get the sub type names and corresponding ids using the metadata API (Customization Resources).
Regarding the Account resource - since there is a default account type its not mandatory to specify the subTypeId, unless you need to upload data to a different account type.
Bulk upload of JSON or CSV ZIP files
Bulk upload is supported in 2 forms: JSON and a single CSV file inside a ZIP file , for example and
While json is a standard format , CSV files should be UTF-8 encoded, and comma demilited.
For csv_zip we support 2 types of Body and Content-Type : either application/zip and binary data , or multipart/form-data and
binary encoded in a multipart body - please note that only 1 zip file should be per each multipart body - the rest will be ignored.