Start here

Quickstart

Create a key, find the iwi for a site, create a project, send it. That loop is most of what an integration does, and you can get through it in a few minutes with curl.

Use a sandbox key while you build. Sandbox projects never reach an iwi inbox and never consume tokens. When you are ready, swap the key and change nothing else.

1. Create a key

In the portal, open your profile menu at the bottom of the sidebar, then API keys, then Create key. Give it the scopes below and copy the secret when it appears. It is shown once.

iwi:read projects:read projects:write projects:send files:write

Shell

export IWICONNECT_KEY='iwk_test_7Qx4...'
export IWICONNECT_URL='https://api.iwiconnect.com'

2. Check the key works

GET /user returns the identity behind the key, including the team it belongs to and the current token balance. It costs nothing and needs no scopes, so it is a good health check to run on startup.

Request

curl "$IWICONNECT_URL/user" \
  -H "Authorization: Bearer $IWICONNECT_KEY"

Response

{
  "success": true,
  "message": "User retrieved",
  "status_code": 200,
  "response_object": {
    "id": "0b6a51d2-7a2e-4c8e-9f0a-2c2b6b9a1d44",
    "teams": [
      {
        "id": "3f1b0c77-9a5d-4d0b-8c3e-1f2a4b6c8d90",
        "name": "Kāpiti Coast District Council",
        "current_credit_balance": 12,
        "role": "OWNER"
      }
    ]
  }
}

Hold onto that team id. Several endpoints take it in the path.

3. Find out who holds mana whenua

Before you create anything, check which iwi cover the site. POST /iwi/count takes a latitude and longitude and returns the iwi whose rohe include that point.

Request

curl -X POST "$IWICONNECT_URL/iwi/count" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "lat": -40.8752, "lon": 175.0662 }'

Response

{
  "success": true,
  "message": "Iwi retrieved",
  "status_code": 200,
  "response_object": {
    "iwi": [
      { "slug": "te-ati-awa-ki-whakarongotai", "name": "Te Āti Awa ki Whakarongotai" },
      { "slug": "ngati-toa-rangatira", "name": "Ngāti Toa Rangatira" }
    ],
    "can_select_iwi": true
  }
}

When can_select_iwi is false, the rohe are settled enough that IwiConnect routes the project for you and any iwi array you send is ignored. When it is true, you choose from the list.

4. Create the project

Create it as a draft first. Drafts are free, editable, and invisible to iwi until you send them.

Request

curl -X POST "$IWICONNECT_URL/projects" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Waikanae Bridge strengthening",
    "reference": "RC-2026-0418",
    "type": "INFRASTRUCTURE_DEVELOPMENT",
    "phase": "PRE_LODGEMENT",
    "description": "Seismic strengthening of the SH1 bridge abutments, including temporary works in the riverbed.",
    "address": "State Highway 1, Waikanae 5036",
    "latitude": -40.8752,
    "longitude": 175.0662,
    "start_date": "2026-11-03",
    "end_date": "2027-04-30",
    "respond_by_date": "2026-10-14",
    "files": [],
    "draft": true,
    "iwi": ["te-ati-awa-ki-whakarongotai"]
  }'

The response carries the new project, including its id and a set of can_* flags that tell you which actions the current key may take next.

5. Send it

Sending moves the project out of draft, notifies the iwi you selected, and consumes one token.

Request

curl -X PUT "$IWICONNECT_URL/projects/8f0c2c1e-2f4a-4a63-9d0e-6c1a2f0f1a11/send" \
  -H "Authorization: Bearer $IWICONNECT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "message": "Kia ora koutou. Sharing this ahead of lodgement so we can talk about the riverbed works early." }'

This one is not reversible. A sent project has landed in someone's inbox. You can close it afterwards, but you cannot unsend it, and the token is spent. Test the whole path with a sandbox key before you point production at it.

6. Follow the thread

Poll GET /projects/{id}/engagements for replies, or GET /projects/{id} if you only need the status. Status moves from NEW to AWAITING_RESPONSE to IN_PROGRESS as the iwi picks it up and responds.

Request

curl "$IWICONNECT_URL/projects/8f0c2c1e-2f4a-4a63-9d0e-6c1a2f0f1a11/engagements?page=1&limit=10" \
  -H "Authorization: Bearer $IWICONNECT_KEY"

A sensible polling interval is five to fifteen minutes. Anything faster will not surface replies sooner and will eat your rate limit.

Where to go next

Attach documents with the upload flow before you create the project. Route work to the right people with assignment groups. And read errors before you write your retry logic, because the difference between a 402 and a 403 matters here.