> ## Documentation Index
> Fetch the complete documentation index at: https://developers.podero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Parameters

> Complete reference for user account attributes and properties

# User Parameters

User parameters define end-user account information, contact details, and metadata for the Podero platform.

<Tip>
  Use the `external_user_id` field to link Podero users with your internal customer management system.
</Tip>

## Required Parameters

<ParamField body="org_id" type="string (UUID)" required>
  Organization ID that the user belongs to. Assigned during partner onboarding.

  **Example:** `016b78a7-0c7c-4241-a277-015c3ad3cb90`

  **Writable:** No (set at creation, cannot be changed)
</ParamField>

<ParamField body="email" type="string" required>
  User's email address. Must be unique within the organization.

  **Example:** `peter.schmidt@gmail.com`

  **Writable:** Yes
</ParamField>

<ParamField body="role" type="enum" required>
  User's access level within the organization.

  **Options:**

  * `admin` - Full access to all organization resources
  * `staff` - Can manage end-users and devices, but not other staff/admins
  * `user` - End-user with access only to their own resources

  **Example:** `user`

  **Writable:** Yes (admin only can change roles)
</ParamField>

## Optional Parameters

### Personal Information

<ParamField body="external_user_id" type="string">
  Partner's internal user identifier for cross-referencing with your systems.

  **Example:** `134681893870`

  **Writable:** Yes
</ParamField>

<ParamField body="first_name" type="string">
  User's first name.

  **Example:** `Peter`

  **Writable:** Yes
</ParamField>

<ParamField body="last_name" type="string">
  User's last name.

  **Example:** `Schmidt`

  **Writable:** Yes
</ParamField>

### Address Information

<AccordionGroup>
  <Accordion title="Street Address">
    <ParamField body="street_and_number" type="string">
      Primary street address with house number.

      **Example:** `Platz der Republik 1`

      **Writable:** Yes
    </ParamField>

    <ParamField body="street_add_info" type="string">
      Additional address information (apartment number, floor, building, etc.).

      **Example:** `Apt 4B`

      **Writable:** Yes
    </ParamField>
  </Accordion>

  <Accordion title="City & Postal Code">
    <ParamField body="zip_code" type="string">
      Postal/ZIP code.

      **Example:** `11011`

      **Writable:** Yes
    </ParamField>

    <ParamField body="town" type="string">
      City or town name.

      **Example:** `Berlin`

      **Writable:** Yes
    </ParamField>

    <ParamField body="country" type="string">
      Country code in ISO 3166-1 alpha-2 format.

      **Example:** `DE`

      **Writable:** Yes
    </ParamField>
  </Accordion>
</AccordionGroup>

### Location Coordinates

<Note>
  Latitude and longitude can be used for location-based optimization and regional pricing.
</Note>

<ParamField body="latitude" type="float">
  Geographic latitude coordinate.

  **Example:** `40.7128`

  **Writable:** Yes
</ParamField>

<ParamField body="longitude" type="float">
  Geographic longitude coordinate.

  **Example:** `74.0060`

  **Writable:** Yes
</ParamField>

## Usage Examples

### Create User with Minimum Required Fields

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users' \
    -H 'Authorization: Bearer {auth_token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "role": "user",
      "email": "customer@example.com"
    }'
  ```

  ```python Python theme={null}
  response = requests.post(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users',
      headers={
          'Authorization': f'Bearer {auth_token}',
          'Content-Type': 'application/json'
      },
      json={
          'role': 'user',
          'email': 'customer@example.com'
      }
  )
  ```
</CodeGroup>

### Create User with Complete Information

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users' \
    -H 'Authorization: Bearer {auth_token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "role": "user",
      "email": "peter.schmidt@gmail.com",
      "external_user_id": "134681893870",
      "first_name": "Peter",
      "last_name": "Schmidt",
      "street_and_number": "Platz der Republik 1",
      "street_add_info": "Apt 4B",
      "zip_code": "11011",
      "town": "Berlin",
      "country": "DE",
      "latitude": 52.5200,
      "longitude": 13.4050
    }'
  ```

  ```python Python theme={null}
  response = requests.post(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users',
      headers={
          'Authorization': f'Bearer {auth_token}',
          'Content-Type': 'application/json'
      },
      json={
          'role': 'user',
          'email': 'peter.schmidt@gmail.com',
          'external_user_id': '134681893870',
          'first_name': 'Peter',
          'last_name': 'Schmidt',
          'street_and_number': 'Platz der Republik 1',
          'street_add_info': 'Apt 4B',
          'zip_code': '11011',
          'town': 'Berlin',
          'country': 'DE',
          'latitude': 52.5200,
          'longitude': 13.4050
      }
  )
  ```
</CodeGroup>

### Update User Information

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT \
    'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}' \
    -H 'Authorization: Bearer {auth_token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "external_user_id": "updated_id_12345",
      "town": "Munich",
      "country": "DE"
    }'
  ```

  ```python Python theme={null}
  # Only send fields that need to be updated
  response = requests.put(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}',
      headers={
          'Authorization': f'Bearer {auth_token}',
          'Content-Type': 'application/json'
      },
      json={
          'external_user_id': 'updated_id_12345',
          'town': 'Munich',
          'country': 'DE'
      }
  )
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="External User ID">
    * Always set `external_user_id` to link with your internal systems
    * Use a consistent ID format across all users
    * This makes it easy to sync data between systems
    * Useful for customer support and troubleshooting
  </Accordion>

  <Accordion title="Contact Information">
    * Collect user names and addresses for better optimization
    * Location data helps with regional pricing and weather-based optimization
    * Keep email addresses up-to-date for important notifications
    * Validate email format before sending to API
  </Accordion>

  <Accordion title="Role Management">
    * Use `user` role for end-customers
    * Use `staff` role for support team members
    * Reserve `admin` role for managers and senior staff
    * Only admins can change user roles
  </Accordion>

  <Accordion title="Data Privacy">
    * Only collect data you need and have permission to store
    * Follow GDPR and other privacy regulations
    * Provide users with access to their own data
    * Implement data retention policies
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/partner-api/getting-started/create-user">
    Create your first user
  </Card>

  <Card title="User Management" icon="users" href="/partner-api/user-journeys/back-office/user-management">
    Back-office user workflows
  </Card>

  <Card title="Team Administration" icon="user-shield" href="/partner-api/user-journeys/back-office/team-administration">
    Manage staff and admin users
  </Card>
</CardGroup>