public-api-docs

Operations API Customers And Groups Guide

Overview

Customers are user accounts on the Wunder Mobility platform. Groups are business accounts that can contain members, cost centers, billing configuration, payment sources, vouchers, and business-unit context. In the Operations API, “group” and “user group” usually refer to this business-account model. Use the Operations API customer and group endpoints when building support tools, customer care workflows, business account administration, membership management, identity-card assignment, credit-rating review, or booking/rental troubleshooting.

Customer and group data is sensitive. Treat read access as privileged and treat writes as support or administrative actions that can affect authentication, billing, booking eligibility, rental requirements, vouchers, payment behavior, and audit history.

Related reference: Operations API Operations API Guide Rental Guide Booking Guide Pricing Guide Error Codes

Core Concepts

Customer Account

A customer account represents one user. Operators usually interact with customers when resolving account setup, verification, payment, rental eligibility, booking issues, or authentication problems.

Important account signals include:

Signal Why it matters
blockState Indicates whether the user is blocked or deleted.
paymentState Indicates payment setup status, such as no payment source, payment source added, or invoicing.
emailIsVerified / phoneIsVerified Affects sign-in and rental requirement fulfillment.
licenseVerificationState / idVerificationState / manualVerificationState Affects whether a user can start rentals that require verification.
creditStatus Affects credit/risk related workflows where enabled.
signupSettled Indicates signup-fee settlement status where configured.
termsAndConditionsAcceptanceState Indicates whether the user accepted the relevant branch terms.
blockedByUnpaidInvoices Explains rental blocks caused by unpaid invoices.
annotations / tags Operator-managed labels and tags used for support workflows.

For custom support tools, use the list endpoint for search results and the details endpoint for a customer profile page. Do not assume a list result contains every field needed to explain a blocked rental or booking.

Profile Setup And Completeness

Customer profile completeness is defined by the rental requirements assigned to the relevant branch and vehicle category. There is no global “complete profile” state that applies to every operator, every branch, or every vehicle type.

A user can exist in the system and be complete for one rental workflow but incomplete for another. For example, if an operator does not configure driving license verification as a rental requirement for a branch/category combination, the user does not need a verified driving license to rent that vehicle type in that branch. If another branch/category requires a license, the same user may be incomplete there until license verification is fulfilled.

This is why operator tools should evaluate profile completeness in the context of the intended rental or booking:

  1. Identify the branchId.
  2. Identify the vehicleCategoryId.
  3. Include booking time or business-account context when relevant.
  4. Call GET /rental-requirements/start.
  5. Use the returned requirements to explain what is missing.

Typical completeness checks:

Area Main fields/endpoints What to check
Contact profile firstName, lastName, birthdate, email, phone, address fields Required profile fields are present for the branch and rental requirement configuration.
Contact verification emailIsVerified, phoneIsVerified Required sign-in/contact methods are verified.
Terms acceptance GET /customers/{id}/details, POST /customers/{id}/accept-terms-and-conditions User accepted the relevant branch terms and conditions.
Payment setup paymentState, paymentSourceIsAvailable, GET /customers/{id}/payment-sources User has a payment source or invoicing setup that satisfies the branch/category requirements.
Signup fee signupSettled / signupFeeSettled Signup fee or signup package requirement is fulfilled where configured.
Driving license licenseVerificationState, licenseExpirationDate, drivingLicenseCategories, /verification Driving license is verified, not expired, and includes required license categories.
ID document idVerificationState, idExpirationDate, idDocumentType, /verification Required identity document verification is complete.
Manual verification manualVerificationState Manual/address/back-office verification is complete where configured.
Credit/risk creditStatus, /customers/{accountId}/ratings Credit or risk requirement is fulfilled where enabled.
Business account GET /customers/{id}/groups, group membership endpoints User is assigned to the correct business account when using business bookings or rentals.

Do not hard-code one universal completeness checklist. The table above lists common signals, but the active checklist comes from the branch/category rental requirements. Use GET /rental-requirements/start with the relevant branchId, vehicleCategoryId, and optional booking or business-account context to explain the exact blocker for a rental or booking workflow.

Terms And Conditions

Terms and conditions are branch-specific from the customer support point of view. GET /customers/{id}/details?branchId={branchId} exposes whether the customer has accepted the relevant terms for that branch through termsAndConditionsAcceptanceState.

