# Working with customer self-service

## Intro

Use case description of how to use the customer self-service collection to display customer profile data and process customer-initiated data changes via the Open API.

This collection follows an amendment model:

- GET endpoints return current data state and expose any pending change request.
- POST endpoints submit new amendment requests per data domain.
- DELETE endpoint cancels an existing amendment before it is processed.


Each GET response also includes an `amendmentConfigurationStatus` that controls whether changes go through a verification queue or are applied directly.

## Relevant Endpoints

- [GET customer's contact data](../openapi/openapi/customers-self-service/getCustomerContactData)
- [POST create contact data amendment](../openapi/openapi/customers-self-service/createCustomerContactDataAmendment)
- [GET customer's address data](../openapi/openapi/customers-self-service/getCustomerAddressData)
- [POST create address data amendment](../openapi/openapi/customers-self-service/createCustomerAddressDataAmendment)
- [GET customer's master data](../openapi/openapi/customers-self-service/getCustomerMasterData)
- [POST create master data amendment](../openapi/openapi/customers-self-service/createCustomerMasterDataAmendment)
- [GET customer's payment data](../openapi/openapi/customers-self-service/getCustomerPaymentData)
- [POST create payment data amendment](../openapi/openapi/customers-self-service/createCustomerPaymentDataAmendment)
- [DELETE withdraw customer's amendment](../openapi/openapi/customers-self-service/withdrawAmendment)


## Customer self-service

The customer self-service collection enables partners to build profile maintenance flows for members while keeping data changes transparent and auditable.

Core behavior:

- Changes are submitted as domain-specific amendments, not as direct updates.
- Each GET response includes `amendmentConfigurationStatus`: `CHANGES_WITHOUT_VERIFICATION` (applied instantly), `CHANGES_REQUIRE_VERIFICATION` (queued for studio approval), or `READ` (domain is view-only and cannot be amended).
- Only one active amendment can exist per data domain at a time. Attempting to create a second amendment while one is pending returns an error.
- Each GET response includes a `pendingAmendment` object when a change request is already in progress. The `id` field in that object is required to withdraw the amendment.
- Payment amendments may require a customer signature (`requireSignature: true`), passed as `signature.base64SvgSignature` in the POST request.


Recommended use cases:

- Member profile maintenance in web or app
- Contact and address correction flows
- Payment method change requests
- Self-service with optional studio-side review


## Display and amendment flow

### 1. Retrieve current data

Use the GET endpoint for each domain before rendering an edit screen.

Use this to:

- prefill user-facing forms with current values
- read `amendmentConfigurationStatus` to determine whether changes apply immediately or require review
- detect a `pendingAmendment` and surface it to the user before allowing new submissions


### 2. Check amendment configuration status

Before rendering a change form, evaluate `amendmentConfigurationStatus`:

- `CHANGES_WITHOUT_VERIFICATION` — changes apply immediately on POST
- `CHANGES_REQUIRE_VERIFICATION` — changes go into a studio task queue; show the user that approval is pending
- `READ` — the domain is read-only; do not offer an edit option


### 3. Submit an amendment

When a customer confirms their changes, POST to the corresponding domain endpoint.

Use this to:

- submit changes for one domain at a time
- store the returned `id` (amendment proposal id) for subsequent withdraw calls if needed
- show domain-level feedback: immediate confirmation or pending state depending on configuration


Best practice:

- submit only one amendment per domain at a time
- explicitly handle the 409 conflict case for when a pending amendment already exists


### 4. Withdraw an amendment

If a pending amendment needs to be cancelled before it is processed, use DELETE withdraw customer's amendment with the `customerId` and `amendmentId` (the `id` returned from the POST response).

Use this to:

- let users undo a submitted change request
- clear the pending state so a corrected amendment can be submitted


### 5. Refresh data after mutations

After any POST or DELETE, re-fetch the relevant GET endpoint to keep frontend state in sync.

## Complete workflow examples

Note: The payload examples below are integration-oriented drafts. Validate all field names and structures against the current OpenAPI schema before publishing or implementation.

### Example 1: Update contact data

Scenario: Customer changes their email address.

1. GET customer's contact data
2. Check `amendmentConfigurationStatus`
3. Show prefilled edit form
4. POST create contact data amendment
5. Re-fetch GET customer's contact data


Example POST request payload (illustrative):


```json
{
  "email": "new-email@example.com",
  "phonePrivate": "+49 00000000",
  "phonePrivateMobile": "+49 00000000000",
  "phoneBusiness": "+49 00000000",
  "phoneBusinessMobile": "+49 00000000000"
}
```

Example POST response shape (illustrative):


```json
{
  "id": 4521,
  "email": "new-email@example.com",
  "phonePrivate": "+49 00000000",
  "phonePrivateMobile": "+49 00000000000",
  "phoneBusiness": "+49 00000000",
  "phoneBusinessMobile": "+49 00000000000"
}
```

### Example 2: Submit address change, then withdraw

Scenario: Customer submits a new address but notices a typo and cancels before it is processed.

1. GET customer's address data
2. POST create address data amendment
3. Store returned `id` (e.g., `7834`)
4. Customer requests cancellation
5. DELETE withdraw customer's amendment (`amendmentId: 7834`)
6. Re-fetch GET customer's address data


Example POST request payload (illustrative):


```json
{
  "street": "Am Bahnhof",
  "houseNumber": "90",
  "zipCode": "12133",
  "city": "Munich",
  "countryCode": "DE"
}
```

Example POST response shape (illustrative):


```json
{
  "id": 7834,
  "street": "Am Bahnhof",
  "houseNumber": "90",
  "zipCode": "12133",
  "city": "Munich",
  "countryCode": "DE"
}
```

DELETE withdraw returns HTTP 200 with no response body.

### Example 3: Update payment data with signature

Scenario: Customer updates their bank account. The studio requires a customer signature.

1. GET customer's payment data
2. Check `requireSignature: true` in response
3. Present signature capture in UI
4. POST create payment data amendment with IBAN, BIC, and base64 SVG signature
5. Re-fetch GET customer's payment data


Example POST request payload (illustrative):


```json
{
  "accountHolder": "Sven Hannawald",
  "bankName": "Deutsche Bank",
  "iban": "DE91 1000 0000 0123 4567 89",
  "bic": "DEUTDEFFXXX",
  "signature": {
    "base64SvgSignature": "<base64-encoded SVG>"
  }
}
```

Example POST response shape (illustrative):


```json
{
  "id": 3301,
  "accountHolder": "Sven Hannawald",
  "bankName": "Deutsche Bank",
  "iban": "DE91 1000 0000 0123 4567 89",
  "bic": "DEUTDEFFXXX",
  "requireSignature": true
}
```

## Common integration challenges

- Ignoring `amendmentConfigurationStatus`: Always read this field before rendering an edit option. Submitting to a `READ` domain returns an error.
- Missing pending amendment check: If `pendingAmendment` is present on GET, block new submissions for that domain and surface the pending state to the user.
- Concurrent amendment conflict: Attempting a second POST while one is pending returns 409. Handle this explicitly rather than letting it surface as a generic error.
- No post-mutation refresh: Always re-fetch the relevant GET endpoint after POST or DELETE to prevent stale form state.
- Skipping signature handling: For payment amendments where `requireSignature` is true, the POST request must include `signature.base64SvgSignature`. Missing this field will cause a validation failure.
- Cross-domain saves: Combining changes from multiple domains in a single UI action complicates error handling. Submit one amendment domain per action.


## Customer self-service webhook events

For event-driven synchronization, subscribe to the relevant customer update events. These are triggered when a pending amendment is approved or rejected by studio staff, or when data is updated directly, and can be used to keep local profile state in sync.

Event reference:

- [Event types](../webhooks/event-types/)