Description

Purpose and use

The Customers module holds the legal or personal banking relationship. A customer record is the anchor onboarding data hangs from: company details, addresses, team members, shareholders, signatories, status, documents, roles, and product eligibility (tariff and FX tariff). It is the entity every downstream account, payment, and compliance workflow refers back to.

Who uses this. Onboarding teams create and progress records. Relationship managers and customer service maintain team membership and company data. Compliance officers review shareholders, signatories, and status transitions. Operations and auditors read the record throughout the customer lifecycle.

How it works. A customer record links to personas, addresses, accounts, KYB answers, uploads, signatories, team members, and permissions. Its status controls which actions may continue. On creation the system also provisions a mirror root counterparty for the same entity and grants the creator access to it, so later flows that need counterparty context (settlement, payment routing) already have a linked reference.

What users do. Check a company name is free, create the customer, invite and manage team members, add signatories and shareholders, upload an avatar, move the record through its status stages, and expose a limited public profile to external integrators.

Outcomes and side effects. Creating a customer provisions the root counterparty, persists its reference on the customer, bootstraps customer roles, and grants role-scoped access. Customer changes drive roles, notifications, onboarding tasks, and document requirements. They do not post ledger entries on their own — a ledger posting only happens when a downstream money-movement or fee workflow runs.

Related manuals: KYB, Accounts & Portfolios, Users, Risk Assessment.

Who operates each area

Access and controls

Nearly all operations require an authenticated banking user (bearer sign-in) and are further filtered by role — a user sees and edits only the records their role permits. Three endpoints are the exception and use an API key instead of a user sign-in, because they serve external or pre-login flows:

• the public company profile (a cut-down view: abbreviation, logo, and name only);
• signatory invitation verification (the invitee has not signed in yet);
• team invitation verification (same reason).

The company-name check is rate limited to a small number of attempts per minute per user, to stop bulk probing of which companies already exist. Every operation is written to the audit trail with the acting user, the action, and a timestamp for compliance review.

Customer record

Core company data

Legal and relationship data

Status stages

Tasks

Check a company name is available

POST /v1/customers/check-name

Before creating a customer, verify the company name is not already taken. Matching ignores case and surrounding spaces, so "Acme AG" and "acme ag " are treated as the same name. The check returns whether the name is free and the normalized form that was compared. Repeated rapid calls are throttled. Use this to give the onboarding user immediate feedback before they submit the full form.

Create a customer

POST /v1/customers

Creates the company record from its core and legal data (name, UID, legal form, seat, and starting status are required). On success the module does more than store the row:

1. Provisions the root counterparty for the same entity (skipped if one is already linked).
2. Persists that counterparty reference on the customer.
3. Grants the creating user full access to the root counterparty.
4. After customer roles are bootstrapped, grants role-scoped counterparty permissions from configuration.

The created record is returned including its counterparty reference. If the UID is already in use by another customer, creation is rejected as a duplicate — resolve the conflict before retrying.

View or list customers

GET /v1/customers

GET /v1/customers/{id}

GET /v2/customers

• List (v1) returns a plain list of customers and accepts simple field filters (UID, name, status, legal form, seat, principal, active, and audit fields).
• List (v2) is the search-oriented listing: it accepts structured search fields, sorting, and paging, and returns a result envelope carrying the page of records plus the total and whether more pages remain. Use v2 for operational search screens and grids.
• Get one returns the full record with its addresses.

Update a customer

PUT /v1/customers/{id}

PATCH /v1/customers/{id}

PUT /v1/customers/{id}/restricted

• Full update replaces the editable company fields and returns the updated record.
• Partial update (status patch) changes only the fields supplied — any of: tariff, FX tariff, type, status, signing room, or principal. This is the normal way to move a customer between status stages.
• Restricted update edits only the presentation fields (abbreviation, logo, description) and is used where a caller may touch branding but not legal data.

Set the tariff or FX tariff

PUT /v1/customers/{id}/tariff

PUT /v1/customers/{id}/fx

Assign the pricing schedule (tariff) or the foreign-exchange schedule (FX tariff) that applies to this customer. Each takes the identifier of the schedule to apply.

Delete a customer

DELETE /v1/customers/{id}

Permanently removes the customer record. This is a hard removal, not a deactivation — the row is gone, not merely marked inactive. Consider the linked root counterparty and any dependent records before removing. To take a customer out of use without deleting it, change its status to SUSPENDED or clear its active flag instead.

Manage the company avatar

POST /v1/customers/avatar

GET /v1/customers/{id}/avatar

Upload or replace the company avatar (the image is supplied inline against the owning customer), and read it back. Both the upload result and the read return the avatar as a data record — image content plus its metadata — not a raw image download.

Expose a public profile

GET /v1/customers/{id}/public

Returns a minimal public view — abbreviation, logo, and name only — for use by external integrators. This endpoint is reached with an API key rather than a user sign-in, and deliberately exposes nothing sensitive.

Team members

A customer's team is the set of users who act on its behalf, each carrying a role and a position.

