POST Requests

POST Requests

Overview

POST requests allow you to add or edit data in the CIMcloud platform via the API

• If a data record sent via a POST already exists, it will update it.
• If a data record sent via a POST does not exists, it will add a new record.

PUT request allow you to update existing data records in the CIMcloud platform via the API (if the data record PUT does not exist, a record will not be added).

Example: Create an Account

HTTP Method: POST

Endpoint: https://api.cimcloud.com/{sitename}/account/

Example Body:

{ 
"ref_id": "00-TEST012", 
"nm": "Test Account", 
"status": "1"
}

Successful Response:

{

"action": "DataImported",

"success": true,

"importedRecords": 1,

"updatedRecords": 0,

"recordCountInRequest": 1,

"message": null

}

Example: POSTs with Multiple JSON Objects in Payload

This is supported in the API Framework.  You can create/update multiple records within the database using an array of JSON objects:

[{
	"field1": "value1",
	"field2": "value2",
	"field3": "value3"
}, 
{
	"field1": "value1",
	"field2": "value2",
	"field3": "value3"
},
{
	"field1": "value1",
	"field2": "value2",
	"field3": "value3"
}]

Example: POSTs with Nested JSON Objects in Payload

This is currently not supported with the API Framework.  A use-case would be attempting to POST the header and detail lines of an order with one API call.  That is, you will need to make multiple POSTs to include the header and detail lines for an order.

For example, this will not work with POSTs:

{
   "field1":"value1",
   "field2":"value2",
   "field3":"value3",
   "details":[
      {
         "detail_field1":"detail_value1",
         "detail_field2":"detail_value2"
      },
      {
         "detail_field1":"detail_value1",
         "detail_field2":"detail_value2"
      },
      {
         "detail_field1":"detail_value1",
         "detail_field2":"detail_value2"
      }
   ]
}

Jobs Queue – POSTs exceeding Rate Limit

If your POST contains more than the API Framework’s limit of 10 JSON objects per POST, the HTTP response will return a jobURL endpoint.  You can make a request to this endpoint to view the status of the job (i.e. the records to be processed in our queue).

Example Response:

{
    "jobId": "XXXXXX-XXX-XXX-XXX-XXXXXXXXX",
    "jobUrl": "/jobs/XXXXXX-XXX-XXX-XXX-XXXXXXXXX",
    "action": "DataQueued",
    "success": true,
    "importedRecords": 0,
    "updatedRecords": 0,
    "recordCountInRequest": 11,
    "message": "Record Count > 10.  Inserted Into Queue. Payload Count: '11'"
}

Example: Check the status of a Job

{
    "status": "Queued",
    "recordsAdded": null,
    "recordsUpdated": null,
    "recordsDeleted": null,
    "recordsErrored": null,
    "error": null
}