How to extract user information from projects using Cintoo API

Overview

This guide demonstrates how to extract user information (name, email, roles, permissions) for each project using Cintoo API. This can be achieved by making two separate API calls and joining the results based on user IDs.

Prerequisites

• a valid Cintoo API access token
• access to the Cintoo Cloud API, with necessary permissions to fetch project and user data
• familiarity with Python and REST API calls

Workflow

To retrieve user information from individual projects, you will need to:

1. Call the /projects endpoint to get user IDs and their roles within projects.
2. Call the /users endpoint to get detailed user information.
3. Join the results based on user IDs to get complete user details, including project-specific roles and permissions.

Python Script

import requests

# Replace with your access token, account ID, and base URLs
access_token = "YOUR_ACCESS_TOKEN"
account_id = "YOUR_ACCOUNT_ID"
base_url = "https://aec.cintoo.com"

# Set up headers for authorization
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# 1. Get all projects and users in the projects
def get_projects_users():
    url = f"{base_url}/api/accounts/{account_id}/projects"
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        projects = response.json()
        user_roles = {}
        
        # Extract user IDs from each project
        for project in projects:
            project_id = project["id"]
            user_ids = project.get("userIds", [])
            
            # Add roles to the dictionary
            user_roles.update({user_id: {"roles": project.get("permissions", {}), "project_id": project_id} for user_id in user_ids})
        
        return user_roles
    else:
        print(f"Failed to fetch projects: {response.status_code} - {response.text}")
        return {}

# 2. Get all user details
def get_users():
    url = f"{base_url}/api/accounts/{account_id}/users"
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        users = response.json()
        return {user["id"]: user for user in users}
    else:
        print(f"Failed to fetch users: {response.status_code} - {response.text}")
        return {}

# Join project user data with user details
def join_user_data(user_roles, users):
    complete_user_info = []

    for user_id, role_info in user_roles.items():
        user_details = users.get(user_id)
        if user_details:
            combined_info = {
                "user_id": user_id,
                "name": f"{user_details.get('firstname', '')} {user_details.get('lastname', '')}",
                "email": user_details.get("email", ""),
                "roles": role_info["roles"],
                "project_id": role_info["project_id"]
            }
            complete_user_info.append(combined_info)

    return complete_user_info

# Main execution
if __name__ == "__main__":
    user_roles = get_projects_users()
    users = get_users()

    if user_roles and users:
        complete_user_info = join_user_data(user_roles, users)
        
        # Print or process the combined user information
        for user_info in complete_user_info:
            print(user_info)

How the code works

1. Get Project Users:
   • Uses the /projects endpoint to get user IDs and roles for each project.
2. Get User Details:
   • Uses the /users endpoint to fetch user information (name, email, etc.).
3. Join Results:
   • Combines project user roles with user details, resulting in a complete user dataset for each project.

Requirements

• Install the requests library:
  
  
  pip install requests

• Replace placeholders (YOUR_ACCESS_TOKEN, YOUR_ACCOUNT_ID) with actual values.

Notes

• The Cintoo API uses JWT tokens for authentication, which must be passed in the request headers.
• Ensure your access token is valid and has the necessary permissions to fetch user and project data.

Best Practices

• Use a sandbox environment to test the API calls before running them in production.
• Implement error handling to manage API call failures or token expiration.

Additional Information

For more details on Cintoo API endpoints, please take a look at the Cintoo API Documentation.