Skip to main content

User Extra

The User Extra API provides endpoints for managing additional user information and extended attributes beyond basic user profiles. These endpoints allow you to store, retrieve, and modify supplementary user data such as preferences, custom fields, and device associations within your organization's user management system.

Base URL: https://gate.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The User Extra API category enables comprehensive management of extended user information that supplements core user profiles. This API is designed for applications that need to store additional user attributes, preferences, device associations, and custom metadata that goes beyond standard user account fields.

Key Features:

  • Extended User Profiles: Store custom attributes and preferences for users
  • Device Association: Link users with specific device information and metadata
  • Organization Context: Filter and manage user data within organizational boundaries
  • Flexible Data Structure: Support for custom fields and dynamic user attributes

Common Integration Scenarios:

  • Employee management systems requiring custom employee data
  • Device assignment and tracking systems
  • User preference and settings management
  • Multi-tenant applications with organization-specific user attributes

The endpoints work together to provide full CRUD operations, with advanced filtering capabilities for organization-based data segregation and optional device information inclusion for comprehensive user-device relationship management.

Endpoints

GET /user_extra/

Description: Retrieves a paginated list of user extra information records. This endpoint supports filtering by organization and parent user relationships, making it ideal for multi-tenant applications or when you need to fetch user data within specific organizational contexts.

Use Cases:

  • Display all extended user profiles for an organization's admin dashboard
  • Retrieve user preferences and custom attributes for bulk operations
  • Export user data with device associations for reporting purposes

Full URL Example:

https://gate.zequenze.com/api/v1/user_extra/?parent__organization_id=12345&device_info=true&limit=25&offset=0

Parameters:

