1. Satuit Technologies Learning Center
  2. Knowledge Base
  3. SatuitSDX® | Secure Data Exchange, Bulk, and REST API

Satuit Bulk API

What is Bulk API

The Bulk API is a RESTful API that is optimal for loading, updating or exporting large sets of data. You can use it to query, insert, update, and export large quantities of records asynchronously by submitting batches that SatuitCRM processes in the background. The Satuit Bulk API requires developer-level programming skills (MS.net) and is designed to transfer large amounts of data, conduct large API data loads, and extract data in an efficient manner.

The Bulk API uses the data mapping provided by SatuitCRM's standard Import Tools to enable the mapping of fields from the external sources into Satuit's data structure. The addition of the Bulk API enables our user community to automate the integration with other key industry software including data warehouses, portfolio accounting systems, fund administrators, eMarketing tools, and billing software.

From an export perspective, the Bulk API exports data based on reports and Saved Views which may be set to run automatically. This data can then be used in multiple ways including populating client reporting and eMarketing tools, analytic tools such as PowerBI, or allow clients to do their own transformations/calculations on the data and reimport into Satuit.

When to Use Bulk API

The Bulk API is based on REST principles and is optimized for loading or deleting large sets of data. You can use it to query, queryAll, insert, and update, many records asynchronously by submitting batches. These batches are processed in the background and normally scheduled during off-peak hours.

SOAP API, in contrast, is optimized for real-time client applications that update a few records at a time. You can use SOAP API for processing many records but is less practical when the data sets contain hundreds of thousands of records. The Bulk API is designed to make it simple to process data from a few thousand to millions of records.

 

How Bulk API Works

ONLINE SAMPLES & DOCUMENTATION
https://documenter.getpostman.com/view/20721034/UyxnDPxN

 

SESSION TOKENS

A Session token is used as your security token for all API calls after the initial call. A Session token is created by calling a GET request from the API Token service providing it a username, password, and APIKey. The session token is then used as the sole authentication means for all other calls. A Session token has a limited lifespan. If you try to use an expired session token, you will receive an unauthorized error. Call the token service again to get a new session token.

IMPORTS

You process a set of records by creating a job. The job imports or updates a set of data. The fields and what type of operation is being used by using Templates created in the Import Tool. A list of Templates can be retrieved through the API through a call to the Template service. A job is a set of records sent to the server in an HTTP POST request. Each job is processed independently by the server, not necessarily in the order it is received. Jobs may be processed in parallel.

Processing data typically consists of the following steps:

  1. Create a new job that specifies the object and action
  2. Send data to the server in a single CSV file
  3. Check the status periodically until the status is “Completed”. When the job is completed, check the result by retrieving an exception report

EXCEPTION REPORTS

Exception reports are used to show anything that could have gone wrong in the Import Process. They are retrieved through a GET request to the Bulk API. Once a job’s status is “Complete”, an exception report is available to download. The file is a CSV and the format is a header row that was included in the original Import file. For each row that had an error, the entire row will be included in the file, with the exception being the last column. If the import was 100% successful, there will still be an Exception Report but it will only contain the header row.

Retrieving an Exception Report consist of the following steps:

  1. Check the status of Import Job, until it is “Completed”
  2. Download the exception report as a CSV from the API 

Bulk API URL

Throughout the document, please replace the ellipse (…) in the URLs below with the URL for your production site. For example, if your URL is https://www2.satuitcrm.com/sitename, use the BULK API https://www2.satuitcrm.com/sitename/api/v1/bulk/.

Setting-Up And Authenticating The Session

The Satuit Bulk API allows for a Session Token to be created for continued use for the functions throughout this documentation.

