Developers: The Constructicore API

Access. API keys are included on paid plans: an account owner creates them in Settings, Integrations. Building an integration and want to try it first? Email info@constructicore.com for a sandbox company with demo data and its own keys.

What you can do

Create projects and subcontracts from your own system, with the contract sum analysis.
Create, update and submit payment applications, and record certifications.
Read applications, notices and payments into job costing, ERP or reporting (for example COINS, Eque2, NetSuite or an in-house system).
Hear about events straight away through webhooks, instead of polling.

Xero, QuickBooks and Sage are covered by built-in connections, and any other accounts package by the accounts export, without using the API.

Getting started

In Constructicore, go to Settings, Integrations and create an API client. Choose only the scopes it needs. The client secret is shown once; store it in your system's secrets store.
Exchange the client ID and secret for an access token (OAuth 2.0 client credentials). Tokens last an hour.
Call the API with the token. The base address is https://api.constructicore.com.

curl -X POST https://api.constructicore.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

curl https://api.constructicore.com/v1/projects \
  -H "Authorization: Bearer ACCESS_TOKEN"

Scopes

Scope	Allows
`projects:read`	Read projects
`projects:write`	Create and update projects
`contracts:read`	Read subcontracts and contract sum analyses
`contracts:write`	Create and update subcontracts and contract sum analyses
`applications:read`	Read applications
`applications:write`	Create, update and submit applications
`notices:read`	Read notices
`notices:write`	Record notices
`cash:read`	Read payments
`cash:write`	Record payments
`webhooks:manage`	Register webhooks

A client acts on behalf of the company that created it, and can be limited to applications up to a set value.

Endpoints (version 1)

Method	Path	What it does
`GET`	`/v1/projects`	List projects (search with q, or look one up by external_ref)
`POST`	`/v1/projects`	Create a project
`GET`	`/v1/projects/{id}`	A project, with its statistics
`PATCH`	`/v1/projects/{id}`	Update a project
`GET`	`/v1/subcontracts`	List subcontracts
`POST`	`/v1/subcontracts`	Create a subcontract on a project
`GET`	`/v1/subcontracts/{id}`	A subcontract, with retention, VAT and CIS settings
`PATCH`	`/v1/subcontracts/{id}`	Update a subcontract
`GET`	`/v1/subcontracts/{id}/csa`	Its contract sum analysis
`PUT`	`/v1/subcontracts/{id}/csa`	Replace the contract sum analysis
`GET`	`/v1/subcontracts/{id}/applications`	Its applications
`POST`	`/v1/subcontracts/{id}/applications`	Start a draft application
`GET`	`/v1/applications/{id}`	An application, with lines and figures
`PATCH`	`/v1/applications/{id}`	Update a draft application
`DELETE`	`/v1/applications/{id}`	Delete a draft application
`POST`	`/v1/applications/{id}/submit`	Submit an application
`POST`	`/v1/applications/{id}/certification`	Record the certified amount
`GET`	`/v1/webhooks`	List webhooks
`POST`	`/v1/webhooks`	Register a webhook
`DELETE`	`/v1/webhooks/{id}`	Remove a webhook

Main contractor endpoints (packages, assessments, notices and payments due) are planned; tell us what you need.

Conventions

Money is in whole pence, as integers (contract_sum_pence: 4200000 is £42,000.00). Percentages are in basis points (500 is 5%). Currency is GBP.
Identifiers are UUIDs. Your own references can be stored in external_ref and used to look records up.
Lists return data and next_cursor. Pass ?limit= (up to 200) and ?cursor= for the next page.
Safe retries: every POST needs an Idempotency-Key header (for example a UUID). Repeating a request with the same key returns the original result instead of doing it twice.
Errors use HTTP status codes and application/problem+json bodies with a title, a detail and, for validation, an errors object by field.
Dates are ISO 8601, in UTC for timestamps.

Webhooks

Register an HTTPS address for the events you want. Each delivery is a JSON POST with the event type and the record, signed so you can check it came from us:

Headers X-CC-Timestamp and X-CC-Signature. The signature is HMAC-SHA256 of timestamp.body with your webhook secret. Reject anything older than 5 minutes.
Failed deliveries are retried with increasing gaps for up to 24 hours; an address that keeps failing is switched off and shown in Settings.

Events: project.created, subcontract.created, subcontract.updated, application.created, application.submitted, application.revised, application.certified, notice.recorded, payment.recorded.

Support and changes

Version 1 changes only by adding fields or endpoints; anything that would break an integration comes as a new version, with notice. Questions, or need something the API does not do yet? Email info@constructicore.com. Our security page explains how data is protected, and the status page includes the API.

The Constructicore API.