Use POST /customers/{id}/accept-terms-and-conditions?branchId={branchId} only for operator workflows where accepting terms on behalf of the customer is permitted by the operator’s process. If a specific terms version must be accepted, pass tacId.

Terms content and versions are managed through the terms endpoints:

Task Endpoint
List terms GET /terms-and-conditions
Create terms POST /terms-and-conditions
Get terms GET /terms-and-conditions/{id}
Update terms PUT /terms-and-conditions/{id}
Delete terms DELETE /terms-and-conditions/{id}

For most custom support tools, the customer details endpoint and the accept endpoint are enough. Terms administration should be exposed only in administrative configuration tools.

Verification And Driving Licenses

Verification is modeled as customer state plus verification attempts. The customer fields tell you the result that affects rental eligibility. The verification endpoints let support teams inspect the underlying attempts and media where permissions allow it.

Driving license verification states:

State Operator meaning
UNVERIFIED No verification has started.
CREATED Verification was initiated but not completed.
PROCESSING User submitted data and verification is still running.
VERIFIED Verification passed. User can satisfy license requirements if all other requirements pass.
REJECTED Verification failed. User must usually retry with corrected data.
RETRY User can retry the verification flow.
VERIFIED_BUT_NEEDS_CHECK Verification passed but requires additional processing or support review.
EXPIRED_LICENSE License document is expired. User must verify with a valid license.
REVIEW Verification requires review by the customer’s team; used for provider flows that support review mode.
PENDING_REVERIFICATION User must reverify the driving license.

Use these endpoints for support review:

Task Endpoint
List verification attempts for a user GET /verification?guserId={id}
Load attempts without full details GET /verification?guserId={id}&includeDetails=false
Get one verification GET /verification/{verificationId}
Get a provider attempt GET /verification/{verificationId}?attemptUuid={attemptUuid}
Get verification media GET /verification/media/{fileUuid}

The platform can integrate with different verification providers, depending on tenant configuration. Custom tools should not hard-code provider-specific assumptions. Instead, read licenseVerificationState, idVerificationState, manualVerificationState, customExternalVerificationState, and the verification attempt data returned by the API. Provider-specific setup and mapping is platform configuration.

Supported provider scope:

Capability Supported provider scope
ID verification Onfido only.
Driving license verification Veriff and Onfido only.
Credit score / credit check CRIF only.

If a tenant does not use one of these providers or does not configure the corresponding rental requirement, the related profile field may still exist but should not be treated as required for renting.

Manual Verification

Manual verification is a back-office verification state used when the tenant requires an operator or support process in addition to, or instead of, an automated provider flow. In the public customer fields it appears as manualVerificationState with values such as UNVERIFIED, PROCESSING, VERIFIED, REJECTED, and RETRY.

Use manual verification state as an explanation signal in support tools. For example, if start requirements fail because manual verification is not fulfilled, the operator should see whether the user is still processing, rejected, or allowed to retry.

Payment Methods And Signup Fees

Payment setup can be represented by several related fields:

Field Meaning
paymentSourceIsAvailable Whether a payment source is available for the customer.
paymentState High-level payment setup state, such as NONE, PUSH_INITIATED, PUSH_COMPLETED, SOURCE_ADDED, or INVOICING.
signupSettled / signupFeeSettled Whether signup fee or signup package requirements are fulfilled where configured.
blockedByUnpaidInvoices Whether unpaid invoices block the user from renting.

Use GET /customers/{id}/payment-sources?branchId={branchId} to review payment sources visible to the operator. The response only includes payment sources the executing operator is allowed to see.

Payment method editing is usually a customer-facing payment-provider flow. Operator tools should generally show payment state, visible payment sources, and requirement failures, then guide the customer to add or update their payment method through the supported user-facing flow. Only expose administrative payment-source actions if the operator role and tenant process explicitly allow them.

Signup fees are handled as a configured signup package or signup voucher requirement. In customer search, signupSettled can filter users by whether that signup requirement has been fulfilled. In rental/start troubleshooting, errors such as missing signup package or failed signup fee payment should be shown as customer setup actions, not as generic payment failures.

Groups And Business Accounts

A group represents a business account. The API and some schemas still use the term “user group”, but for operator tooling this should be understood as the business-account concept. There is no separate non-business group use case for these endpoints.