The steps below can help establish the session:

  1. Performing a GET to get the session token
  2. Steps: '…api/v1/bulk/token/' this gets the token that is used to create authentication
  3. Request parameters are needed:
    • Username (username of the rep)
    • Password (rep's CRM password)
    • apikey (provided by Satuit, only one per client)

The session token will reset based on a predetermined amount of time set by the user.

  • From there, a Response is created, and it is broken down as such:
  • Message - string
  • Result:
    • Access Token - string
    • Rep - string
    • Created - datetime
    • ExpiresIn - integer
    • ApiKey - string
  • QuotaUsage - string
  • Additional Message - string

Returning Import Templates

To determine which import templates are available, you can perform a GET to return a list of import templates used by following the below steps:

  1. '…api/v1/bulk/template/'
  2. To access this, you will need to use the Session Token created above
  3. Request parameter:
    • sessiontoken
  4. This returns a list of the import templates within Satuit

After you receive a list of templates, the Response includes the following:

  • Message - string
  • Result - a list of the templates:
    • Template - int
    • TemplateName - string
    • ImportType - string
    • MapDescription - string
    • CreatedOn - datetime
    • CreatedBy - string
    • UpdatedOn - datetime
    • UpdatedBy - string
    • LastUsed (nullable) - datetime
  • QuotaUsage - string
  • AdditionalMessage - string

Running The Import

To import data into Satuit, run a POST to push in the Import Template using the steps below:

  1. '…api/v1/bulk/job/' - This allows the user to upload the file to the API
  2. Request Parameters:
  3. A file is required to run the POST and the import document to be mapped correctly to the template

The Response includes the following:

  • Message - string
  • Result - Job Information:
    • JobID - int
    • JobStatus - string
    • QuotaUsage - string
    • AdditionalMessage - string

Tracking The Job

Follow the steps below to get the Status of the Job:

  1. '…api/v1/bulk/Job/JobID' - Just like the CRM's outputs field has the status of the job, this can be leveraged for that as well
  2. Request parameters:
    • sessiontoken from above - passes as header parameter
  3. URL Parameters:
    • Jobid used as a URL parameter: '…api/v1/bulk/job/jobid' that is returned above

The Response includes the following:

  • Message - string
  • Result - Job Information:
    • JobID - int
    • JobStatus - string
    • Created - DateTime
    • Updated - DateTime
    • Operation - string
    • ResultDescription - string
    • RequestType - string
    • QuotaRemaining - int
    • QuotaResestDate - DateTime
  • QuotaUsage - string
  • AdditionalMessage - string

Accessing The Exception Report

Like any import within Satuit, there is the ability to access an Exception Report. This can be retrieved by:

  • '…api/v1/bulk/exceptionfile/JobId/' - Performs a GET function to return the Exception File
  • Request Parameters:
  • URL Parameters:
    • JobID used within the URL from the job run

The Response returned is the file contents from the report.

Note

The job must be finished before you can access the Exception Report.

Accessing Saved Views

The Satuit Bulk API is able to return a list of Saved Views through the following GET procedure:

  1. '…api/v1/bulk/savedviews' - Returns a list of Saved views in Satuit -- this reflects the users existing permissions on what available saved views they have access to
  2. Request parameters:
    • Sessiontoken provided above

The Response includes the following:

  • Message - string
  • Result - List Of:
    • SavedView:
    • SavedViewId - int
    • Name - string
    • Scope - string
    • UpdatedBy - string
    • LastUsedOn - DateTime
    • UpdatedOn - DateTime
  • QuotaUsage - string
  • AdditionalMessage - string

Returning Saved View Results

To access the results of a Saved View:

  1. '…api/v1/bulk/SavedViews/SavedViewID' - Use this to pull back the contents of a Saved View
  2. Parameters:
  3. URL Parameters:
    • SavedViewID

The Response returned is the file contents from the Saved View.

Returning Report ID's

Similar to accessing Saved View ID's, the same steps can be followed to access Report ID's through a GET procedure:

  1. '…api/v1/bulk/Reports
  2. Returns a list of Reports within Satuit
  3. Request parameters:
    • Sessiontoken provided above

The Response includes the following:

  • Message - string
  • Result - List Of:
    • ReportID - int
    • Name - string
    • Description - string
    • UpdatedBy - string
    • LastUsedOn - DateTime
    • UpdatedOn - DateTime
  • QuotaUsage - string
  • AdditionalMessage - string

Reporting Through Bulk

Follow these steps to run a report through the Bulk API using a POST procedure:

  1. '…api/v1/bulk/Reports?id=XXX&SavedviewId=YYY
  2. Parameters:
    • Sessiontoken from above
    • Reportformat - output of values:
      • "PDF"
      • "EXCEL"
      • "HTML4.0"
      • "CSV"
      • "WORD"
      • "XML"
  3. URL Parameters:
    • XXX = the ReportID
    • YYY = Saved View ID

The Response includes the following:

  • Message - string
  • Result - Report Information:
    • ReportJobID - int
    • ReportStatus - string
  • QuotaUsage - string
  • AdditionalMessage - string

Tracking The Report

To get the Status of the Report, use the following:

  1. '…api/v1/bulk/Reports/Status/ReportJobID' - Just like the CRM's outputs field has the status of the report, this can be leveraged for that as well
  2. Request parameters:
  3. URL Parameters:
    • ReportJobID used in the URL

The Response includes the following:

  • Message - string
  • Result: o ReportID - int
    • ReportJobID - int (used to download the file and check on the status)
    • ReportStatus - string
    • StatusDescription - string
    • RequestType - string
    • Created - DateTime
    • Updated - DateTime
    • Operation - string
    • QuotaRemaining - int
    • QuotaResestDate - DateTime
  • QuotaUsage - string
  • AdditionalMessage - string

Downloading The Report

Following completion of a report, you can access that report through the API through a GET request:

  1. '…api/v1/bulk/reports/Download/ReportJobID/' - This downloads the requested file. Please note, you will receive an error message if the report is not complete
  2. Request parameters:
    • Sessiontoken
  3. URL Parameters:
    • ReportJobID

The Response returned is the file contents.

Troubleshooting

    401 Error Message:
    • You have provided an invalid username, password, or API Key
  • 400 Error Message:
    • Check to ensure the settings are configured properly on the machine
  • 400 Error Message: Bad Request:
    • Missing ReportJobID in URL
    • ReportJobID Not Found
    • Report Not Complete
    • Invalid Saved View ID
    • Missing parameters (reportformat, savedviewid, reportid)
    • Incorrect file format
    • ReportId Not found
    • SavedViewID not found
    • Missing parameters
    • File count not equal to 1
    • Template does not exist
    • Number of rows exceeds the Max rows per job amount
    • Exceeded Max Concurrent Jobs
    • Exceeded Quota limit
Was this article helpful?
0 out of 0 found this helpful

Articles in this section