Skip to main content

New Request Handling

Process flow

This diagram illustrates the process of receiving a new client request (account/policy opening) from a tenant via Zinsli. It shows the interactions between Zinsli and the Product Provider during the tenant onboarding process.

Implementation

Follow this step-by-step guide to implement the product opening process.
TIP: See API Specification below for Swagger docu.

Auth Setup

  1. OAuth authorization
    Obtain authorization using the Client Credentials Grant flow of OAuth 2.0.
    Follow the instructions under Setup OAuth App to create an OAuth App and get client_id and client_secret.

    warning

    The following scopes must be set for the OAuth App. rental_collateral:read rental_collateral:update

    • post: /v1/user/auth/token
    info

    For all subsequent API calls, include the following header: Authorization: Bearer <access_token>.



Get new requests

  1. Retrieve Product Opening Information
    Obtain details about tenants who have completed the Zinsli onboarding process and wish to open one of your products. You can choose between two methods to retrieve this information: Webhooks and Polling.

    Webhooks:

    Follow the instructions under Setup Webhooks to activate them. After that you can receive events which have the following schema:

    {
    collateralId: string
    state: 'tenant-onboarded'
    }

    Polling:

    Another variant is to poll the following endpoint:

    • GET: /v1/{organizationSlug}/product-provider/rental-collateral
    info

    state must have the value tenant-onboarded (this means the tenant has onboarded themselves to the collateral and sent their request for a specific product).
    collateralId contains the ID needed to get collateral data



  2. Get Tenant Onboarding Data
    Find all information about the rental deposit to be opened, including information about the landlord, tenant and property. You will find the relevant information in the following places:

    • Primary tenant email and locale: state.tenant.email and state.tenant.locale
    • All other Primary tenant information: state.product.primaryTenant
    • All secondary tenant information: state.product.secondaryTenants
    • All rental deposit information (ex. required amount): deposit
    • All rental property information (ex. address):property
    • Property owner: property.owner
    • Property manager: property.management

    (In case you need information about your own product that the tenant chose, please check under state.product.product, for example the fees under state.product.product.fees).

    warning

    Only objects with the state tenant-onboarded should be processed by the product provider. You need to track which objects with this state you are already processing. (For more information on the different states, please refer to the explanations).

    • get: /v1/product-provider/rental-collateral/{id}

Confirm tenant onboarding & activation status

Determine your product configuration

Check your product settings.

  • billing.kind for the configured payment option
  • shouldLockAfterAccountCreation for the guarantee confirmation

For more information about the different configurations, please see here.

Continue in the appropriate tab:



API Specification

Swagger spec "ZINSLI_V1_0" not found. Set the parameter "swaggerSpecName" to one of the following values: ZINSLI_V1_0