# Entity Onboarding Sessions
> Entity Onboarding Sessions let your customers onboard themselves by completing Increase-hosted forms. Create a session and redirect your customer to the returned URL. When they're done, they'll be redirected back to your site. This API is used for [hosted onboarding](/documentation/hosted-onboarding).

## The Entity Onboarding Session object
### Example
```json
{
  "created_at": "2020-01-31T23:59:59Z",
  "entity_id": "entity_n8y8tnk2p9339ti393yi",
  "expires_at": "2020-02-01T05:59:59+00:00",
  "id": "entity_onboarding_session_wid2ug11fsmvh3k9hymd",
  "idempotency_key": null,
  "program_id": "program_i2v2os4mwza1oetokh9i",
  "redirect_url": "https://example.com/onboarding/completed",
  "session_url": "https://onboarding.increase.com/onboarding/sessions?id=HIrdj46cXyyNqT5RDcIR38dzPqzRBgTdG84XwzOz",
  "status": "active",
  "type": "entity_onboarding_session"
}
```
### Attributes
- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Entity Onboarding Session was created.

- `entity_id` (string, nullable)
  The identifier of the Entity associated with this session, if one has been created or was provided when creating the session.

- `expires_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Entity Onboarding Session will expire.

- `id` (string)
  The Entity Onboarding Session's identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `program_id` (string)
  The identifier of the Program the Entity will be onboarded to.

- `redirect_url` (string)
  The URL to redirect to after the onboarding session is complete. Increase will include the query parameters `entity_onboarding_session_id` and `entity_id` when redirecting.

- `session_url` (string, nullable)
  The URL containing the onboarding form. You should share this link with your customer. Only present when the session is active.

- `status` (enum)
  The status of the onboarding session.
  Cases:
  * `active` (The Entity Onboarding Session is active.)
  * `expired` (The Entity Onboarding Session has expired.)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `entity_onboarding_session`.

## List Entity Onboarding Session
GET /entity_onboarding_sessions

### Example
```curl
curl \
  --url "${INCREASE_URL}/entity_onboarding_sessions" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `status.in` (array of enums, optional)
  Filter Entity Onboarding Session for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
  Cases:
  * `active` (The Entity Onboarding Session is active.)
  * `expired` (The Entity Onboarding Session has expired.)

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

### Returns a Entity Onboarding Session List object:
```json
{
  "data": [
    {
      "created_at": "2020-01-31T23:59:59Z",
      "entity_id": "entity_n8y8tnk2p9339ti393yi",
      "expires_at": "2020-02-01T05:59:59+00:00",
      "id": "entity_onboarding_session_wid2ug11fsmvh3k9hymd",
      "idempotency_key": null,
      "program_id": "program_i2v2os4mwza1oetokh9i",
      "redirect_url": "https://example.com/onboarding/completed",
      "session_url": "https://onboarding.increase.com/onboarding/sessions?id=HIrdj46cXyyNqT5RDcIR38dzPqzRBgTdG84XwzOz",
      "status": "active",
      "type": "entity_onboarding_session"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create an Entity Onboarding Session
POST /entity_onboarding_sessions

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/entity_onboarding_sessions" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "program_id": "program_i2v2os4mwza1oetokh9i",
    "redirect_url": "https://example.com/onboarding/session"
  }'
```

### Body Parameters
- `entity_id` (string, optional)
  The identifier of an existing Entity to associate with the onboarding session. If provided, the onboarding form will display any outstanding tasks required to complete the Entity's onboarding.

- `program_id` (string, required)
  The identifier of the Program the Entity will be onboarded to.

- `redirect_url` (string, required)
  The URL to redirect the customer to after they complete the onboarding form. The redirect will include `entity_onboarding_session_id` and `entity_id` query parameters.

## Retrieve an Entity Onboarding Session
GET /entity_onboarding_sessions/{entity_onboarding_session_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/entity_onboarding_sessions/entity_onboarding_session_wid2ug11fsmvh3k9hymd" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `entity_onboarding_session_id` (string, required)
  The identifier of the Entity Onboarding Session.

## Expire an Entity Onboarding Session
POST /entity_onboarding_sessions/{entity_onboarding_session_id}/expire

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/entity_onboarding_sessions/entity_onboarding_session_wid2ug11fsmvh3k9hymd/expire" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `entity_onboarding_session_id` (string, required)
  The identifier of the Entity Onboarding Session to expire.

## Sandbox: Submit an Entity Onboarding Session
POST /simulations/entity_onboarding_sessions/{entity_onboarding_session_id}/submit
> Simulates the submission of an [Entity Onboarding Session](#entity-onboarding-sessions). This session must have a `status` of `active`. After submission, the session will transition to `expired` and a new Entity will be created.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/entity_onboarding_sessions/entity_onboarding_session_wid2ug11fsmvh3k9hymd/submit" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `entity_onboarding_session_id` (string, required)
  The identifier of the Entity Onboarding Session you wish to submit.