Permits

GET

Get multiple permits

GET /{organizationNickname}/projects/{projectId}/permits

Gets a paginated list of permits.

Header Parameters

Name	Type	Description
Authorization	String	Civillo API Credentials *required

Query Parameters

Name	Type	Description
targetUserId	Uuid	Get the permits for a specific user. This returns all permits in which the provided user is involved.
excludeIds	Array <Integer>	Any permit IDs to exclude from the result.
statuses	Array <Integer>	Filter permits by statuses (see below for status codes).
name	String	Filter permits by name.
types	Array <String>	Filter permits based on their type, or template ID.
creatorId	Uuid	Filter permits based on the user who requested it.
holderId	Uuid	Filter permits based on the user holding it.
showArchived	Boolean	If true, show archived permits (only available for project admins and permit controllers).
startDateFrom	DateTime	Filter on permits that have a start time after this.
startDateUntil	DateTime	Filter on permits that have a start time before this.
expiryDateFrom	DateTime	Filter on permits that have a expiry time after this.
expiryDateUntil	DateTime	Filter on permits that have a expiry time before this.

Sample output

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalCount": 100,
  "totalPages": 2,
  "items": [
    {
      "id": 1,
      "uuid": "cca0f5e6-46b6-473d-9c7d-b9202e0ffebf",
      "name": "GPP 1",
      "template": {
          "id": 1,
          "name": "GPP",
          "description": null
      },
      "status": 1,
      "description": null,
      "startTime": "2025-07-16T14:00:00Z",
      "expiryDate": "2025-07-30T14:00:00Z",
      "renewalTime": "2025-07-23T14:00:00Z",
      "timesRenewed": 0,
      "maxRenewals": null,
      "renewalsRemaining": null,
      "requesterId": "47fb1597-4daa-4a38-a99b-74fe5cd519de",
      "holderId": null,
      "specifiedHolderId": null,
      "geometry": "{\"type\":\"FeatureCollection\",\"features\":[{\"type\":\"Feature\",\"properties\":{},\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[145.34072661657814,-38.0451256846611],[145.34140279001423,-38.04551370973493],[145.34168059770622,-38.04466335422924],[145.34102014923275,-38.04439090814364],[145.34072661657814,-38.0451256846611]]]}}]}",
      "documentUrl": "https://app.civillo.com/i/permits/cca0f5e6-46b6-473d-9c7d-b9202e0ffebf",
      "civilloUrl": "https://app.civillo.com/org/project/1/permits/1",
      "archived": false,
      "holdable": true,
      "cancellable": false,
      "allowCopy": true,
      "copiedFrom": null,
      "daysValid": 2.5,
      "validTime": 60,
      "validTimeMinutes": 3600,
      "lapsed": false
    },

    // more permits
  ]
}

Renewal period units

validTime is the renewal period in whole hours, rounded down. A permit whose renewal period was reduced when it was requested can have a period that isn’t a whole number of hours, so use validTimeMinutes for the exact period, or renewalTime for when the permit next requires renewal. Both validTime fields are left out or null when the permit never requires renewal.

Get one permit

GET /{organizationNickname}/projects/{projectId}/permits/{permitId}

Gets a more detailed view of a specific permit.

Header Parameters

Name	Type	Description
Authorization	String	Civillo API Credentials *required

Sample output