A business account can own billing behavior, payment sources, members, cost centers, vouchers, tags, and settings that influence business rentals and bookings.

Important group fields include:

Field Meaning
owner / ownerId Account owner.
membersCount Number of active members.
billingCycle Billing cadence for accumulated booking/rental costs.
paymentState Business account payment or invoicing state.
defaultCostCenter Default cost center for the account.
costCenters Cost centers available for business bookings/rentals.
defaultBusinessUnit Default business unit for billing/reporting segmentation.
checkRentalRequirements Whether rental requirements should be checked for this group.
settings.requireDrivingLog Whether members must provide driving-log information.
settings.shouldIgnoreBCategoryRentalRequirement Group-level exception for a category-related rental requirement.

Business bookings and business rentals can require userGroupId, costCenterId, and a business reason. For booking-specific behavior, see the Booking Guide.

Group Membership

Group membership connects users to a business account and defines their role in that account.

At the moment, one user can be a member of only one business account. Custom tools should therefore treat group membership as the user’s business-account assignment, not as a many-to-many segmentation feature.

Role Meaning
OWNER Owner of the group. This role is read-only and cannot be assigned through membership update.
ADMIN Group administrator.
MEMBER Regular group member.

Membership can be ACTIVE or INACTIVE. A member can also have a default cost center and superior email. These fields are relevant for business bookings, business rentals, approvals, and reporting.

Business Units

Business units provide an additional business-account segmentation layer. They can be used for billing, reporting, and default assignment on groups.

Use business-unit endpoints when building administrative tools that manage the business account structure. Do not delete a business unit after it has been referenced; the delete endpoint only works when the business unit has not been referenced anywhere yet. For the full business-unit and billable-branch model, see the Business Units And Billable Branches Guide.

Customer Identity Cards

Customer identity cards are RFID or card identifiers that can be assigned to users. They are typically used when the mobility workflow requires a physical card or identity token.

Card states include:

State Meaning
NEW Card was created but not yet assigned or activated.
ASSIGNED Card is assigned to a user.
UNASSIGNED Card is available but not assigned.
BROKEN Card is broken.
LOST Card was reported lost.
ARCHIVED Card is no longer in active use.

Card numbers must be globally unique. RFID UID and RFID type must also be unique together.

Vouchers And Customer Care Credit

Customer care voucher endpoints apply benefits to a customer or group from a customer-care voucherable. A single voucherable can create multiple vouchers if it contains multiple benefits.

Use the apply-vouchers endpoints for new tooling. The older singular /voucher endpoints are deprecated.

Credit Ratings

Credit-rating endpoints can read, create, approve, reject, or trigger ratings for a customer or group account ID. These workflows are permission-gated and may involve an external provider.

Use the queue endpoint sparingly. Triggering a rating can incur provider costs even if an active rating already exists.

Common Operator Workflows

Search Customers

Use GET /customers for branch-scoped customer search.

Useful filters:

Filter Use it for
branchId Required branch scope. Filters users by branches where they accepted terms and conditions.
searchText Search first name, last name, phone, email, and user ID.
includeChildBranches Include users from child branches. Defaults to true.
signupSettled Filter by signup-fee settlement status where used.

Use GET /customers?simple for lightweight search/autocomplete workflows. It supports filters such as userGroupId, excludeBlockState, excludeImpersonatedUsers, hasUserGroup, excludeBlocked, and includeOperatorsOnly.

View A Customer Profile

Use these endpoints:

Task Endpoint
Get customer GET /customers/{id}
Get detailed customer profile for a branch GET /customers/{id}/details?branchId={branchId}
Get customer’s groups GET /customers/{id}/groups
Get payment sources visible to the operator GET /customers/{id}/payment-sources
Get refresh tokens GET /customers/{id}/refresh-tokens

Use the details endpoint when explaining blocked rentals or bookings because it includes branch-specific terms state, assigned identity cards, unpaid-invoice block information, and statistics.

Create Or Update A Customer

Use:

Task Endpoint
Create customer POST /customers
Update customer PATCH /customers/{id}
Delete customer DELETE /customers/{id}

Customer creation can include authentication type, email/phone, branch, name, birthdate, license verification state, driving license categories, language, newsletter preferences, and reset-password flow.

