Core resources

Projects

A project is one piece of work you want iwi to know about: a consent application, a maintenance programme, an accidental discovery. It carries the description, the location, the dates, the documents and every exchange that follows.

Lifecycle

Projects move through a small set of states. Most of the rules that trip people up are about which state allows which action.

Status	What it means
`DRAFT`	Created but not sent. Free, fully editable, invisible to iwi.
`NEW`	Sent and sitting in the iwi inbox, not yet picked up.
`AWAITING_RESPONSE`	Seen and assigned on the iwi side, no reply yet.
`IN_PROGRESS`	Kōrero is underway. Both sides can add engagements.
`UPDATED`	New activity since you last looked.
`COMPLETE`	Engagement finished and marked complete.
`CLOSED`	Closed off, usually because the work or the consent ended.

Sending a draft is one way. Closing is not final: a closed project can be reopened, and reopening costs nothing because the submission already happened.

Sides, and who can do what

Every project has two sides. The sender is whoever created it, the recipient is whoever received it. Most projects are created by an organisation and received by iwi, but an iwi can also create a project and send it to a connected organisation. is_iwi_created on the project tells you which way round you are.

The side you are on decides which actions are available, and so does the project's status. Fetching a single project returns a set of can_* booleans that have already worked this out for you.

Organisation created the project

Action	Organisation (sender)	Iwi (recipient)
Edit	Yes	No
Send	While `DRAFT`	No
Respond	Once sent	Yes
Assign	Sender side only	Recipient side only
Add notes	Once sent, until closed	Once sent, until closed
Complete	No	Yes
Close	Until closed	No
Reopen	While `CLOSED`	While `CLOSED`

Iwi created the project

Action	Iwi (sender)	Organisation (recipient)
Edit	Yes	No
Send	While `DRAFT`	No
Respond	Yes	Once sent
Assign	Sender side only	Recipient side only
Add notes	Until closed	Until closed
Complete	Yes	No
Close	Yes	Until closed
Reopen	While `CLOSED`	While `CLOSED`

Completing is the iwi's call, closing is the organisation's. An iwi marks a project COMPLETE when the engagement has run its course. An organisation closes it. The one exception is a project the iwi created itself, which they can also close.

List projects

get /projects projects:read

Every project your team can see, paged and filterable. See pagination and filtering for the full parameter list.

Request

curl -G "$IWICONNECT_URL/projects" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  --data-urlencode 'active_status=active' \
  --data-urlencode 'limit=50'

Fetch one project

get /projects/{id} projects:read

The full record, including the organisation, the recipient team, assignment, and the can_* flags describing what this key may do next.

Response

{
  "success": true,
  "message": "Project retrieved",
  "status_code": 200,
  "response_object": {
    "id": "8f0c2c1e-2f4a-4a63-9d0e-6c1a2f0f1a11",
    "name": "Waikanae Bridge strengthening",
    "reference": "RC-2026-0418",
    "description": "Seismic strengthening of the SH1 bridge abutments.",
    "type": "INFRASTRUCTURE_DEVELOPMENT",
    "phase": "LODGED",
    "status": "IN_PROGRESS",
    "priority": "HIGH",
    "address": "State Highway 1, Waikanae 5036",
    "latitude": -40.8752,
    "longitude": 175.0662,
    "start_date": "2026-11-03T00:00:00.000Z",
    "end_date": "2027-04-30T00:00:00.000Z",
    "respond_by_date": "2026-10-14T00:00:00.000Z",
    "created_on": "2026-09-18T21:04:11.000Z",
    "updated_on": "2026-09-20T02:55:40.000Z",
    "closed_on": null,
    "iwi_name": "Te Āti Awa ki Whakarongotai",
    "recipient_team": { "id": "c41d...", "name": "Te Āti Awa ki Whakarongotai" },
    "assigned_to": { "first_name": "Mere", "last_name": "Tuhoro", "profile_picture_url": null },
    "can_edit": false,
    "can_respond": true,
    "can_assign": true,
    "can_send": false,
    "can_close": true,
    "can_reopen": false,
    "can_add_notes": true
  }
}

Create a project

post /projects projects:write

Creates a draft when draft is true, or creates and immediately submits when it is false. Submitting consumes a token.

Field	Type		Notes
`name`	string	required	What iwi see first, and what `search` matches on.
`description`	string	required	Plain language. This is the part people actually read.
`type`	string	required	One of the project types. Drives priority and which phases are valid.
`start_date`	string	required	`YYYY-MM-DD`.
`end_date`	string	required	`YYYY-MM-DD`.
`respond_by_date`	string	required	When you need a response by. Drives the reminders sent before the date passes.
`files`	array	required	Document ids from the upload flow. Send `[]` if there are none.
`draft`	boolean	required	`true` to hold it, `false` to send on creation.
`phase`	string	optional	Must be valid for the type. Works types take works phases, consents take consent phases.
`reference`	string	optional	Your own reference number. Searchable, and the easiest way to reconcile later.
`address`	string	optional	Street address of the site.
`latitude`	number	optional	Decimal degrees. Needed for rohe routing.
`longitude`	number	optional	Decimal degrees.
`iwi`	array	optional	Iwi slugs. Ignored when the location resolves to a single iwi.
`organisation_id`	uuid	optional	An existing organisation on your account.
`organisation`	object	optional	Create the organisation inline with `name`, `address`, `latitude`, `longitude`.
`contact`	object	optional	Site contact: `name`, `role`, `phone`, optional `email`.
`quantity`	number	optional	Buy tokens as part of the submission. One of 1, 5, 10, 20, 50.
`recipient_team_id`	uuid	optional	Send to a specific team rather than routing by location.