{
    "id": 1,
    "name": "GPP 1",
    "description": null,
    "declaration": null,
    "legendLayersOnly": false,
    "uuid": "8cd60c5b-59e7-45da-a42f-8330be2a2221",
    "status": 1,
    "templateName": "Ground penetration permit",
    "templateDescription": null,
    "geometry": "{\"type\":\"FeatureCollection\",\"features\":[{\"type\":\"Feature\",\"properties\":{},\"geometry\":{\"type\":\"Polygon\",\"coordinates\":[[[144.9627462043975,-37.813152398504116],[144.9633832927978,-37.81461198001696],[144.9659316464007,-37.814712639746816],[144.96631389944065,-37.81310206759216],[144.9627462043975,-37.813152398504116]]]}}]}",
    "startTime": "2025-04-27T14:00:00Z",
    "renewalTime": null,
    "expiryDate": null,
    "owner": true,
    "documentUrl": "https://app.civillo.com/i/permits/cca0f5e6-46b6-473d-9c7d-b9202e0ffebf",
    "categories": [
        {
            "signoffs": [
                "77464f9b-2175-463e-af31-4892241a3671"
            ],
            "signatures": [
                {
                    "timestamp": null,
                    "userId": "77464f9b-2175-463e-af31-4892241a3671",
                    "isRejection": false,
                    "comment": null,
                    "groupId": null,
                    "imageUrl": null
                }
            ],
            "signatureRequirements": [
                {
                    "userId": "77464f9b-2175-463e-af31-4892241a3671",
                    "groupId": null,
                    "minGroupMembersRequired": null
                }
            ],
            "minUserSignoffsRequired": null,
            "updateable": false,
            "potentialRespondents": [],
            "respondent": "77464f9b-2175-463e-af31-4892241a3671",
            "isCurrent": true,
            "signaturesRequired": false,
            "id": 1,
            "categoryId": 1,
            "name": "Category A",
            "status": 0,
            "users": null,
            "userIsSignoff": null,
            "userCanSignoff": true,
            "sequenceNumber": 1,
            "isClosing": false,
            "isProgression": false,
            "isOpen": false,
            "items": "[{\"id\":1,\"subItems\":null,\"type\":2,\"prompt\":\"Prompt A\",\"value\":\"No\",\"options\":[\"Yes\",\"No\"],\"dependencyResponse\":null,\"defaultValue\":null,\"flagged\":false,\"revisionComment\":null,\"linkedPermit\":null,\"linkedPermits\":null,\"isHeaderType\":false,\"NullAllowed\":false}]",
            "header": null,
            "footer": null,
            "activated": null,
            "description": null,
            "declaration": null
        }
    ],
    "closeOffCategories": [],
    "progressionCategories": [],
    "openCategories": [],
    "creator": {
        "role": 0,
        "user": {
            "id": "77464f9b-2175-463e-af31-4892241a3671",
            "profileUrl": null,
            "firstName": "Joe",
            "lastName": "Blogs",
            "company": null,
            "title": null,
            "username": "Joe Blogs"
        }
    },
    "layers": [],
    "history": null,
    "renewable": false,
    "daysValid": null,
    "attachments": null,
    "timesRenewed": 0,
    "maxRenewals": null,
    "closingCategoriesActive": false,
    "progressionCategoriesActive": false,
    "signatures": [
        {
            "timestamp": null,
            "userId": "77464f9b-2175-463e-af31-4892241a3671",
            "isRejection": false,
            "comment": null,
            "groupId": null,
            "imageUrl": null
        }
    ],
    "renewalsRemaining": null,
    "amendable": false,
    "canAddRemoveOpenCategories": false,
    "signoffable": false,
    "cancellable": true,
    "closeOffAble": false,
    "progressable": false,
    "rejectable": false,
    "revokable": false,
    "viewable": false,
    "updateable": true,
    "holdable": false,
    "userCanHold": false,
    "userCannotYetHold": false,
    "userCanRelinquish": false,
    "holderId": null,
    "specifiedHolderId": null,
    "activationDeclaration": null,
    "relinquishmentDeclaration": null,
    "signaturesRequired": false,
    "allowCopy": false,
    "geometryUpdateable": true,
    "copiedFrom": null,
    "dbydRequired": false,
    "lapsed": false
}

Permit statuses

Each permit status in Civillo maps to a specific number.

Value	Name	Description
0	Created	The permit has been created.
1	CategoryPending	One or more required permit categories are pending completion or review.
2	SignoffPending	The permit is awaiting one or more required overall signoffs.
3	Approved	The permit has been fully approved but not yet active.
4	Rejected	The permit has been reviewed and changes requested.
5	RenewalRequired	The permit has reached a state where renewal is required to remain valid.
6	Updated	The permit has been modified.
7	Revoked	The permit has been forcibly withdrawn and is no longer valid.
8	Active	The permit is currently active and in effect.
9	Completed	The permit has been fully completed and closed out successfully.
10	Renewed	The permit has been successfully renewed.
11	Cancelled	The permit has been cancelled prior to becoming active.
12	Amended	The permit has been modified by an admin, bypassing the normal lifecycle rules.
13	CloseOffPending	The permit is awaiting final close-off checks or approvals.
14	Progressed	The permit has progressed to the next workflow stage.
15	Expired	The permit has expired and is no longer valid.

Permit category statuses

Value	Name	Description
0	PendingSignoff	The category is awaiting one or more required signoffs before it can be approved.
1	Approved	The category has been fully reviewed and approved.
2	Rejected	The category has been reviewed and rejected.
3	PendingResponse	The category requires a response or additional information before it can proceed.