# Documentation for Parallel Developer Documentation Legacy – v1.x

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

## New Case Management API Availability

If you are a new partner, you should integrate with the [Case Management API](https://developer.parallelmarkets.com/docs/1.x/server/case-management-api/introduction), which provides access to your records, including identity information. You do not need to integrate with the Identity API.

If you are an existing partner using Parallel's Case Management platform, you can now use the [Case Management API](https://developer.parallelmarkets.com/docs/1.x/server/case-management-api/introduction) to fetch identity information and manage your records instead of the Identity API. See the [migration guide](https://developer.parallelmarkets.com/docs/1.x/server/case-management-api/migration-guide) for more details.

Know Your Customer (KYC) and Anti-Money Laundering (AML) rules require receiving and verifying information from potential clients. Parallel Markets simplifies this process, since we collect and validate user supplied information.

This API requires that you first receive `identity` and `profile` [scope](https://developer.parallelmarkets.com/docs/1.x/server/scopes) permissions via a valid [OAuth Access Token](https://developer.parallelmarkets.com/docs/1.x/server/access-token) for an individual or business. You will then use that token for authentication for all requests.

## Background

For individuals (natural persons), the robust information returned from our Identity API is specific to that single individual. You can use the [Request Granting Entity Identity API](https://developer.parallelmarkets.com/docs/1.x/server/identity-api/#request-oauth-granting-entity-identity) to fetch the KYC/AML Identity information for a granting entity.

For businesses, more information is provided so partners can properly evaluate not just the business entity but all of its owners (which could be businesses or individuals) and control persons.

In this example, if you request the [Granting Entity](https://developer.parallelmarkets.com/docs/1.x/server/identity-api/#request-dependency-identity-with-oauth-token) endpoint, you will get back information about the top-level business that granted `identity` access permission. The response will contain (among other KYC/AML data) a list of control persons and beneficial owners along with their `id`s. You can then use the [Dependency API](https://developer.parallelmarkets.com/docs/1.x/server/identity-api/#request-dependency-identity-with-oauth-token) to look up each control person and owner by `id`.

## Request OAuth Granting Entity Identity

Get Identity (KYC/AML) information for an individual or business whose information is accessible with the given OAuth Token. This API requires the `identity` [scope permission](https://developer.parallelmarkets.com/docs/1.x/server/scopes).

### HTTP Request

`GET https://api.parallelmarkets.com/v1/identity`

You must send an `Authorization` header with a value of `Bearer {token}`, where `{token}` is a valid [OAuth Access Token](https://developer.parallelmarkets.com/docs/1.x/server/access-token).

### Query Parameters
None

### Response Parameters

| Parameter                     | Description                                                                                                                                     |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                          | A unique identifier for the subject whose information is in the response. (ex: `VXNlcjox`)                                                    |
| `type`                        | The type of the subject whose information is in the response: `individual` or `business`                                                      |
| `identity_details`           | A [Business Identity Details](https://developer.parallelmarkets.com/docs/1.x/server/data-structures#business-identity-details) or [Individual Identity Details](https://developer.parallelmarkets.com/docs/1.x/server/data-structures#individual-identity-details) object depending on the `type` |
| `user_id`                    | A unique identifier for the person who authenticated via OAuth and consented to share the subject's 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. |
| `access_expires_at`          | A timestamp which, if not `null`, indicates a future time after which this subject's data will no longer be accessible via the provided access token.                                                        |
| `access_revoked_by`          | This will be one of: <br>- `null`: Access revocation is not scheduled. In this case, `access_expires_at` will be `null`.<br>- `subject`: The subject requested to stop sharing their data.<br>- `partner`: You requested to revoke your own access to the subject's data.<br>- `system`: Access to this subject's data was revoked by our internal systems.|

## Request Dependency Identity with OAuth Token

This API can be used to look up the Identity (KYC/AML) information for a **dependency** — a control person, individual beneficial owner, or business beneficial owner — based on `id` using a given OAuth Token.

### HTTP Request

`GET https://api.parallelmarkets.com/v1/identity/{dependency_id}`

### Query Parameters
None

### Response Parameters

## Examples Responses

### Individual

```json
{
  "id": "VXNlcjoxMDMyNg==",
  "type": "individual",
  "user_id": "VXNlcjoxMDMyNw==",
  "user_providing_for": "other-individual",
  "access_expires_at": null,
  "access_revoked_by": null,
  "identity_details": {
    "birth_date": "1970-10-24",
    "citizenship_country": "US",
    "completed_at": "2021-07-04T13:32:21Z",
    "created_by": {
      "email": "jackson@stargate.mil",
      "first_name": "Daniel",
      "last_name": "Jackson"
    },
    "domicile_location": {
      "address_one": "2 Lake Dr",
      "address_two": null,
      "city": "Silver Creek",
      "country": "US",
      "postal_code": "55380",
      "region": null,
      "state": "MN"
    },
    "email": "oneill@stargate.mil",
    "expires_at": "2022-07-04T23:59:59Z",
    "first_name": "Jonathan",
    "foreign_tax_id": null,
    "identity_files": [
      {
        "download_url": "https://files.parallelmarkets.com/download/url/front.jpg",
        "download_url_expires": 30,
        "type": "passport"
      }
    ],
    "last_name": "O'Neill",
    "marital_status": "single",
    "middle_name": "J",
    "phone": "+1 719-555-4202",
    "residence_location": {
      "address_one": "250 Vandenberg",
      "address_two": "Ste. B-016",
      "city": "Peterson AFB",
      "country": "US",
      "postal_code": "80914-3808",
      "region": null,
      "state": "CO"
    },
    "risk_monitor_matches": [],
    "us_tax_id": "333-22-4444",
    "user_session": {
      "maybe_anonymizing_proxy": false,
      "country_code": "US",
      "region": "Colorado",
      "city": "Colorado Springs"
    }
  }
}
```

### Business

```json
{
  "id": "QnVzaW5lc3M6MjI2Mg==",
  "type": "business",
  "user_id": "VXNlcjoxMDM4NA==",
  "user_providing_for": "controlled-business",
  "access_expires_at": null,
  "access_revoked_by": null,
  "identity_details": {
    "name": "Hic Sunt Leones LLC",
    "incorporation_country": "US",
    "incorporation_region": "Lagalos",
    "incorporation_state": "NC",
    "business_type": "C Corporation",
    "completed_at": "2021-06-29T13:32:21Z",
    "direct_beneficial_owners": [
      {
        "id": "QnVzaW5lc3M6MjI2NA==",
        "type": "business",
        "ownership_percent": 0.25,
        "profile": {
          "name": "Parent Company",
          "business_type": "C Corporation",
          "primary_contact": {
            "email": "me@gobl.in",
            "first_name": "Sevro",
            "last_name": "Barca"
          }
        }
      },
      {
        "id": "QnVzaW5lc3M6MjEzOQ==",
        "type": "individual",
        "ownership_percent": 0.5,
        "access_expires_at": null,
        "access_revoked_by": null,
        "profile": {
          "email": "ly@r.ia",
          "first_name": "Lyria",
          "last_name": "de Lagalos"
        }
      }
    ],
    "control_persons": [
      {
        "id": "QnVzaW5lc3M6MjEzOQ==",
        "type": "individual",
        "title": "Gamma",
        "access_expires_at": null,
        "access_revoked_by": null,
        "profile": {
          "email": "ly@r.ia",
          "first_name": "Lyria",
          "last_name": "de Lagalos"
        }
      },
      {
        "id": "QnVzQlc3M6MjEzO",
        "type": "individual",
        "title": "Mustang",
        "access_expires_at": null,
        "access_revoked_by": null,
        "profile": {
          "email": "virginada@example.com",
          "first_name": "Virgina",
          "last_name": "au Augustus"
        }
      }
    ],
    "created_by": {
      "email": "ly@r.ia",
      "first_name": "Lyria",
      "last_name": "de Lagalos"
    },
    "expires_at": "2021-09-07T15:04:15Z",
    "foreign_tax_id": "ftid_0123456789",
    "identity_files": [
      {
        "download_url": "http://localhost/file",
        "download_url_expires": 30,
        "type": "formation-document"
      }
    ],
    "primary_contact": {
      "email": "ly@r.ia",
      "first_name": "Lyria",
      "last_name": "de Lagalos"
    },
    "principal_location": {
      "address_one": "11 Merge St",
      "address_two": null,
      "city": "Durham",
      "country": "US",
      "postal_code": "27701",
      "region": null,
      "state": "NC"
    },
    "risk_monitor_matches": [],
    "type": "business",
    "us_tax_id": "333-22-4444",
    "user_session": {
      "maybe_anonymizing_proxy": false,
      "country_code": "US",
      "region": "North Carolina",
      "city": "Durham"
    }
  }
}
```

## Dependency Identity Access Expiration

A **dependency** is not guaranteed to have consented to share their information directly with you, the partner. Most often, **dependency** individuals and businesses agree to share their information with owned or controlled businesses. One or more of those businesses then may consent to share its information _and that of its owners and control persons_ with partners.