# 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": "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,
"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. |
← DELETE Permits Events →