Using the AchieveIt API for Data Integration

The AchieveIt platform allows you to automate the process of publishing progress updates to your plans and plan items by submitting a CSV file containing the requested updates to our public REST API.

Progress Updates

Prerequisites

You will need to meet the following prerequisites in order to submit progress updates through the API. These are managed by AchieveIt and can only be enabled by request.

  1. Have API access enabled on your AchieveIt organization account.
  2. Have an API key and an “API Account.” The API Account is an AchieveIt user to which changes made via the API are associated.
  3. Set up plan item mappings. Each plan item which will be mapped to external IDs that correspond to your existing systems (such as a financial or CRM system, for example). Your AchieveIt Customer Success Manager will map the plan item IDs to your external IDs to ensure the correct plan items are updated in each batch update.
  4. Designate a point of contact within your organization that will be associated with the API connection. This point of contact is who AchieveIt will proactively communicate with should we encounter any API failure.

Update Components

Customers have the ability to import data that creates a progress update, including the Update Date, Status, and Metric Value, either on a one-time or ongoing basis.

Structuring the CSV File

A sample CSV file is attached to this article.

These are the attributes to include in CSV file for each progress update:

Field Name

Required

Comment

External ID

yes

External ID names cannot contain the phrase “external.” It can contain spaces and special characters, with the exception of commas and quotation marks.

Status

yes

The status must be one of the current AchieveIt statuses. Capitalization does not matter, but spelling must be the same. Statuses include:

  • On Track
  • Off Track
  • At Risk
  • Achieved
  • Not Achieved
  • Canceled
  • Not Started

Current Value

yes, if the item has
a metric

Percentages should be formatted in decimal format – for example, 20% should be input as .2, rather than 20.

As Of Date

yes

This is the date for the progress update. The date can be formatted in any ISO-8601 compliant date format. Most of our customers use regular US date format – MM/DD/YYYY. AchieveIt only uses the date, so if you include a time in the As Of Date value, AchieveIt will ignore it.

A few additional items to note when building your CSV file:

  • You can choose to include or exclude column headers. If you choose to include them, the first column must be labeled External ID.
  • Columns must be in the same order as our template. From left to right, the columns should be External ID, Status, Current Value, and As Of Date.
  • Currently, we do not support empty rows in the CSV file.

Submitting Updates

Updates can be submitted by making an HTTP POST request to the following endpoint: https://api.achieveit.com/api/progressupdates/<filename of CSV>

You must include the API key as part of an authorization header. The header needs to be in the following form:

Authorization: API-KEY <API_KEY>

Include your CSV in the body of the request.

For example (using cURL) - with a CSV title ‘my_updates.csv’ and an API key of ‘12004478285f4f4eb21cd25e62ba5eb7’, your request would look like the following:

curl -L -XPOST \

    -H 'Authorization: API-KEY 12004478285f4f4eb21cd25e62ba5eb7' \

    --data-binary "@my_updates.csv" \

    https://api.achieveit.com/api/progressupdates/my_updates.csv

The API does not process update requests immediately or synchronously. It will push the request to a queue and the system  will subsequently process the updates. Except for the cases of invalid requests (authorization header is missing or is malformed, unexpected server error, etc.), your HTTP request should immediately return with a 200 OK response as well as a job ID which you can use to query the status of your batch update request.

You can request the status of a batch update by making a HTTP GET request to the following endpoint:

http://api.achieveit.com/api/progressupdates/status/<UNIQUE_IDENTIFIER>

You will get a different response depending on the state that your request is currently in:

  • Request is received or is currently being processed: 202 Accepted.
  • Request has been successfully processed: 200 OK.
  • Request has failed to be processed: 400 Bad Request or 500 Server Error.

An example request using cURL with the same API key as before and a job ID of 2bf2dda7-2aa4-4345-b6a8-8070d6ceec39:

curl -LI -XGET \

    -H 'Authorization: API-KEY 12004478285f4f4eb21cd25e62ba5eb7' \

    http://api.achieveit.com/api/progressupdates/status/2bf2dda7-2aa4-4345-b6a8-8070d6ceec39

Request Reference

Push updates

curl -L -XPOST \

    -H 'Authorization: API-KEY <API_KEY>' \

    --data-binary "@<updates_file>.csv" \

    https://api.achieveit.com/api/progressupdates/<updates_file>.csv

Response

  • 200 OK if request has been successfully queued
  • 500 Internal Server Error if request failed to be queued

Get Status

curl -LI -XGET \

    -H 'Authorization: <API_KEY>' \

    http://api.achieveit.com/api/progressupdates/status/<UNIQUE_IDENTIFIER>

Response

  • 202 Accepted: Request is received or is currently being processed.
  • 200 OK: Request has been successfully processed.
  • 400 Bad Request or 500 Server Error: Request has failed to be processed.

Additional Documentation

The API is also documented via Swagger, which can be accessed at the following URL:
https://api.achieveit.com/swagger/.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.