Parameter Type In Required Description
parent string query No Filter by parent user ID to get specific user's extra information
parent__organization_id string query No Filter results by organization ID for multi-tenant data isolation
limit integer query No Number of results to return per page (default: 20, max: 100)
offset integer query No The initial index from which to return results for pagination
device_info boolean query No Include associated device information in the response

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user_extra/?parent__organization_id=12345&device_info=true&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 157,
  "next": "https://gate.zequenze.com/api/v1/user_extra/?limit=10&offset=10&parent__organization_id=12345&device_info=true",
  "previous": null,
  "results": [
    {
      "id": 1,
      "parent": 42,
      "organization_id": "12345",
      "preferences": {
        "theme": "dark",
        "notifications": true,
        "language": "en"
      },
      "custom_fields": {
        "department": "Engineering",
        "employee_id": "EMP001",
        "access_level": "senior"
      },
      "device_info": {
        "assigned_devices": [
          {
            "device_id": "DEV-001",
            "device_type": "laptop",
            "serial_number": "ABC123456",
            "assigned_date": "2024-01-15T10:30:00Z"
          }
        ]
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-01T14:20:00Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of user extra information
401 Unauthorized - Invalid or missing API token
403 Forbidden - Insufficient permissions to access user data

POST /user_extra/

Description: Creates a new user extra information record with custom attributes, preferences, and metadata. This endpoint allows you to extend user profiles with organization-specific data and custom fields tailored to your application's needs.

Use Cases:

  • Create extended profiles for new employees with custom attributes
  • Initialize user preferences and settings during onboarding
  • Add device associations and metadata for new user-device assignments

Full URL Example:

https://gate.zequenze.com/api/v1/user_extra/

Parameters:

Parameter Type In Required Description
data object body Yes JSON object containing user extra information fields

cURL Example:

curl -X POST "https://gate.zequenze.com/api/v1/user_extra/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": 42,
    "organization_id": "12345",
    "preferences": {
      "theme": "light",
      "notifications": true,
      "language": "en"
    },
    "custom_fields": {
      "department": "Marketing",
      "employee_id": "EMP002",
      "access_level": "standard",
      "hire_date": "2024-01-15"
    }
  }'

Example Response:

{
  "id": 158,
  "parent": 42,
  "organization_id": "12345",
  "preferences": {
    "theme": "light",
    "notifications": true,
    "language": "en"
  },
  "custom_fields": {
    "department": "Marketing",
    "employee_id": "EMP002",
    "access_level": "standard",
    "hire_date": "2024-01-15"
  },
  "created_at": "2024-02-15T09:15:00Z",
  "updated_at": "2024-02-15T09:15:00Z"
}

Response Codes:

Status Description
201 Created - User extra information successfully created
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing API token
409 Conflict - User extra record already exists for this user

GET /user_extra/{id}/

Description: Retrieves detailed information for a specific user extra record by its unique identifier. This endpoint provides access to all custom attributes, preferences, and optionally device information for a single user's extended profile.

Use Cases:

  • Display user-specific settings and preferences in application UI
  • Retrieve custom employee data for HR management systems
  • Fetch user-device associations for IT asset management

Full URL Example:

https://gate.zequenze.com/api/v1/user_extra/158/?device_info=true

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user extra record
device_info boolean query No Include associated device information in the response

cURL Example:

curl -X GET "https://gate.zequenze.com/api/v1/user_extra/158/?device_info=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 158,
  "parent": 42,
  "organization_id": "12345",
  "preferences": {
    "theme": "dark",
    "notifications": false,
    "language": "es",
    "timezone": "America/Los_Angeles"
  },
  "custom_fields": {
    "department": "Engineering",
    "employee_id": "EMP002",
    "access_level": "senior",
    "manager_id": "EMP001",
    "office_location": "Building A, Floor 3"
  },
  "device_info": {
    "assigned_devices": [
      {
        "device_id": "DEV-002",
        "device_type": "laptop",
        "serial_number": "XYZ789012",
        "model": "MacBook Pro 16",
        "assigned_date": "2024-01-15T10:30:00Z",
        "status": "active"
      },
      {
        "device_id": "DEV-003",
        "device_type": "phone",
        "serial_number": "MOB456789",
        "model": "iPhone 15 Pro",
        "assigned_date": "2024-01-20T14:00:00Z",
        "status": "active"
      }
    ],
    "device_count": 2
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-02-10T16:45:00Z"
}

Response Codes:

Status Description
200 Success - Returns the requested user extra information
401 Unauthorized - Invalid or missing API token
404 Not Found - User extra record with specified ID does not exist
403 Forbidden - Insufficient permissions to access this user's data

PUT /user_extra/{id}/

Description: Completely replaces all data for a specific user extra record with new information. This endpoint performs a full update, requiring all fields to be provided in the request body. Use this when you need to replace the entire user extra profile.

Use Cases:

  • Complete profile updates during employee role changes
  • Bulk synchronization of user data from external systems
  • Resetting user preferences to new default configurations

Full URL Example:

https://gate.zequenze.com/api/v1/user_extra/158/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user extra record to update
data object body Yes Complete JSON object with all user extra information fields

cURL Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user_extra/158/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": 42,
    "organization_id": "12345",
    "preferences": {
      "theme": "auto",
      "notifications": true,
      "language": "fr",
      "timezone": "Europe/Paris"
    },
    "custom_fields": {
      "department": "Sales",
      "employee_id": "EMP002",
      "access_level": "manager",
      "manager_id": null,
      "office_location": "Building B, Floor 2",
      "promotion_date": "2024-02-01"
    }
  }'

Example Response:

{
  "id": 158,
  "parent": 42,
  "organization_id": "12345",
  "preferences": {
    "theme": "auto",
    "notifications": true,
    "language": "fr",
    "timezone": "Europe/Paris"
  },
  "custom_fields": {
    "department": "Sales",
    "employee_id": "EMP002",
    "access_level": "manager",
    "manager_id": null,
    "office_location": "Building B, Floor 2",
    "promotion_date": "2024-02-01"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-02-15T11:20:00Z"
}

Response Codes:

Status Description
200 Success - User extra information completely updated
400 Bad Request - Invalid data format or validation errors
401 Unauthorized - Invalid or missing API token
404 Not Found - User extra record does not exist
403 Forbidden - Insufficient permissions to modify this record

PATCH /user_extra/{id}/

Description: Partially updates specific fields of a user extra record without affecting other existing data. This endpoint is ideal for updating individual preferences, custom fields, or specific attributes while preserving all other information.

Use Cases:

  • Update user preferences without changing custom employee data
  • Modify specific custom fields like department or access level
  • Update individual settings while maintaining existing configurations

Full URL Example:

https://gate.zequenze.com/api/v1/user_extra/158/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user extra record to update
data object body Yes JSON object containing only the fields to be updated

cURL Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user_extra/158/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "theme": "dark",
      "notifications": false
    },
    "custom_fields": {
      "access_level": "senior_manager"
    }
  }'

