Accela Cloud Document Service (ACDS) — API Reference

Contents

• Overview & Concepts
• Authentication
• Upload Files
• Download Files
• Delete Files
• Get File Metadata
• List Documents

Overview & Concepts

The Accela Cloud Document Service (ACDS) provides a REST API for uploading, downloading, deleting, and retrieving metadata for documents associated with Accela records. ACDS replaces the legacy Accela Document Service (ADS) and supports large file uploads via a chunked upload model, which improves reliability on slow networks and enables resumable uploads.

ACDS serves as the document backend for:

• Accela Citizen Access (ACA)
• Civic Platform (CIVP)
• Direct REST API integrations

Documents are stored in Azure File Share for long-term persistence, using Azure Blob Storage as a temporary staging area during chunked upload assembly.

Key Concepts: Session-Based API

All ACDS operations follow a two-step session pattern:

1. Create a session — POST to a session endpoint. This returns a sessionId and an expiresIn value.
2. Poll for status / retrieve results — GET the same session using the sessionId.

This asynchronous pattern is used for all operations (upload, download, delete, metadata, list) because file operations may involve backend processing that takes time to complete.

Step 1: POST /documents/{operation}-sessions              → returns { sessionId, expiresIn }
Step 2: GET  /documents/{operation}-sessions/{sessionId}  → returns status + result data

Base URL

https://{your-accela-environment}/documents/

Common Response Envelope

All endpoints return responses in the following envelope:

{
  "traceId": "abc-123-trace-id",
  "message": "Human-readable status",
  "result": { ... },
  "errors": []
}

Error Responses

Authentication

All session-creation endpoints require a Bearer token passed as an HTTP Authorization header. Identity context (tenant, agency, user) is also passed via HTTP headers — not in the request body.

Session-Creation Requests

Include the following headers on every session-creation POST:

Authorization: Bearer {your_access_token}
x-accela-agency: {agency_code}
x-accela-tenant-id: {tenant_id}
x-accela-tenant-name: {tenant_name}
x-accela-agency-user: {user_id}
Content-Type: application/json

Follow-up Requests (Chunks, Commit, Poll)

After a session is created, subsequent requests (chunk uploads, commits, and polls) authenticate via the session ID in the URL path. You do not need to re-send the Authorization header for these calls.

For details on obtaining an access token, see API Authentication.

Upload Files

Uploading a file is a multi-step process using chunked uploads:

1. POST /documents/upload-sessions                          → Create upload session
2. POST /documents/upload-sessions/{id}/chunks/{n}          → Upload each chunk
3. POST /documents/upload-sessions/{id}/commit              → Commit / assemble file
4. GET  /documents/upload-sessions/{id}                     → Check status & get documentId

Step 1 — Create an Upload Session

POST /documents/upload-sessions

Initializes an upload session. Returns a sessionId used for all subsequent upload operations.

Request Body

{
  "uploadMeta": {
    "fileName": "example.pdf",
    "fileSize": "10MB",
    "chunkSize": "5MB",
    "fileDigest": "sha256:abc123...",
    "storageType": "AZURE"
  },
  "document": {
    "recordId": { ... },
    "entityId": "string",
    "entityType": "string",
    "description": "string",
    "uploadedBy": "string",
    "recordType": {
      "capGroup": "string",
      "capType": "string",
      "capSubType": "string",
      "capCategory": "string"
    }
  }
}

uploadMeta Fields

document Fields

The document object is required.

Response 201 Created

{
  "traceId": "trace-abc-123",
  "message": "Upload session created",
  "result": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "expiresIn": "3600"
  },
  "errors": []
}

Step 2 — Upload a Chunk

POST /documents/upload-sessions/{uploadSessionId}/chunks/{chunk}

Uploads a single binary chunk of the file. Chunks must be numbered starting from 1 and uploaded sequentially or in parallel. Each call is a multipart/form-data request.

Path Parameters

Query Parameters

Request

Content-Type: multipart/form-data

Response 201 Created

{
  "traceId": "trace-abc-123",
  "message": "Chunk received",
  "result": {
    "chunkNumber": 1,
    "message": "Chunk 1 uploaded successfully"
  },
  "errors": []
}

Step 3 — Commit the Upload

POST /documents/upload-sessions/{uploadSessionId}/commit

Triggers assembly of all uploaded chunks into a single file, then transfers the assembled file to the backend document store. This is an asynchronous operation — the commit is queued and processed in the background.

Path Parameters

Response 200 OK

{
  "traceId": "trace-abc-123",
  "message": "Commit accepted",
  "result": {
    "message": "Processing started"
  },
  "errors": []
}

Step 4 — Get Upload Status & Document ID

GET /documents/upload-sessions/{uploadSessionId}

Poll this endpoint after committing to retrieve the processing status and, once complete, the documentId of the newly stored document.

Path Parameters

Response 200 OK

