Core resources

Engagements and notes

An engagement is one entry in a project's thread. Some are visible to both sides, like a response with documents attached. Others are internal notes your team keeps to itself.

The two kinds

Kind	`is_internal`	Created by	Seen by
Response	`false`	`PUT /projects/{id}/respond`	Both sides.
Note	`true`	`POST /projects/{id}/notes`	Your team only.

Notes exist to record what happened off the platform: the phone call, the site visit, the hui at the marae. They keep the record complete without pretending the conversation was digital.

Read the thread

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

Paged, newest first, with documents and author on each entry. Defaults to 10 per page, maximum 100.

Response

{
  "success": true,
  "message": "Engagements retrieved",
  "status_code": 200,
  "response_object": {
    "data": [
      {
        "id": "d21c...",
        "project_id": "8f0c2c1e-...",
        "content": "Ngā mihi for sending this through early. We would like a site walkover before the riverbed works start.",
        "is_internal": false,
        "meeting_type": null,
        "created_on": "2026-09-20T02:55:40.000Z",
        "updated_on": "2026-09-20T02:55:40.000Z",
        "created_by": { "first_name": "Mere", "last_name": "Tuhoro", "profile_picture_url": null },
        "documents": []
      },
      {
        "id": "a77b...",
        "content": "Rang Mere, agreed to a walkover the week of the 12th.",
        "is_internal": true,
        "meeting_type": "PHONE_CALL",
        "created_on": "2026-09-20T03:40:02.000Z",
        "created_by": { "first_name": "Aroha", "last_name": "Rangi", "profile_picture_url": null },
        "documents": []
      }
    ],
    "total": 2,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

Respond to a project

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

Adds a visible message to the thread and notifies the other side. Check can_respond first, since the endpoint itself only checks that you are party to the project.

For an organisation, responding can cost a token. See tokens and billing. An iwi never spends tokens, on this endpoint or any other.

Field	Type		Notes
`message`	string	required	Plain text. Line breaks are preserved.
`files`	array	required	Document ids from the upload flow. Send `[]` for none.

Request

curl -X PUT "$IWICONNECT_URL/projects/8f0c2c1e-.../respond" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Happy to do a walkover the week of the 12th. Updated methodology attached.",
    "files": [{ "id": "b3f2a1c4-55de-4f7a-9c21-0a5d6e8f4b12" }]
  }'

Log a note

post /projects/{id}/notes projects:write

Records an interaction that happened outside the platform. Internal to your team, and it does not notify anyone.

Field	Type		Notes
`content`	string	required	What happened.
`meeting_type`	string	required	`PHONE_CALL`, `VIDEO_CALL`, `IN_PERSON`, `EMAIL` or `OTHER`.

Request

curl -X POST "$IWICONNECT_URL/projects/8f0c2c1e-.../notes" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Site walkover with Mere and two kaitiaki. Agreed on a 5m setback from the bank.",
    "meeting_type": "IN_PERSON"
  }'

Edit and delete notes

put /projects/{id}/notes/{engagementId} projects:write

Replaces content and meeting_type. Only the author can edit a note, and the edit is recorded in the project log.

delete /projects/{id}/notes/{engagementId} projects:write

Removes the note. The deletion itself stays in the log, so the audit trail does not develop a hole.

Responses cannot be edited or deleted. Once a message has gone to the other side it stays on the record. If you got something wrong, send another response correcting it. That is how it works in the portal too.

Watching for replies

There are no webhooks yet. Poll GET /projects with active_status=active and compare updated_on, then fetch engagements only for projects that moved. Every five to fifteen minutes is plenty, and it keeps you well inside the rate limit even with a few hundred open projects.