Aphex Data API V2

Aphex Product Team Updated by Aphex Product Team

This is the V2 Aphex Data API. Is your Organisation still using V1? Find the info here.

Overview

Teams using Aphex generate vast amounts of data that would normally get wiped off whiteboards or stored in spreadsheets, never seeing the light of day. The Aphex Data API is designed to help you maximise the value of your data by providing access to the true story of what did, and didn't happen on site.

The Aphex Data API is available on the Aphex Enterprise plan

Structure

The API is designed to be called daily. Calling will provide you a list of task events, ordered chronologically, that you can use to reconstruct the data held in Aphex.

Events are generated by users creating, updating and deleting tasks as well as attaching day level delay and resource allocation.

The events are structured so that you can apply them directly to your copy of the tasks, giving you an up-to-date view on what did and didn't happen across all of your projects.

Calling the API

Calling the API is as simple as making a HTTP GET request to our endpoint https://europe-west2-aphex-prod.cloudfunctions.net/apiTaskEventsV2

To fetch the events since you last called we support the following query parameter:

  • startAfter : The most recent eventId from the events you've received.
    • For subsequent calls, this value can also be found on the nextStartAfter property at the root of the previous response
    • Calls that omit this parameter will return from the Organisation's first event

Along with the call you must include a custom header, x-api-key, with your organisation API key which was provided to you as part of your enterprise onboarding.

An example:

curl -X GET -H 'x-api-key: 6fa9a827da2ca37ae4057e4ae861c6b3' https://europe-west2-aphex-prod.cloudfunctions.net/apiTaskEventsV2?startAfter=57e4ae861c6b3

Make sure you use HTTPS and not HTTP - our API rejects requests made over HTTP, since this sends your API Key over the internet in plain text.

API Response

The response from the API is a chronological list of events.

There are 3 event types:

  1. TaskCreated : Triggered when a user creates a task. Contains the created task.
  2. TaskUpdated : Triggered when a user updates a task, attaches a delay or updates the resource allocation. Contains the full task.
  3. TaskDeleted : Triggered when a user deletes a task. Contains the id of the deleted task.

Task Created

Any task created will return an event payload with same attributes and order as below.

{
"data": [
{
"apiVersion": "v1",
"createdAt": 1614587767389,
"eventId": "FO8097npw2KzZaFoya1O",
"task": {
"calendar": "Five Day",
"duration": 1,
"end": 1614297600000,
"externalId": "",
"id": "6LFkmZqBmdA4oByyLP2N",
"labourResources": {
"Carpenters": 4,
},
"location": "",
"materialResources": {
"Concrete Panels": 24,
},
"name": "New Task",
"ownerEmail": "e.williams@aphex.co",
"ownerName": "Elliot Williams",
"packageId": "2349mgeg43ksgmerer",
"parentId": "",
"plantResources": {
"100T Excavator": 2,
},
"projectExternalId": "234mfksd433m45ks",
"projectId": "U2qmd9CVWG0k5EvFxlp9",
"projectName": "Aphex Fire",
"shift": "day"
"start": 1614211200000,
"statuses": [
{
date: 1614902400000,
type: "onSchedule"
name: "On Schedule",
value: -2,
addedBy: "e.musk@tesla.com",
createdAt: 23423423523,
},
{
date: 1614905300000,
type: "delay"
name: "Insufficient Resources",
category: "Resources",
value: 2,
addedBy: "e.musk@tesla.com",
createdAt: 23423423523,
}
],
"subcontractor": "",
"successors": [fasdwr4gen2nbReyLP2N],
"wbsPath": "",
},
"type": "TaskCreated"
}, // ...
],
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",
}

Task Updated

Any task updated will return an event payload with same attributes and order as below.

{
"data": [
{
"apiVersion": "v1",
"createdAt": 1614587767389,
"eventId": "FO8097npw2KzZaFoya1O",
"task": {
"calendar": "Five Day",
"duration": 1,
"end": 1614297600000,
"externalId": "",
"id": "6LFkmZqBmdA4oByyLP2N",
"labourResources": {
"Carpenters": 4,
},
"location": "",
"materialResources": {
"Concrete Panels": 24,
},
"name": "New Task",
"ownerEmail": "e.williams@aphex.co",
"ownerName": "Elliot Williams",
"packageId": "2349mgeg43ksgmerer",
"parentId": "",
"plantResources": {
"100T Excavator": 2,
},
"projectExternalId": "234mfksd433m45ks",
"projectId": "U2qmd9CVWG0k5EvFxlp9",
"projectName": "Aphex Fire",
"shift": "day"
"start": 1614211200000,
"statuses": [
{
date: 1614902400000,
type: "onSchedule"
name: "On Schedule",
value: -2,
addedBy: "e.musk@tesla.com",
createdAt: 23423423523,
},
{
date: 1614905300000,
type: "delay"
name: "Insufficient Resources",
category: "Resources",
value: 2,
addedBy: "e.musk@tesla.com",
createdAt: 23423423523,
}
],
"subcontractor": "",
"successors": [fasdwr4gen2nbReyLP2N],
"wbsPath": "",
},
"type": "TaskUpdated"
}, // ...
],
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",
}

Task Deleted

Any task deleted will return an event payload with same attributes and order as below.

{
"data": [
{
"apiVersion": "v1",
"createdAt": 1614587776549,
"eventId": "HLoT3X3nyCAbGFDdcXdQ",
"task": { "id": "8xH9q2IptPRYnYDMjc3J" },
"type": "TaskDeleted"
},
],
"nextStartAfter": "GnYlE9ElFv2X38crCR1f",
}

Statuses

In Aphex, status is recorded as a collection of events that are in turn attached to tasks. Status events record the interactions of the team as they update and adjust their committed plans and can reflect positive or negative status events.

Status events are attached to tasks under the statuses tag and have the following attributes;

  1. date : The date that the status event is attached to in Unix Epoch time format
  2. type : The Type of Status Event;
    1. delay : A delay has been logged on this task or the task has been extended in duration
    2. shortened : The task has reduced in duration
    3. completed : The task is completed
    4. onSchedule : The task is confirmed as on schedule
    5. completedEarly : The task was completed early than planned
  3. name : The display name of the event (either a display format for a positive event such as "On Schedule" or the delay reason for a negative event such as "Awaiting Access" for an event type delay)
  4. value : The value or quantum of the status event. This indicates the impact of the change to the completion date of the task. A positive value indicates a delay and a negative value indicates an improvement.
  5. category : The Delay Category for the Delay Reason contained in the name. If the event is not a delay, this will be blank. The Delay Category will represent the current category assigned to the Delay Reason i.e. if Delay Reason "Awaiting Access" was changed to "Access" Delay Category then future delay events will contain the new category value whilst previous events will not be retriggered (in order to avoid excessive noise in the API). You can chose to look for these changes in order to update your reference tables or simply store them as they are.
  6. addedBy : The User that generated the status event (by email)
  7. createdAt : The date that the status event is created in Unix Epoch time format

API Limits

We place limits on our API to ensure its availability and responsiveness. The limits are;

  • Responses have a page limit of 4000 events
  • Organisations have a daily limit of 20,000 task events per day

If you find this limit restrictive please contact us at hello@aphex.co and we can adjust your limit to something more suitable.

HTTP Response Codes

  • 200 OK - your data will be in the body of the response
  • 204 No Data - your request returned no data
  • 400 Bad Request - double check your query parameters
  • 401 Unauthorized - double check your API key is included in the x-api-key header
  • 403 Forbidden - ensure you are making a GET request
  • 503 Service Unavailable - Likely you've breached the daily organisation limit. Don't worry you can call tomorrow passing the most recent startAfter you've received to date.

Reach out to hello@aphex.co if you need any assistance or have other ways you would like to access your data.

How did we do?

Aphex Data API V1

Contact