This is documentation for Parallel Developer Documentation **Legacy – v1.x**, which is no longer actively maintained.

For up-to-date documentation, see the **[latest version](https://developer.parallelmarkets.com/docs/server)** (Current – v2.x).

Version: Legacy – v1.x

## When a Parallel flow is initiated
When a Parallel flow is initiated, the user doesn't return to a partner's website until _after_ they complete all required steps. In some limited cases, users decide to come back later to complete a flow, in which case they would not return to your site. In these cases, if you'd like to check on the status of the handoff, we provide the concept of a "Handoff ID" and "Handoff API".

When initiating a Parallel flow (via the [Server Authorization URL](https://developer.parallelmarkets.com/docs/1.x/server/access-token) or [Login function in the JavaScript SDK](https://developer.parallelmarkets.com/docs/1.x/javascript/sdk)), you can provide a custom `handoff_id` value that represents either the user (or business they represent) or user session. You can then:

1. Make requests to the Handoff API at any point to see if permissions were granted and which entity was selected based on the `handoff_id` you provided
2. Based on the selected entity in the Handoff API, you can make calls to the Identity / Accreditation / Blockchain APIs to see submitted information, if any

## Things to Note

There are a few things to note about this API.

First, we strongly recommend that partners also provide the parameters with the `expected_` prefix so that we can pre-fill (or even pre-select in some cases) the expected user or business. This way, the entity you're expecting to be associated with a `handoff_id` will be communicated as the expected choice for the user.

Second, we strongly recommend that partners use an opaque, universally unique identifier (UUID) as the `handoff_id`. It is possible for technically savvy users to inspect the handoff and see (or potentially modify) the `handoff_id` in the handoff.

Third, we provide information in real time as the user may be going through a flow. It's possible the user could go back and select a different entity to share, in which case the information returned from the API for the same `handoff_id` could change.

Finally, we recommend that if you want to call this API with a `handoff_id` that that you call it shortly after the user has been handed off. We only store handoff information for the last 7 days, so any requests about handoffs that occurred prior to that will result in a `404 Not Found`.

## HTTP Request with API Key

`GET https://api.parallelmarkets.com/v1/handoff?id={handoff_id}`

You must send an `Authorization` header with a value of `Bearer {apiKey}`, where `{apiKey}` is a valid [API Key](https://developer.parallelmarkets.com/docs/1.x/server/api-keys).

### Query Parameters

| Parameter | Description |
| --- | --- |
| `id` | The `handoff_id` value you previously provided when initiating a Parallel flow (via the [Server Authorization URL](https://developer.parallelmarkets.com/docs/1.x/server/access-token) or [Login function in the JavaScript SDK](https://developer.parallelmarkets.com/docs/1.x/javascript/sdk)) |

### Response Parameters

The response fields refer to the subject — the individual or business whose information is being shared.

| Parameter | Description |
| --- | --- |
| `id` | A unique identifier for the subject |
| `type` | The entity type of the subject, either `"individual"` or `"business"` |
| `user_id` | A unique identifier for the individual who authenticated. If `user_providing_for` is `"self"`, this will be the same as `id` (otherwise, this will be an identifier for the user providing information) |
| `user_providing_for` | This will be one of: <br>- `"self"`: The user has authenticated as themselves and is sharing their own information<br>- `"controlled-business"`: The user has authenticated as a business and is sharing that business' information<br>- `"other-individual"`: The user has authenticated on behalf of another person and is sharing that person's information (this option is only possible with the [`identity` scope](https://developer.parallelmarkets.com/docs/1.x/server/scopes)) |
| `scopes` | The [scopes](https://developer.parallelmarkets.com/docs/1.x/server/scopes) the user consented to share |
| `subject_selected_at` | Timestamp of when the user selected which entity they wanted to share (in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format) |
| `handoff_id` | The value of the `handoff_id` that was searched |
| `client_id` | The `client_id` of the OAuth Client used to initiate the flow |

### Examples

Get the selected user/business for a specific `handoff_id` of `885c34ce-e9d9-49d6-a703-8c0909add2b3`.

```shell
curl https://api.parallelmarkets.com/v1/handoff/885c34ce-e9d9-49d6-a703-8c0909add2b3 \
  -H 'Authorization: Bearer {apiKey}'
```

The above command returns JSON structured like this (for an individual):

```json
{
  "id": "VXNlcjox",
  "type": "individual",
  "user_id": "VXNlcjox",
  "user_providing_for": "self",
  "scopes": "accreditation_status profile",
  "subject_selected_at": "2021-06-29T13:32:21Z",
  "handoff_id": "885c34ce-e9d9-49d6-a703-8c0909add2b3",
  "client_id": "xjpoja00923n4qasd"
}
```

Here's an example of the details for a business:

```json
{
  "id": "Xxn203ty",
  "type": "business",
  "user_id": "VXNlcjox",
  "user_providing_for": "controlled-business",
  "scopes": "accreditation_status profile",
  "subject_selected_at": "2021-06-29T13:32:21Z",
  "handoff_id": "885c34ce-e9d9-49d6-a703-8c0909add2b3",
  "client_id": "xjpoja00923n4qasd"
}
```