Customer updates are support actions. Only expose editable fields that your operator workflow explicitly supports; avoid sending a whole customer object back after editing one field unless your tool is designed to preserve every property correctly.

Manage Sign-In And Account Access

Use these endpoints for support workflows:

Task Endpoint
Send password reset email POST /customers/{id}/password-reset-email
Reset password by email POST /customers/reset/{email}
Add email sign-in method POST /customers/{id}/add-email-sign-in-method
Add phone sign-in method POST /customers/{id}/add-phone-sign-in-method
Add email-code sign-in method POST /customers/{id}/add-email-code-sign-in-method
Remove sign-in method POST /customers/{customerId}/remove-sign-in-method
Reset MFA DELETE /customers/{id}/mfa
Log out one customer PATCH /customers/{id}/logout
Log out users by role and branch PATCH /customers/logout

These endpoints can affect user access immediately. Show a confirmation step for destructive access changes such as removing a sign-in method, resetting MFA, or invalidating refresh tokens.

Resolve Rental Or Booking Eligibility

Use customer details together with rental requirement checks:

Task Endpoint
Check rental/booking start requirements GET /rental-requirements/start
Accept branch terms for a customer POST /customers/{id}/accept-terms-and-conditions
Review payment sources GET /customers/{id}/payment-sources
Review customer groups GET /customers/{id}/groups
Review customer identity cards GET /customer-identity-cards?branchId={branchId}&searchText={text}

For support tooling, prefer explaining the failed requirement and the next operator action instead of directly overriding eligibility. Some fixes are customer-facing, such as adding a payment method. Others are operator-facing, such as assigning a card, accepting terms on behalf of a user where allowed, or reviewing verification state.

Manage Customer Tags

Use PUT /customers/{userId}/tags?branchId={branchId}.

Tags are useful for support segmentation and operational workflows. When replacing tags, make sure the operator understands whether the UI is adding/removing one tag or replacing the full tag list.

Manage Groups

Use these endpoints:

Task Endpoint
List groups GET /groups
Create group POST /groups
Get group GET /groups/{userGroupId}
Update group PATCH /groups/{userGroupId}
Delete group DELETE /groups/{userGroupId}
Get payment sources GET /groups/{id}/payment-sources
Get billing summary GET /groups/{id}/billing-summary
Update group tags PUT /groups/{id}/tags

GET /groups requires branchId and can also filter by name, code, or searchText. In user-facing labels, prefer “business account” over “group” unless the tool is intended for technical operators who already know the API naming.

Manage Group Members

Use these endpoints:

Task Endpoint
List members GET /groups/{id}/members
Add one member POST /groups/{userGroupId}/add-member
Add multiple members POST /groups/{userGroupId}/add-members
Create join requests POST /groups/{userGroupId}/create-join-requests
Remove members POST /groups/{userGroupId}/remove-members
View one membership GET /groups/{userGroupId}/members/{userId}
Update one membership PUT /groups/{userGroupId}/members/{userId}

Bulk add/remove responses include successful and unsuccessful IDs. Operator tools should surface partial failures instead of treating the whole request as a generic error.

When updating a membership, do not try to assign OWNER. The owner role is read-only.

Because a user can currently belong to only one business account, adding a member should be treated as assigning that user to the account. If the user is already assigned elsewhere, surface the conflict clearly instead of presenting memberships as independent tags or segments.

Manage Business Units

Use these endpoints:

Task Endpoint
List business units GET /business-units
Create business unit POST /business-units
Get business unit GET /business-units/{id}
Update business unit PUT /business-units/{id}
Delete unused business unit DELETE /business-units/{id}

Business units are administrative configuration. Use them in tools that manage business account structure, not in customer-care screens unless the operator needs to understand billing/reporting segmentation.

Manage Customer Identity Cards

Use these endpoints:

Task Endpoint
List cards GET /customer-identity-cards
Create card POST /customer-identity-cards
Batch create cards PATCH /customer-identity-cards
Get card GET /customer-identity-cards/{cardId}
Update card PATCH /customer-identity-cards/{cardId}
Assign card to user POST /customer-identity-cards/{cardId}/assign
Unassign card POST /customer-identity-cards/{cardId}/unassign

When unassigning a card, choose the resulting state intentionally: UNASSIGNED, BROKEN, LOST, or ARCHIVED.

