AchieveIt API Basics

The AchieveIt platform allows you to automate the process of publishing data to your plans and plan items using our public REST API.

Prerequisites

You will need to meet the following prerequisites in order to access the REST API. These are managed by AchieveIt and can only be enabled by request.

  • Have API access enabled on your AchieveIt organization account.
  • Have an API key and an "API Account": The API Account is an AchieveIt user to which changes made via the API are associated.
  • 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.

In addition, if you are submitting data through the API you will need to take the following additional step:

  • Set up data mappings: Each metric or item status you want to publish to AchieveIt must have a unique "external ID" defined in your existing system. Your AchieveIt Customer Success Manager will map each external ID to a plan item in one of your AchieveIt plans to ensure the correct plan items are updated in each batch update.

Submitting Data

Submit data through the API by making an HTTP POST request containing a data file to the endpoint relevant to the type of data you're publishing. For example, if you are submitting progress update data, you would call the "progressupdates" 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 data file in the body of the request.

For example (using cURL), with a data file named "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

The API responds with a Job ID and one of the following HTTP status codes:

  • 200 OK: Request has been successfully queued
  • 500 Internal Server Error: Request failed to be queued

Checking on Status of Data Processing

The 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 check the status of an update by making an HTTP GET request to the "status" endpoint corresponding with the type of data, such as in the following example for submitting progress updates:

https://api.achieveit.com/api/progressupdates/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 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" \

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

Data File

For most endpoints, you submit data in a file that you post through the HTTP request. The data file will typically be a structured format such as a Comma Separated Values (CSV) file that allows you to submit multiple records in one request.

For most endpoints, the following rules apply to CSV data files:

  • 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 shown in the template for each data file type.
  • The CSV file must not contain any empty rows.

Refer to the specific help articles and API documentation for each endpoint to see the details of the layout of each data file.

Security

In order to ensure the security of your data, the each request to the API must meet the following security requirements:

  • API Key: Each request must contain the API Key in the request header.
  • HTTPS: Each request must be made using HTTPS.

Additional Documentation

Read more about how to submit each different type of data into AchieveIt:

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

Article is closed for comments.