Example Response:

{
  "id": 158,
  "parent": 42,
  "organization_id": "12345",
  "preferences": {
    "theme": "dark",
    "notifications": false,
    "language": "fr",
    "timezone": "Europe/Paris"
  },
  "custom_fields": {
    "department": "Sales",
    "employee_id": "EMP002",
    "access_level": "senior_manager",
    "manager_id": null,
    "office_location": "Building B, Floor 2",
    "promotion_date": "2024-02-01"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-02-15T14:30:00Z"
}

Response Codes:

Status Description
200 Success - Specified fields updated successfully
400 Bad Request - Invalid field values or data format
401 Unauthorized - Invalid or missing API token
404 Not Found - User extra record does not exist
403 Forbidden - Insufficient permissions to modify this record

DELETE /user_extra/{id}/

Description: Permanently removes a user extra record and all associated custom data, preferences, and metadata. This action cannot be undone and will completely delete the extended user profile information.

Use Cases:

  • Clean up user data when employees leave the organization
  • Remove test or duplicate user extra records
  • Comply with data retention policies and user data deletion requests

Full URL Example:

https://gate.zequenze.com/api/v1/user_extra/158/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the user extra record to delete

cURL Example:

curl -X DELETE "https://gate.zequenze.com/api/v1/user_extra/158/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response:

HTTP/1.1 204 No Content

Response Codes:

Status Description
204 No Content - User extra record successfully deleted
401 Unauthorized - Invalid or missing API token
404 Not Found - User extra record does not exist
403 Forbidden - Insufficient permissions to delete this record

Common Use Cases

Use Case 1: Employee Onboarding System

Create comprehensive employee profiles during onboarding by using POST /user_extra/ to initialize custom employee data, preferences, and device assignments. Then use PATCH requests to gradually update specific information as the employee completes different onboarding stages.

Use Case 2: Multi-Tenant Application Data Management

Leverage the parent__organization_id filter with GET /user_extra/ to maintain data isolation between different organizations. This ensures each tenant only sees their own user data while sharing the same API infrastructure.

Use Case 3: User Preference Management

Use PATCH /user_extra/{id}/ for real-time preference updates when users change settings in your application. This allows granular updates without overwriting other custom fields or device associations.

Use Case 4: Device Assignment Tracking

Utilize the device_info parameter with GET requests to track user-device relationships for IT asset management. Combine with organization filtering to manage devices across different departments or business units.

Use Case 5: Data Cleanup and Compliance

Implement automated data retention policies using DELETE /user_extra/{id}/ for removing user data after employment termination or when users request data deletion for privacy compliance.

Best Practices

  • Pagination Management: Always use limit and offset parameters for large datasets. Start with smaller page sizes (10-25 records) and increase based on performance requirements.

  • Efficient Filtering: Use parent__organization_id filtering early in your queries to reduce data transfer and improve response times in multi-tenant environments.

  • Selective Device Information: Only request device_info when necessary, as it can significantly increase response size and processing time for large user bases.

  • Partial Updates: Prefer PATCH over PUT for most update operations to avoid accidentally overwriting existing data and reduce network payload size.

  • Error Handling: Implement proper retry logic for 429 (rate limiting) responses and graceful degradation for 503 (service unavailable) errors.

  • Data Validation: Validate custom_fields structure and preferences format on the client side before sending requests to reduce 400 errors and improve user experience.

  • Security Considerations: Always validate user permissions before allowing access to organization-specific data, especially in multi-tenant applications where data isolation is critical.

Back to top