AchieveIt allows you to automate the process of publishing metric updates to plan items by submitting a CSV file containing the requested updates to our public REST API. For more information on the general aspects of the AchieveIt REST API, read our help article on API basics.
Metric Update Data File
Submit metric updates by POSTing the metric updates in a CSV (Comma Separated Values) file.
These are the attributes to include in the CSV file for each metric update:
Field Name |
Required |
Comment |
External ID |
yes |
This value is generated by AchieveIt and can be accessed by clicking the Export External IDs option in the row action menu on plans for which you are an admin. |
Current Metric Value |
yes |
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 metric 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. |
Comment |
no |
The comment associated with the metric update. This column can optionally be excluded if you do not want comments on any of your imported updates. |
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 must be External ID, Current Metric Value, As Of Date, and Comment (optional).
- The CSV file cannot contain any empty rows.
A sample CSV file is attached to the end of this article.
Submitting Updates
Updates can be submitted by making an HTTP POST request to one of the following endpoints, depending on which environment your organization uses:
- Non-government environment: https://api.achieveit.com/api/metricupdates/<filename of CSV>
- Government environment: https://gov-api.achieveit.com/api/metricupdates/<filename of CSV>
If you are un-sure which environment you use, please contact your Customer Success Manager for guidance.
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, with a CSV title ‘my_updates.csv’ and an API key of ‘12004478285f4f4eb21cd25e62ba5eb7’, your request would look like one of the following:
// Bash (Non-Government environment)
curl -L -XPOST \
-H "Authorization: API-KEY 12004478285f4f4eb21cd25e62ba5eb7" \
--data-binary "Path_To_File_On_Harddrive/my_updates.csv" \
https://api.achieveit.com/api/metricupdates/my_updates
// PowerShell (Non-Government environment)
Invoke-RestMethod -Uri "https://api.achieveit.com/api/metricupdates/my_updates" `
-Method Post `
-Headers @{ "Authorization" = "API-KEY 12004478285f4f4eb21cd25e62ba5eb7" } `
-InFile "Path_To_File_On_Harddrive/my_updates.csv" `
-ContentType "application/octet-stream"
// Bash (Government environment)
curl -L -XPOST \
-H "Authorization: API-KEY 12004478285f4f4eb21cd25e62ba5eb7" \
--data-binary "Path_To_File_On_Harddrive/my_updates.csv" \
https://gov-api.achieveit.com/api/metricupdates/my_updates
// PowerShell (Government environment)
Invoke-RestMethod -Uri "https://gov-api.achieveit.com/api/metricupdates/my_updates" `
-Method Post `
-Headers @{ "Authorization" = "API-KEY 12004478285f4f4eb21cd25e62ba5eb7" } `
-InFile "Path_To_File_On_Harddrive/my_updates.csv" `
-ContentType "application/octet-stream"
In the above code examples, ensure you replace "Path_To_File_On_Harddrive" with the correct file path. The API responds with a Job ID and a 200 OK status code to indicate the upload was successfully queued for processing.
Checking on Status of Data Processing
The AchieveIt API does not process update requests immediately or synchronously. It pushes each request to a queue and the system subsequently processes 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 an HTTP GET request to one of the following endpoints:
- Non-government environment: https://api.achieveit.com/api/metricupdates/status/<Job ID>
- Government environment: https://gov-api.achieveit.com/api/metricupdates/status/<Job ID>
The system will respond with an HTTP status code indicating the state that your request is currently in:
- 202 Accepted: Request is received or is currently being processed
- 200 OK: Request has been successfully processed
- 400 Bad Request: Request has failed to be processed
- 500 Server Error: Request has failed to be processed
An example request with the same API key as before and a job ID of 2bf2dda7-2aa4-4345-b6a8-8070d6ceec39:
// Bash (Non-government environment)
curl -i -XGET \
-H "Authorization: API-KEY 12004478285f4f4eb21cd25e62ba5eb7" \
https://api.achieveit.com/api/metricupdates/status/2bf2dda7-2aa4-4345-b6a8-8070d6ceec39
// PowerShell (Non-government environment)
Invoke-RestMethod -Uri "https://api.achieveit.com/api/metricupdates/status/2bf2dda7-2aa4-4345-b6a8-8070d6ceec39" `
-Method Get `
-Headers @{ "Authorization" = "API-KEY 12004478285f4f4eb21cd25e62ba5eb7" }
// Bash (Government environment)
curl -i -XGET \
-H "Authorization: API-KEY 12004478285f4f4eb21cd25e62ba5eb7" \
https://gov-api.achieveit.com/api/metricupdates/status/2bf2dda7-2aa4-4345-b6a8-8070d6ceec39
// PowerShell (Government environment)
Invoke-RestMethod -Uri "https://gov-api.achieveit.com/api/metricupdates/status/2bf2dda7-2aa4-4345-b6a8-8070d6ceec39" `
-Method Get `
-Headers @{ "Authorization" = "API-KEY 12004478285f4f4eb21cd25e62ba5eb7" }