{
  "traceId": "trace-abc-123",
  "message": "Upload complete",
  "result": {
    "documentId": 98765,
    "fileName": "example.pdf",
    "state": "Complete",
    "eventMessage": "Upload completed successfully."
  },
  "errors": []
}

State Values

Download Files

1. POST /documents/download-sessions          → Create download session
2. GET  /documents/download-sessions/{id}     → Poll for status & retrieve download link

Step 1 — Create a Download Session

POST /documents/download-sessions

Initiates a download session for a given document. Returns a sessionId to poll for the generated download link.

Request Body

{
  "documentId": 98765,
  "fileKey": "optional-file-key",
  "moduleName": "optional-module",
  "storageType": "AZURE",
  "recordId": {
    "customId": "B2023-001",
    "id": "123456"
  }
}

Response 201 Created

{
  "traceId": "trace-abc-123",
  "message": "Download session created",
  "result": {
    "sessionId": "660e8400-e29b-41d4-a716-446655440111",
    "expiresIn": "3600"
  },
  "errors": []
}

Step 2 — Get Download Status & Link

GET /documents/download-sessions/{downloadSessionId}

Poll for the download link once the session is ready.

Path Parameters

Response 200 OK

{
  "traceId": "trace-abc-123",
  "message": "Download link generated",
  "result": {
    "documentId": 98765,
    "shareFileLink": "https://storage.azure.com/...",
    "shareFileLinkExpiresOn": "2026-03-18T22:00:00Z",
    "state": "Complete",
    "message": "Download link generated."
  },
  "errors": []
}

Delete Files

Important: Deletion is permanent at the storage layer. Once a delete operation completes, the document cannot be recovered through ACDS.

1. POST /documents/delete-sessions          → Create delete session
2. GET  /documents/delete-sessions/{id}     → Poll for status

Step 1 — Create a Delete Session

POST /documents/delete-sessions

Initiates a delete operation for a document.

Request Body

{
  "documentId": 98765,
  "entityId": "optional-parent-entity-id",
  "fileKey": "optional-file-key",
  "moduleName": "optional-module",
  "storageType": "AZURE",
  "recordId": {
    "customId": "B2023-001",
    "id": "123456"
  }
}

Response 201 Created

{
  "traceId": "trace-abc-123",
  "message": "Delete session created",
  "result": {
    "sessionId": "770e8400-e29b-41d4-a716-446655440222",
    "expiresIn": "3600"
  },
  "errors": []
}

Step 2 — Get Delete Status

GET /documents/delete-sessions/{deleteSessionId}

Path Parameters

Response 200 OK

{
  "traceId": "trace-abc-123",
  "message": "Document deleted",
  "result": {
    "documentId": 98765,
    "entityId": "optional-entity-id",
    "state": "Complete",
    "message": "Document deleted.",
    "eventMessage": "DocumentDeleteAfter event triggered."
  },
  "errors": []
}

Get File Metadata

1. POST /documents/metadata-sessions          → Create metadata session
2. GET  /documents/metadata-sessions/{id}     → Poll for metadata result

Step 1 — Create a Metadata Session

POST /documents/metadata-sessions

Initiates a metadata retrieval request for a document.

Request Body

{
  "documentId": 98765,
  "fileKey": "optional-file-key",
  "moduleName": "optional-module",
  "storageType": "AZURE",
  "recordId": {
    "customId": "B2023-001",
    "id": "123456"
  }
}

You can look up a document by documentId, fileKey, or both. At least one should be provided.

Response 201 Created

{
  "traceId": "trace-abc-123",
  "message": "Metadata session created",
  "result": {
    "sessionId": "880e8400-e29b-41d4-a716-446655440333",
    "expiresIn": "3600"
  },
  "errors": []
}

Step 2 — Get Metadata Result

GET /documents/metadata-sessions/{metadataSessionId}

Path Parameters

Response 200 OK

Returns document metadata once the session is in Complete state. The result payload contains file metadata attributes such as file name, size, storage location, and associated record information.

List Documents

1. POST /documents/list-sessions          → Create list session
2. GET  /documents/list-sessions/{id}     → Poll for document list result

Step 1 — Create a List Session

POST /documents/list-sessions

Initiates a request to list documents associated with a record or entity.

Request Body

{
  "entityIds": "id1,id2,id3",
  "entityType": "CAP",
  "altIds": "alt1,alt2"
}

entityIds accepts a comma-separated list of entity IDs. entityType specifies the type (e.g. CAP, PARCEL, INSPECTION). altIds is optional for alternate ID lookups.

Response 201 Created

{
  "traceId": "trace-abc-123",
  "message": "List session created",
  "result": {
    "sessionId": "990e8400-e29b-41d4-a716-446655440444",
    "expiresIn": "3600"
  },
  "errors": []
}

Step 2 — Get List Results

GET /documents/list-sessions/{listSessionId}

Path Parameters

Response 200 OK

Returns a list of document metadata objects associated with the requested entities once the session reaches Complete state.

API Quick Reference