Apply Customer Care Vouchers

Use these endpoints for new tooling:

Task Endpoint
Apply vouchers to customer POST /customers/{userId}/apply-vouchers
Apply vouchers to group POST /groups/{groupId}/apply-vouchers

Avoid deprecated singular endpoints:

Deprecated endpoint Replacement
POST /customers/{userId}/voucher POST /customers/{userId}/apply-vouchers
POST /groups/{groupId}/voucher POST /groups/{groupId}/apply-vouchers

Review Or Trigger Credit Ratings

Use these endpoints:

Task Endpoint
List ratings GET /customers/{accountId}/ratings
Create manual rating POST /customers/{accountId}/ratings
Approve credit status POST /customers/{accountId}/ratings/approve
Reject credit status POST /customers/{accountId}/ratings/reject
Queue automated rating retrieval POST /customers/{accountId}/ratings/queue

accountId can refer to either a customer or a user group. Expose queueing only to trained operator roles because it can trigger provider costs.

Most Relevant APIs

Area Endpoint
Customer search GET /customers, GET /customers?simple
Customer profile GET /customers/{id}, GET /customers/{id}/details, GET /customers/{id}/groups
Customer write actions POST /customers, PATCH /customers/{id}, DELETE /customers/{id}
Account access /customers/{id}/password-reset-email, /customers/{id}/mfa, /customers/{id}/logout, sign-in method endpoints
Payment sources GET /customers/{id}/payment-sources, GET /groups/{id}/payment-sources
Terms acceptance POST /customers/{id}/accept-terms-and-conditions
Terms administration GET/POST /terms-and-conditions, GET/PUT/DELETE /terms-and-conditions/{id}
Verification review GET /verification, GET /verification/{verificationId}, GET /verification/media/{fileUuid}
Customer/group vouchers POST /customers/{userId}/apply-vouchers, POST /groups/{groupId}/apply-vouchers
Groups GET/POST /groups, GET/PATCH/DELETE /groups/{userGroupId}
Group members /groups/{userGroupId}/add-member, /add-members, /remove-members, /members/{userId}
Group billing GET /groups/{id}/billing-summary
Group tags PUT /groups/{id}/tags
Business units GET/POST /business-units, GET/PUT/DELETE /business-units/{id}
Identity cards GET/POST/PATCH /customer-identity-cards, card detail/assign/unassign endpoints
Credit ratings /customers/{accountId}/ratings endpoints

Permissions And Settings

Customer and group endpoints are permission-gated and often branch-scoped. A user may be allowed to search customers but not update account details, view payment sources, reset MFA, assign cards, manage groups, or trigger credit ratings.

Common permission considerations:

Workflow Permission consideration
Customer search User list/read permission.
Customer profile details User read permission plus branch scope.
Payment sources Payment-source visibility; the response only includes sources the operator can see.
Account access changes Elevated customer support/admin permissions.
Terms acceptance Customer/account administration permission for the branch.
Terms administration Administrative terms configuration permission.
Verification review Verification/customer support permissions; media access should be tightly controlled.
Group administration User group read/write/member permissions.
Group billing summary Finance or group billing visibility.
Vouchers Customer-care voucher permissions.
Identity cards Card management permissions and branch scope.
Credit ratings RATING_READ, RATING_WRITE, or RATING_TRIGGER depending on action.

Use GET /roles/assignments/exists before showing sensitive actions, and still handle permission failures from the action endpoint.

Settings and configuration that can affect this domain include:

Area Why it matters
Terms and conditions settings Control which branch terms must be accepted.
Verification settings Influence which ID/license/manual checks are required.
Payment settings Affect payment-source requirements, invoicing, signup fees, and unpaid-invoice blocks.
Business account settings Affect group workflows, cost centers, driving logs, billing cycles, and approval flows.
Rental requirements Determine whether a customer or group context is eligible to start a rental or booking.
Credit-rating settings Control whether provider-backed credit checks are enabled.
Identity-card configuration Controls whether cards are relevant for customer access or rental workflows.

Use GET /settings only when your tool knows the relevant DASHBOARD or SHARED setting keys. Use /settings-management for administrative settings discovery and configuration.

Implementation Notes For Custom Tools

Review Notes

The following product decisions are reflected in this guide: