# 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
},
// more permits
]
}
# 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": "Bloggs",
"company": null,
"title": null,
"username": "Joe Bloggs"
}
},
"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
}
# 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. |
← DELETE Permits Events →