List cost roll-ups

curl --request GET \
  --url https://api.ctrl-hub.com/v3/cost-rollups \
  --header 'X-Session-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/cost-rollups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ctrl-hub.com/v3/cost-rollups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ctrl-hub.com/v3/cost-rollups"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/cost-rollups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "cost-rollups",
      "attributes": {
        "cost_centre_id": "7f3a2c18-64bd-4f0e-9a52-c8d1b73e0f45",
        "cost_centre_type": "scheme-contracts",
        "parent_cost_centre_id": "c000c344-8847-47da-a091-32e75902d3b1",
        "parent_cost_centre_type": "scheme-contracts",
        "name": "<string>",
        "code": "<string>",
        "has_cost_sheet": true,
        "direct": {
          "cost": {
            "amount": 9250,
            "currency": "GBP"
          },
          "charge": {
            "amount": 9250,
            "currency": "GBP"
          },
          "profit": {
            "amount": 9250,
            "currency": "GBP"
          },
          "categories": {
            "material": {
              "amount": 9250,
              "currency": "GBP"
            },
            "labour": {
              "amount": 9250,
              "currency": "GBP"
            },
            "misc": {
              "amount": 9250,
              "currency": "GBP"
            },
            "contractor": {
              "amount": 9250,
              "currency": "GBP"
            }
          }
        },
        "rolled": {
          "cost": {
            "amount": 9250,
            "currency": "GBP"
          },
          "charge": {
            "amount": 9250,
            "currency": "GBP"
          },
          "profit": {
            "amount": 9250,
            "currency": "GBP"
          },
          "categories": {
            "material": {
              "amount": 9250,
              "currency": "GBP"
            },
            "labour": {
              "amount": 9250,
              "currency": "GBP"
            },
            "misc": {
              "amount": 9250,
              "currency": "GBP"
            },
            "contractor": {
              "amount": 9250,
              "currency": "GBP"
            }
          }
        },
        "by_status": {
          "quoted": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          },
          "approved": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          },
          "completed": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          }
        },
        "estimated": {
          "direct": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          },
          "rolled": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "counts": {
        "pages": 1,
        "resources": 1
      },
      "current_page": 1,
      "offsets": {
        "next": null,
        "previous": null
      },
      "requested": {
        "limit": 10,
        "offset": 0
      }
    },
    "features": {
      "include": {
        "options": [
          "related.resource"
        ]
      }
    }
  },
  "jsonapi": {
    "version": "1.0"
  }
}

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "errors": [
    {
      "id": "1b3f2c30-2d56-4d3a-9c44-9be9c2cbf2f0",
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not hold the grant required for this action.",
      "code": "AUTH.002"
    }
  ]
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Costs

List cost roll-ups

Read what a node of the job hierarchy costs, and what everything beneath it costs.

A roll-up is derived and read-only — there is no create, update or delete. It is keyed on the cost centre rather than on a cost sheet, so a contract nobody has costed directly still returns a real total from the work orders beneath it, without an empty sheet having to exist for it.

Filter by organisation, cost_centre and cost_centre_type together for the node you want rolled up. All three are required as a set; supplying some but not all of them is rejected rather than answered.

By default this returns exactly one element: the roll-up for the node named by the filter. Add eq(depth,all) to the filter to get one element per node in the subtree beneath and including that node instead, so a client can see which scheme, work order or operation is holding the money rather than only how much is below in total. Any other depth value is rejected rather than answered.

Every element, in either mode, also carries parent_cost_centre_id and parent_cost_centre_type (both null on the subtree’s root), name, code and has_cost_sheet — enough on its own to rebuild the shape of the subtree and label each node, since a depth=all response is otherwise just a bag of totals with no relationships between them.

Each roll-up returns the node’s own direct total, the rolled total that includes every descendant, and by_status — rolled split by the status of the sheet each line sits on, so a client can sum only the statuses it cares about without asking again. Soft-deleted nodes are left out of the walk.

Totals are sums of the snapshots stored on the cost lines themselves, so revising a rate or a margin in the cost register never moves a roll-up.

This read is gated on permission to view cost lines rather than cost sheets: a roll-up returns nothing but money.

GET

cost-rollups

List cost roll-ups

curl --request GET \
  --url https://api.ctrl-hub.com/v3/cost-rollups \
  --header 'X-Session-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Session-Token': '<api-key>'}};

