Handoff API | Parallel Developer Documentation

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 (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 or Login function in the 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.

Query Parameters

Response Parameters

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

Examples

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

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):

{
  "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:

{
  "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"
}