Skip to content
PerfectGym Next Open API
/
/
Working with customer sel...
Last updated

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

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.
  • Payment data amendments are only possible when the customer is already on SEPA direct debit. If the customer's payment method is anything other than direct debit, the payment data domain is always reported as READ and POST create payment data amendment is rejected — regardless of the studio's amendment configuration.

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

For the payment data domain specifically, READ is also returned whenever the customer's current payment method is not SEPA direct debit. In that case the domain is read-only irrespective of the studio's amendment configuration, and the customer must first be moved to direct debit before payment data amendments can be submitted.

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):

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

Example POST response shape (illustrative):

{
  "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):

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

Example POST response shape (illustrative):

{
  "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.

Note: Payment data amendments require the customer to already be on SEPA direct debit. If the customer is on any other payment method, the GET response reports amendmentConfigurationStatus: READ and the POST is rejected.

  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):

{
  "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):

{
  "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.
  • Assuming payment data is amendable for every customer: Payment data amendments require the customer to be on SEPA direct debit. For customers on any other payment method, GET reports amendmentConfigurationStatus: READ and POST is rejected — this is independent of the studio's amendment configuration. Move the customer to direct debit before attempting a payment data amendment.
  • 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:

Previous page
Next page