Hosted Onboarding

Introduction

Increase provides a hosted onboarding flow that allows your customers to submit their business information directly to Increase. This creates an Entity in your Increase environment without requiring you to build custom onboarding forms or handle sensitive information like tax IDs.

The flow works as follows:

1. You create an Entity Onboarding Session via the API, specifying a redirect URL.
2. You send your customer to the session_url returned in the response.
3. Your customer completes the onboarding form on Increase’s hosted page.
4. After submission, the customer is redirected back to your redirect_url with the session and entity IDs as query parameters.

Creating an onboarding session

To start the onboarding flow, create an Entity Onboarding Session using the Create an Entity Onboarding Session endpoint.

curl -X POST \
  --url "https://api.increase.com/entity_onboarding_sessions" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_url": "https://example.com/onboarding/completed",
    "program_id": "program_abc123def"
  }'

{
  "id": "entity_onboarding_session_jjk2k3j4k4j2k3j4k2j",
  "type": "entity_onboarding_session",
  "status": "active",
  "session_url": "https://dashboard.increase.com/onboarding/sessions?id=kzd5dfkzd5dfkzd5dfkzd5df",
  "redirect_url": "https://example.com/onboarding/completed",
  "expires_at": "2024-01-01T06:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "program_id": "program_abc123def"
}

The response includes a session_url that you should redirect your customer to. Sessions eventually expire.

Onboarding an existing entity

If your customer has already created an Entity and they need to provide additional information or documents, you can pass the entity_id parameter when creating the session. The hosted form will display any outstanding tasks required to complete the entity’s onboarding.

curl -X POST \
  --url "https://api.increase.com/entity_onboarding_sessions" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "entity_n8y8tnk2p9339ti393yi",
    "redirect_url": "https://example.com/onboarding/completed",
    "program_id": "program_abc123def"
  }'

Handling the redirect

After the customer completes the onboarding form, they are redirected to your redirect_url. The redirect includes query parameters with the session and entity information:

https://example.com/onboarding/completed?entity_onboarding_session_id=entity_onboarding_session_jjk2k3j4k4j2k3j4k2j&entity_id=entity_n8y8tnk2p9339ti393yi

You can use the entity_id to retrieve the newly created Entity and proceed with creating accounts or other resources.

You should also monitor the entity.created webhook for new Entities. If the user fails to be redirected to your webpage, you’ll still be able to access the new Entity.

Session status

An Entity Onboarding Session can be in one of the following statuses:

If a session expires before the customer completes onboarding, you can create a new session and redirect them again.

Sandbox

In the sandbox environment, you can simulate a customer completing the onboarding form using the Simulate Entity Onboarding Session Submission endpoint.

curl -X POST \
  --url "https://sandbox.increase.com/simulations/entity_onboarding_sessions/${entity_onboarding_session_id}/submit" \
  -H "Authorization: Bearer ${INCREASE_SANDBOX_API_KEY}"

This creates a test Entity and associates it with the session, allowing you to test your redirect handling logic without having to complete the webform each time.