TABLE OF CONTENTS
- Overview of Cloudpermit API
- Key API Endpoints:
- Typical Use Cases
- Key Concepts
Overview of Cloudpermit API
The Cloudpermit API enables developers to access and modify data within the platform, allowing for customized integrations and extended functionalities. The API currently supports functionalities for accessing and modifying:
- Workspaces
- Attachments
- Inspections
- Bills and payments
Key API Endpoints:
Workspaces API:
- Query new and changed workspaces.
- Query by property ID or workspace ID.
- Access data within a workspace, including property data and parties.
Attachments API:
- Download attachments in a workspace with metadata.
- Upload new versions of attachments.
- Update attachment metadata.
Inspections API:
- Retrieve inspectors' work lists.
- Access all inspection data.
- Create ad-hoc inspections.
- Create and update inspection results.
- Upload data collected during inspection visits.
- Payments API:
- Query bills by workspace id/address/party name/property id/bill number/bill status / payer name / organization
- Query new and changed bills by date
- Read bill information by bill id
- Update bill status (mark as paid)
- Update visible invoice #
Typical Use Cases
The Cloudpermit API can be utilized for a variety of integration scenarios, such as:
Public Municipal Maps:
- Display permit and application information on public-facing municipal maps.
Local Government Systems:
- Update information in a local government's property management or enterprise systems.
Inter-Governmental Data Sharing:
- Provide permit decisions and data to municipal, county, regional, state, or provincial systems.
Content Management Systems:
- Integrate with external content management or digital archiving systems for document storage.
Third-Party Review Tools:
- Provide review data and documents to external tools and update results back into Cloudpermit.
Inspection Data Integration:
- Update inspection information from third-party inspection tools.
Note: Identify your specific needs and create your own custom integration using the Cloudpermit API.
Key Concepts
Multi-Tenancy
Cloudpermit operates on a multi-tenant architecture, providing services from a single URL and cloud environment:
- United States:
us.cloudpermit.com - Canada:
ca.cloudpermit.com
There is only one API service used to access data and functionalities for any customer organization. This centralized approach enhances efficiency in managing and using the Cloudpermit API.
Security Mechanism:
- Cloudpermit's security controls ensure that API access is granted only to authorized users.
- Access is limited to permitted users and data, enforcing actions based on user permissions.
- Each local government organization is modeled as a municipality group.
- Users' access is confined to the groups they belong to, maintaining data isolation and security.
API Keys and Authentication
Authorization to Cloudpermit APIs uses OAuth 2.0 with the Client Credentials grant type. This means:
Client Authentication:
- The client application authenticates using a Client ID and Client Secret.
- An Access Token is received in return, which is used for subsequent API calls.
Generating API Keys:
- API keys (Client ID and Secret) must be generated by an existing Cloudpermit user via their My Profile page.
- Alternatively, create a service account for the municipality group and generate the API key.
- The API client application will act on behalf of this user, inheriting all their permissions within the limits of public API endpoints.
Workspaces
Definition:
- A Workspace is a central entity in Cloudpermit that contains all information related to a case, such as building permits, planning applications, license applications, code enforcement cases, etc.
Contents of a Workspace:
- Parties involved (applicant, owner, builder, contractor, agent, etc.).
- Form data and application details.
- Attachments and supporting documents.
- Reviews, permits, decisions, and approvals.
- Inspections, orders, bills, and payments.
Workflow Management:
- The workspace manages the workflow and allowed actions using phases (e.g., pre-consultation, application, execution, archiving) and detailed statuses within each phase.
Accessing Workspaces:
- API client applications can query and access workspaces using their unique Workspace IDs.
Configuration
Flexibility:
- Cloudpermit is highly configurable, allowing each customer to tailor the application to their specific processes and data requirements.
Considerations for Integration:
- When developing integrations, keep in mind that processes and data content can be reconfigured at any time.
- Ensure your integration can handle dynamic changes in configurations.
Developing Your Own Integration
To build your custom integration using the Cloudpermit API, follow these steps:
Step 1: Contact Us
Email: Send an email to support@cloudpermit.com.
Information to Include:
- Describe your integration needs and objectives.
- Provide information about the customer organization involved.
Step 2: Access to the Training Environment
Development Access:
- We will enable access to the Cloudpermit API in our training environment.
- This allows you to build and test your integration safely.
Consultation:
- In some cases, we may schedule a call to discuss your needs in detail.
Step 3: Development and Testing
Build Your Integration:
- Develop your integration using the API endpoints provided.
- Utilize our API reference documentation for detailed guidance.
Testing:
- Thoroughly test your integration in the training environment to ensure functionality and security.
Step 4: Request Production Access
Demonstration:
- Once development is complete, we may request a demonstration of your integration to verify its functionality.
Enable Production Access:
- We will provide access to the Cloudpermit API in the production environment.
- Note: API access needs to be enabled separately for each customer organization.
Getting Access to Cloudpermit APIs
There are two primary scenarios for accessing the Cloudpermit API:
Scenario A: Using an Existing Product Integration
Action Required:
- Contact our sales team through the support portal.
- We will assist you in setting up the API access.
Process:
- Once permission is granted, we enable the API and provide access to both testing and production environments.
Scenario B: Developing a New Custom/Product Integration
Action Required:
- Contact our sales team through the support portal.
- We will schedule an initial call to understand your requirements.
Process:
- After the call, we enable API access in our development/staging environment.
- Develop and test your integration thoroughly.
- Present your integration to us for review.
- Upon approval, we enable API access in the testing and production environments.
API Key Generation:
After the API is enabled for a customer:
- Users can generate API keys in their My Profile pages.
- Administrators can manage API keys in the User Management view.
Best Practices and Considerations
Security:
- Safeguard your Client ID and Client Secret.
- Use secure storage and transmission practices for authentication credentials.
Error Handling:
- Implement robust error handling in your integration to manage API responses gracefully.
Rate Limits:
- Be mindful of any rate limits imposed by the API to avoid service interruptions.
Data Privacy:
- Ensure compliance with all relevant data protection regulations when accessing and handling data.
Documentation:
- Keep your integration documentation up to date for maintenance and future enhancements.
Support and Resources
Cloudpermit Developer Portal:
- Access the API reference documentation, guides, and resources at the Cloudpermit Developer Portal.
Contact Support:
- For any questions or assistance, reach out to us at support@cloudpermit.com.
- Our team is ready to help you successfully integrate with Cloudpermit.