User Extra

ManageThe User Extra API provides endpoints for managing additional user information and extended profileattributes data.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/

RetrieveDescription: Retrieves a paginated list of user extra information recordsrecords. 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 optionaldevice filteringassociations andfor pagination.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 offor themulti-tenant parentdata userisolation
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 theresults resultsfor pagination
device_info	boolean	query	No	Include associated device information in the response

ExamplecURL Request:Example:

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

Example Response:

{
  "count": 45,157,
  "next": "https://gate.zequenze.com/api/v1/user_extra/?limit=2010&offset=20"10&parent__organization_id=12345&device_info=true",
  "previous": null,
  "results": [
    {
      "id": 1,
      "parent": 42,
      "user123"organization_id": "12345",
      "preferences": {
        "theme": "dark",
        "notifications": true,
        "language": "en"
      },
      "custom_fields": {
        "department": "Engineering",
        "job_title"employee_id": "Senior Developer"EMP001",
        "phone_extension"access_level": "1234"senior"
      },
      "emergency_contact"device_info": {
        "assigned_devices": [
          {
            "device_id": "Jane Doe"DEV-001",
            "emergency_phone"device_type": "+1234567890"laptop",
            "serial_number": "ABC123456",
            "assigned_date": "2024-01-15T10:30:00Z"
          }
        ]
      },
      "created_at": "2023-10-01T10:00:2024-01-15T10:30:00Z",
      "updated_at": "2023-10-01T10:00: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/

CreateDescription: Creates a new additionaluser 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 anew user.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	UserJSON object containing user extra information datafields

ExamplecURL Request:Example:

curl -X POST "https://gate.zequenze.com/api/v1/user_extra/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
    "parent": 42,
    "user123"organization_id": "12345",
    "preferences": {
      "theme": "light",
      "notifications": true,
      "language": "en"
    },
    "custom_fields": {
      "department": "Marketing",
      "job_title"employee_id": "Marketing Manager"EMP002",
      "phone_extension"access_level": "5678"standard",
      "emergency_contact"hire_date": "John Smith",
  "emergency_phone": "+0987654321",
  "notes": "Additional notes about the user"2024-01-15"
    }
  }'

Example Response:

{
  "id": 2,158,
  "parent": 42,
  "user123"organization_id": "12345",
  "preferences": {
    "theme": "light",
    "notifications": true,
    "language": "en"
  },
  "custom_fields": {
    "department": "Marketing",
    "job_title"employee_id": "Marketing Manager"EMP002",
    "phone_extension"access_level": "5678"standard",
    "emergency_contact"hire_date": "John2024-01-15"
  Smith",
  "emergency_phone": "+0987654321",
  "notes": "Additional notes about the user"},
  "created_at": "2023-10-01T14:30:2024-02-15T09:15:00Z",
  "updated_at": "2023-10-01T14:30: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}/

RetrieveDescription: Retrieves detailed information for a specific user extra informationrecord by ID.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

ExamplecURL Request:Example:

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

Example Response:

{
  "id": 1,158,
  "parent": 42,
  "user123"organization_id": "12345",
  "preferences": {
    "theme": "dark",
    "notifications": false,
    "language": "es",
    "timezone": "America/Los_Angeles"
  },
  "custom_fields": {
    "department": "Engineering",
    "job_title"employee_id": "Senior Developer"EMP002",
    "phone_extension"access_level": "1234"senior",
    "emergency_contact"manager_id": "Jane Doe"EMP001",
    "emergency_phone"office_location": "+1234567890"Building A, Floor 3"
  },
  "notes"device_info": {
    "assigned_devices": [
      {
        "device_id": "TeamDEV-002",
        lead"device_type": for"laptop",
        mobile"serial_number": development""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": "2023-10-01T10:00:2024-01-15T10:30:00Z",
  "updated_at": "2023-10-01T10:00: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 401403 UnauthorizedForbidden - Insufficient permissions to access this user's data

---

PUT /user_extra/{id}/

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

record.

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 datafields

ExamplecURL Request:Example:

curl -X PUT "https://gate.zequenze.com/api/v1/user_extra/1/158/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
    "parent": 42,
    "user123"organization_id": "12345",
    "preferences": {
      "theme": "auto",
      "notifications": true,
      "language": "fr",
      "timezone": "Europe/Paris"
    },
    "custom_fields": {
      "department": "Engineering"Sales",
      "job_title"employee_id": "Lead Developer"EMP002",
      "phone_extension"access_level": "1234"manager",
      "emergency_contact"manager_id": null,
      "office_location": "JaneBuilding Doe"B, Floor 2",
      "emergency_phone"promotion_date": "+1234567890",
  "notes": "Team lead for mobile and web development"2024-02-01"
    }
  }'

Example Response:

{
  "id": 1,158,
  "parent": 42,
  "user123"organization_id": "12345",
  "preferences": {
    "theme": "auto",
    "notifications": true,
    "language": "fr",
    "timezone": "Europe/Paris"
  },
  "custom_fields": {
    "department": "Engineering"Sales",
    "job_title"employee_id": "Lead Developer"EMP002",
    "phone_extension"access_level": "1234"manager",
    "emergency_contact"manager_id": null,
    "office_location": "JaneBuilding Doe"B, Floor 2",
    "emergency_phone"promotion_date": "+1234567890",2024-02-01"
  "notes": "Team lead for mobile and web development"},
  "created_at": "2023-10-01T10:00:2024-01-15T10:30:00Z",
  "updated_at": "2023-10-01T16:45: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 401403 UnauthorizedForbidden - Insufficient permissions to modify this record

---

PATCH /user_extra/{id}/

Description: Partially updateupdates specific fields of a user extra informationrecord 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	PartialJSON userobject extracontaining informationonly datathe fields to be updated

ExamplecURL Request:Example:

curl -X PATCH "https://gate.zequenze.com/api/v1/user_extra/1/158/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/jsonjson" \
  -d '{
    "preferences": {
      "job_title"theme": "Senior Lead Developer"dark",
      "notes"notifications": false
    },
    "custom_fields": {
      "access_level": "Promoted to senior lead position"senior_manager"
    }
  }'

Example Response:

{
  "id": 1,158,
  "parent": 42,
  "user123"organization_id": "12345",
  "preferences": {
    "theme": "dark",
    "notifications": false,
    "language": "fr",
    "timezone": "Europe/Paris"
  },
  "custom_fields": {
    "department": "Engineering"Sales",
    "job_title"employee_id": "Senior Lead Developer"EMP002",
    "phone_extension"access_level": "1234"senior_manager",
    "emergency_contact"manager_id": null,
    "office_location": "JaneBuilding Doe"B, Floor 2",
    "emergency_phone"promotion_date": "+1234567890",2024-02-01"
  "notes": "Promoted to senior lead position"},
  "created_at": "2023-10-01T10:00:2024-01-15T10:30:00Z",
  "updated_at": "2023-10-01T17:20: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 401403 UnauthorizedForbidden - Insufficient permissions to modify this record

---

DELETE /user_extra/{id}/

DeleteDescription: Permanently removes a user extra informationrecord 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

ExamplecURL Request:Example:

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

Example Response:

HTTP/1.1 204 No Content

Response Codes:

Status	Description
204	No Content (Successfully- deleted)User extra record successfully deleted

401 Unauthorized - Invalid or missing API token 404 Not Found - User extra record does not exist 401403 UnauthorizedForbidden - 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

• Use pagination

  Pagination Management: Always use limit and offset parameters for large datasets. Start with smaller page sizes (limit10-25 records) and offset)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 retrievingnecessary, as it can significantly increase response size and processing time for large datasetsuser tobases.

improve performance Include the

Partial device_infoUpdates: parameter only when device information is specifically needed

UsePrefer PATCH instead ofover PUT for partialmost updatesupdate 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 bandwidth400 errors and avoidimprove overwritinguser unchangedexperience.

fields Filter by

Security parentConsiderations: or parent__organization_id to scope results to specific users or organizations

Always validate requireduser fieldspermissions before sendingallowing POST/PUT requestsaccess to avoidorganization-specific 400data, errorsespecially Storein emergencymulti-tenant contactapplications information securely and ensure compliance withwhere data protectionisolation regulationsis Considercritical. implementing soft deletes instead of hard deletes for audit trail purposes

---