fetch('https://api.ctrl-hub.com/v3/cost-rollups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ctrl-hub.com/v3/cost-rollups",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Session-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ctrl-hub.com/v3/cost-rollups"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Session-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.ctrl-hub.com/v3/cost-rollups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Session-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "cost-rollups",
      "attributes": {
        "cost_centre_id": "7f3a2c18-64bd-4f0e-9a52-c8d1b73e0f45",
        "cost_centre_type": "scheme-contracts",
        "parent_cost_centre_id": "c000c344-8847-47da-a091-32e75902d3b1",
        "parent_cost_centre_type": "scheme-contracts",
        "name": "<string>",
        "code": "<string>",
        "has_cost_sheet": true,
        "direct": {
          "cost": {
            "amount": 9250,
            "currency": "GBP"
          },
          "charge": {
            "amount": 9250,
            "currency": "GBP"
          },
          "profit": {
            "amount": 9250,
            "currency": "GBP"
          },
          "categories": {
            "material": {
              "amount": 9250,
              "currency": "GBP"
            },
            "labour": {
              "amount": 9250,
              "currency": "GBP"
            },
            "misc": {
              "amount": 9250,
              "currency": "GBP"
            },
            "contractor": {
              "amount": 9250,
              "currency": "GBP"
            }
          }
        },
        "rolled": {
          "cost": {
            "amount": 9250,
            "currency": "GBP"
          },
          "charge": {
            "amount": 9250,
            "currency": "GBP"
          },
          "profit": {
            "amount": 9250,
            "currency": "GBP"
          },
          "categories": {
            "material": {
              "amount": 9250,
              "currency": "GBP"
            },
            "labour": {
              "amount": 9250,
              "currency": "GBP"
            },
            "misc": {
              "amount": 9250,
              "currency": "GBP"
            },
            "contractor": {
              "amount": 9250,
              "currency": "GBP"
            }
          }
        },
        "by_status": {
          "quoted": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          },
          "approved": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          },
          "completed": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          }
        },
        "estimated": {
          "direct": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          },
          "rolled": {
            "cost": {
              "amount": 9250,
              "currency": "GBP"
            },
            "charge": {
              "amount": 9250,
              "currency": "GBP"
            },
            "profit": {
              "amount": 9250,
              "currency": "GBP"
            },
            "categories": {
              "material": {
                "amount": 9250,
                "currency": "GBP"
              },
              "labour": {
                "amount": 9250,
                "currency": "GBP"
              },
              "misc": {
                "amount": 9250,
                "currency": "GBP"
              },
              "contractor": {
                "amount": 9250,
                "currency": "GBP"
              }
            }
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "counts": {
        "pages": 1,
        "resources": 1
      },
      "current_page": 1,
      "offsets": {
        "next": null,
        "previous": null
      },
      "requested": {
        "limit": 10,
        "offset": 0
      }
    },
    "features": {
      "include": {
        "options": [
          "related.resource"
        ]
      }
    }
  },
  "jsonapi": {
    "version": "1.0"
  }
}

{
  "id": "98ca4a78-b66f-4234-9719-aaf832ee6669",
  "status": "400",
  "title": "A validation error was encountered",
  "source": {
    "parameter": "include"
  },
  "meta": {
    "resource": "wrong_value"
  }
}

{
  "id": "05fc9c8d-73b9-4697-9337-57f7a567a48f",
  "status": "401",
  "title": "You are not authorised to access this resource",
  "detail": "In order to access this resource, you need the 'admin' role.",
  "code": "AUTH.001"
}

{
  "errors": [
    {
      "id": "1b3f2c30-2d56-4d3a-9c44-9be9c2cbf2f0",
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not hold the grant required for this action.",
      "code": "AUTH.002"
    }
  ]
}

{
  "id": "fe9d9a69-f0a7-4fdc-bb2c-176027f316c5",
  "status": "500",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server."
}

Authorizations

X-Session-Token

string

header

required

Session token for authentication.

Query Parameters

filter

string

default:""

Filters the response data based on the value provided.

Available filters:

organisation: Filter by the ID of the organisation the node belongs to
cost_centre: Filter by the ID of the node to roll up
cost_centre_type: Filter by the type of the node to roll up (scheme-contracts, schemes, work-orders, operations)
depth: Optional. How much of the subtree to return: self (the default, and the same as omitting the term) returns one element, the roll-up for the filtered node; all returns one element per node in the subtree beneath and including it, so a client can see which scheme, work order or operation is holding the money rather than only the total beneath it. Matching is exact lowercase; any other value is rejected with CH.004.211.

A roll-up is derived from a cost centre, so organisation, cost_centre and cost_centre_type must be given together — they identify the node whose subtree is summed. Supplying some but not all of them is rejected with CH.004.211 rather than answered, because a partly-filtered roll-up would return a total for the wrong scope. Supplying none of them returns an empty collection, as any unfiltered collection read does.

Wrap them in and(), as in and(eq(organisation,c000c344-8847-47da-a091-32e75902d3b1),eq(cost_centre,7f3a2c18-64bd-4f0e-9a52-c8d1b73e0f45),eq(cost_centre_type,work-orders),eq(depth,all)); filters after a bare top-level comma are dropped.

For more information on using named filters, see the docs

limit

integer<int64>

default:100

Limit the number of resources returned by the API

Required range: x >= 1

offset

integer<int64>

default:0

Offset the resources returned by the API

Required range: x >= 0

page

object

JSON:API pagination, as page[limit] and page[offset]. The same as the top-level limit and offset parameters; when both forms are sent, page[...] wins.

Show child attributes

Response

List of cost roll-ups.

JSON API response object

data

A list of cost roll-ups · object[]

required

Show child attributes