Location beats the iwi array. Routing starts from the coordinates. If the rohe over that point belong to one iwi, that is who receives it, whatever you passed in iwi. Call POST /iwi/count first if you need to know which case you are in.

Update a project

put /projects/{id} projects:write

Editable fields are name, description, reference, type, phase, start_date, end_date and respond_by_date. The three dates must all be present, even when only one changes.

Location, iwi and organisation are fixed once the project is sent. Changing where a project is would change who should have received it, so that needs a new project.

Request

curl -X PUT "$IWICONNECT_URL/projects/8f0c2c1e-.../" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "phase": "HEARING",
    "start_date": "2026-11-03",
    "end_date": "2027-06-30",
    "respond_by_date": "2026-10-14"
  }'

Send a project

put /projects/{id}/send projects:send

Submits a draft. Consumes one token, notifies the receiving iwi, and locks the fields listed above. Returns 402 when the team has no tokens, and 400 when the iwi you asked for do not match the location. Check can_send rather than sending twice: the endpoint does not re-check the status for you.

Field	Type		Notes
`message`	string	required	The covering note. It becomes the first engagement on the thread.
`iwi`	array	optional	Override the iwi selected at creation, where selection is allowed.

Assignment

put /projects/{id}/assign projects:write

Assign the project to a person or an assignment group. Each project has two assignments, one per side, so both the sender and the recipient can track who is holding it.

Field	Type		Notes
`user_id`	uuid or null	required	`null` unassigns, or assigns to a group instead.
`group_id`	uuid	optional	Assign to a group rather than a person.
`side`	string	optional	`recipient` (default) or `sender`. You can only set your own side.

Closing, completing and reopening

put /projects/{id}/complete iwi accounts only

Marks the engagement COMPLETE, with an optional message. This one is checked on the server: a key belonging to an organisation gets a 403 whichever side of the project it is on, and whoever created the project. If you are integrating from an organisation, close the project instead.

Field	Type		Notes
`message`	string	optional	Added to the thread as a closing message. Supports the `{{iwi_name}}` placeholder.

put /projects/{id}/close projects:write

Closes the project off. An organisation can close any project it is party to. An iwi can only close a project it created itself, so check can_close before offering it.

Closing queues the engagement report for the project, which turns up under GET /team/{id}/reports a little later.

Field	Type		Notes
`all`	boolean	required	`true` closes every copy of the project that went out together, `false` closes only this one. It has no effect on a project that went to a single iwi.
`message`	string	optional	Why it is being closed. Supports the `{{iwi_name}}` placeholder.

Who sees the closing message. A message sent by an iwi lands on the thread where the organisation can read it. A message sent by an organisation is recorded as an internal note, visible only to their own team. Same field, different audience, depending on which side you are on.

Request

curl -X PUT "$IWICONNECT_URL/projects/8f0c2c1e-.../close"   -H "Authorization: Bearer $IWICONNECT_KEY"   -H 'Content-Type: application/json'   -d '{
    "all": true,
    "message": "Ngā mihi to {{iwi_name}} for the input. Consent was granted on 14 August and works are complete."
  }'

put /projects/{id}/reopen projects:write

Puts a closed project back to NEW and clears its closed date. Either side can reopen, and can_reopen is only true while the project is CLOSED. Nothing is charged, because the submission already happened.

Request a report

post /projects/{id}/report projects:send

Generates a PDF engagement report covering the project and its exchanges: useful evidence for a consent application or a council file. Set all to true to cover every iwi on the project. The report appears under GET /team/{id}/reports once it is built.

Related lists

get /projects/{id}/engagements projects:read

The conversation. See engagements and notes.

get /projects/{id}/documents projects:read

Every document attached to the project or to an engagement on it, paged.

get /projects/{id}/logs projects:read

The audit trail: who changed what, when, and from which value to which. This is what you pull when someone asks whether the respond-by date was moved.

Response · logs

{
  "data": [
    {
      "id": "6a1e...",
      "action": "UPDATED",
      "resource": "PROJECT",
      "property": "respond_by_date",
      "from": "2026-10-07",
      "to": "2026-10-14",
      "created_on": "2026-09-19T01:22:07.000Z",
      "created_by": { "first_name": "Aroha", "last_name": "Rangi", "profile_picture_url": null }
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 10,
  "total_pages": 2
}