Invite a team member

POST /v1/customers/{id}/teams/invite

Invites a person (first name, last name, email, position, and whether they hold signature rights) to the customer's team. The system sends the invitation and confirms it was sent.

List team members

GET /v2/customers/{id}/teams

Returns the team as a searchable, paged result envelope, each entry carrying the member's identity, role, link status, and position.

Update a team member

PATCH /v1/customers/{id}/teams/{user_id}

Changes a member's role and/or position. Supply the new role reference and, in metadata, the position.

Remove a team member

DELETE /v1/customers/{id}/teams/{user_id}

Deactivates the membership — the link is marked inactive and flagged as removed, and the member's roles are switched off. This is a reversible soft removal, unlike deleting the customer itself, so history is preserved for audit.

Resend a team invitation

POST /v1/customers/{id}/teams/{user_id}/resend

Re-sends the invitation to a member who has not yet accepted.

Verify a team invitation

GET /v1/teams/verify

Confirms an invitation token before the invitee has signed in. Reached with an API key and the token supplied as a query value.

Shareholders

Shareholders capture the ownership structure for KYB and compliance.

Add, list, view, and update shareholders

POST /v1/customers/{id}/shareholders

GET /v1/customers/{id}/shareholders

GET /v1/customers/{id}/shareholders/{shareholder_id}

PUT /v1/customers/{id}/shareholders/{shareholder_id}

PATCH /v1/customers/{id}/shareholders/{shareholder_id}

Create a shareholder together with its address and linked entity, list all shareholders of a customer, read one, replace one, or partially update one. GET, PUT, and PATCH on a shareholder ID stay scoped to the URL customer; when updates change entity_id, the target persona or organization must already be referenced by a shareholder under that same customer. PATCH preserves omitted scalar fields and merges supplied metadata keys into the stored metadata; it cannot remove existing metadata keys, so use PUT to replace metadata. Adding a shareholder returns the shareholder together with its address and entity so the caller has the complete picture in one step.

Remove a shareholder

DELETE /v1/customers/shareholders/{shareholder_id}

Permanently removes the shareholder — a hard removal, consistent with customer deletion and unlike team-member removal. Removing a shareholder that does not exist is reported as not found.

Signatories

Signatories are the people authorized to sign on the customer's behalf; each carries a signature type, a weight, and a validity period.

Add, list, and view signatories

POST /v1/customers/{id}/signatories

GET /v1/customers/{id}/signatories

GET /v1/customers/{id}/signatories/{user_id}

GET /v2/customers/signatories

Create a signatory and read them back individually or as a list. The v2 signatories listing returns a plain list and can be scoped by customer or by a supplied search; when unscoped it returns a broad list, so pass a customer scope for a specific company.

Invite, resend, and change email

POST /v1/customers/{id}/signatories/invite

POST /v1/customers/{id}/signatories/{signatory_id}/resend

PUT /v1/customers/{id}/signatories/{signatory_id}/email

Invite the customer's signatories to complete verification and signing, resend an invitation, or correct a signatory's email before the invitation is accepted.

Supporting data and documents

GET /v1/customers/{id}/signatories/crif

GET /v1/customers/{id}/signatories/invitees

POST /v1/customers/{id}/signatories/docs

Load signatory details from the external CRIF source, list who has been invited, and generate the signatory document package.

Remove a signatory

DELETE /v1/customers/signatories/{signatory_id}

Removes the signatory. The removal runs as a single transaction so related records are cleaned up together.

Verify a signatory invitation

GET /v1/signatories/verify

Confirms a signatory invitation token and returns the invitee's details. When the invitee must set a password before signing in, the response also carries the password-setup token; when they already have an active account, it does not. Reached with an API key and the token supplied as a query value.

Confirming the invitation also confirms the invitee's e-mail, and one address can hold only one confirmed credential across the platform. If the address is already confirmed on another account the call answers 409 users_m.duplicate_credential and nothing is written — not the credential, not the signatory status, not the role. Retrying cannot succeed, so the signatory has to be re-invited under the address they already hold, or the two accounts merged. The lookup that would normally reuse the existing account compares the stored user name exactly, so a different spelling of the same address reaches this point instead of being matched earlier.

Correct a signatory's e-mail

PUT /v1/customers/{id}/signatories/{signatory_id}/email

Replaces the address an invitation was sent to and re-sends it. The same uniqueness rule applies: if the new address is already confirmed on another account the call answers 409 users_m.duplicate_credential and the change is rolled back with no invitation sent.

Customer links

Links connect a customer to another record in the platform (for example an account or a case), so related items can be found from the customer.

Create, list, view, update, and remove links

POST /v1/customer-links

GET /v1/customer-links

GET /v1/customer-links/{id}

PUT /v1/customer-links/{id}

DELETE /v1/customer-links/{id}

Create a link by naming the customer, the target record, and the record type; list or read links; update one; or remove one.

Common failures and what they mean

Underlying message keys (for support triage) live in the module's localization catalogue; operators act on the business meaning above rather than the raw codes.