# Hosted onboarding

Increase provides a hosted onboarding flow that allows your customers to submit their business information directly to Increase. This creates an [Entity](/documentation/api/entities#entities) 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](/documentation/api/entity-onboarding-sessions#entity-onboarding-sessions) 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](/documentation/api/entity-onboarding-sessions#create-an-entity-onboarding-session) endpoint.

```curl
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"
  }'
```

```json
{
  "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](/documentation/api/entities#entities) 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
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_0011
  &entity_id=entity_n8y8tnk2p9339ti393yi
```

You can use the `entity_id` to retrieve the newly created [Entity](/documentation/api/entities#entities) 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:

| Status    | Description                                                              |
| --------- | ------------------------------------------------------------------------ |
| `active`  | The session is active and the customer can complete the onboarding form. |
| `expired` | The session has expired. Sessions eventually expire.                     |

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

Validations don't run automatically on Entities created in Sandbox, so by default, there won't be any outstanding tasks required to complete the Entity's onboarding. To see the types of problems your customers might come across, you can [simulate an issue](/documentation/entity-validation#sandbox).