For Developers

Getting Started

There are three steps for creating and submitting assessments with the Mitrend API:

  • First an assessment is created and an assessment identifier is returned.
  • The assessment identifier is used to attach assessment files to the assessment.
  • After all files are attached, the assessment can be submitted.

Authentication

The API supports Basic Authentication as defined in RFC2617.

The following is an example of accessing the API via cURL using Basic Authentication. In this example, cURL will prompt the user for the password:

curl -u <email> https://app.mitrend.com/api/assessments/<assessment_id>
In this example, cURL will not prompt the user for the username and password as they are included:
curl -u <email>:<password> https://app.mitrend.com/api/assessments/<assessment_id>

Create an Assessment

The first step is to create an assessment, which will provide a grouping for the files that will be uploaded.

Request

POST /api/assessments - application/x-www-form-urlencoded
curl -u <email>:<password> -X POST -d assessment_name="Test Assessment From Api" -d "company=A Cool Customer Company Name" -d city=Marlborough -d country=US -d state=MA -d timezone="US Eastern" https://app.mitrend.com/api/assessments

Another option is to send the data in JSON format. Using this format you can also include tags and attributes.

Request

POST /api/assessments - application/json
curl -u <email>:<password> -X POST -H "Content-Type: application/json" -d "{\"assessment_name\":\"Test Assessment From Api\",\"company\":\"A Cool Customer Company Name\",\"city\":\"Marlborough\",\"state\":\"MA\",\"country\":\"US\",\"tags\":[\"FIRST TAG\",\"ANOTHER TAG\"],\"attributes\":{\"First Attribute\":\"First Value\",\"Second Attribute\":\"Second Value\",\"sfdc_account_id\":\"MY_SALESFORCE_ID\",\"opportunity_number\":\"MY_OPPORTUNITY_NUMBER\"}}" https://app.mitrend.com/api/assessments

Parameters

Response

Status: 200 OK
{
   "data": {
      "id": 12345,
      "assessment_name": "Test Assessment From Api",
      "company": "A Cool Customer Company Name",
      "city": "Marlborough",
      "state": "MA",
      "country": "US",
      "timezone": null,
      "status": "Draft",
      "attributes": {
         "First Attribute": "First Value",
         "Second Attribute": "Second Value",
         "sfdc_account_id": "MY_SALESFORCE_ID",
         "opportunity_number": "MY_OPPORTUNITY_NUMBER"
      },
      "tags": [
         "FIRST TAG",
         "ANOTHER TAG"
      ],
      "files": []
   }
}

Adding Files

After an assessment is created, input files must be attached for processing. Notice the @ symbol in the following command. This is cURL syntax for attaching a file. Replace <assessment_id> with the id you received in the json block after creating the assessment. Remember to replace EMC_Grab with the correct device_type for your submission. The full list can be found in the parameters table below.

Request

POST /api/assessments/<assessment_id>/files
curl -u <email>:<password> -X POST --form device_type="EMC_Grab" --form file=@SOME_LOCAL_FILE.zip https://app.mitrend.com/api/assessments/<assessment_id>/files

Or if you want to use an FTP URL.

Request

POST /api/assessments/<assessment_id>/files
curl -u <email>:<password> -X POST --form device_type="EMC_Grab" --form ftp_url="ftp://someftphoster.com/something_file.zip" https://app.mitrend.com/api/assessments/<assessment_id>/files

Parameters

Response

Status: 200 OK
{
   "data": {
      "id": 54321,
      "deleted": false,
      "assessment_id": 12345,
      "file": "api.test.js",
      "device_type": "EMC_Grab"
   }
}

Submitting an Assessment

After all of the input files are uploaded, an assessment can be submitted. After an assessment is submitted, no additional files can be attached.

Request

POST /api/assessments/<assessment_id>/submit
curl -u <email>:<password> -X POST https://app.mitrend.com/api/assessments/<assessment_id>/submit

Response

Status: 200 OK
{
   "data": {
      "id": 12345,
      "assessment_name": "Test Assessment From Api",
      "company": "A Cool Customer Company Name",
      "city": "Marlborough",
      "state": "MA",
      "country": "US",
      "timezone": null,
      "status": "Submitted",
      "attributes": {
         "First Attribute": "First Value",
         "Second Attribute": "Second Value",
         "sfdc_account_id": "MY_SALESFORCE_ID",
         "opportunity_number": "MY_OPPORTUNITY_NUMBER"
      },
      "tags": [
         "FIRST TAG",
         "ANOTHER TAG"
      ],
      "files": [
         {
            "id": 54321,
            "deleted": false,
            "assessment_id": 12345,
            "file": "ftp://lksdjf.com/lksdjf.txt",
            "device_type": "EMC_Grab"
         },
         {
            "id": 4532,
            "deleted": false,
            "assessment_id": 12345,
            "file": "api.test.js",
            "device_type": "EMC_Grab"
         }
      ]
   }
}

Pre-populated Upload Page

Many of the fields on the upload page can be pre-populated by constructing the URL and sharing the constructed URL with a user. Normally the URL to the uploaded page looks like this:

  https://app.mitrend.com/#upload

The fields on the page can be pre-populated by modifying the URL with name value pairs using the following format:

https://app.mitrend.com/#upload/company=MyCustomerName/city=Boston/state=MA/country=US

Notice how the following fields were added to the URL: company, city, state, country. If you click on the above link, you will notice that some of the form fields on the Upload page have been pre-populated. The same concept works with custom attributes. For example, if you would like to tag your assessment with a project ID the URL would be the following:

https://app.mitrend.com/#upload/project=ABC_12345

If you click on the above link, you will notice that the assessment now has the tag "project : ABC_12345".

If you'd like to create a link that will include a specific Salesforce.com ID or an Opportunity Number, use the following format:

https://app.mitrend.com/#upload/sfdc_account_id=MY_SALESFORCE_ID/opportunity_number=MY_OPPORTUNITY_NUMBER

Email Report

The XML report bundle email can be triggered programmatically via our API.

Request

POST /api/assessments/<assessment_id>/report
curl -u <email>:<password> -X POST https://app.mitrend.com/api/assessments/<assessment_id>/report

Response

Status: 200 OK
{
   "data": [
      {
         "id": 12356,
         "deleted": false,
         "assessment_id": 54321,
         "title": "AwesomeReport_Storage_XML_Rw2ZrdI.zip",
         "device_type": null,
         "fileType": "XML_REPORT_BUNDLE",
         "status": null
      }
   ]
}