# Positions

## Subscribe positions

Subscribe to receive positions as they update. Returns Position.

> Subscribe positions request example



```json
{
  "positionSubscriptions":[ {
      "clientReferenceId":"Pos987",
      "customerId":"user1",
      "customerOrg":"CSDK1",
      "fromValueDate":"05/04/2020",
      "toValueDate":"7/17/2030",
      "pnlCurrency":"USD",
      "positionLevel":"ORG",
      "inclCustomerPositions":"true"
    }
  ]
}
```

> Request body


| Attribute  | Description |
|  --- | --- |
| `clientReferenceId` | **string: (required)** Your ID for the position subscription. |
| `customerId` | **string: (required)** User ID subscribing to positions. |
| `customerOrg` | **string: (required)** Organization ID subscribing to positions. |
| `fromValueDate` | **string: (required)** The start date (inclusive) of the position date range in the format `MM/dd/yyyy`. |
| `toValueDate` | **string: (required)** The end date (inclusive) of the position date range in the format `MM/dd/yyyy`. |
| `pnlCurrency` | **string: (required)** The P&L reporting currency. |
| `positionLevel` | **string: (required)** Positions calculated by the entity that took the position: `ORG`=Your organization. `USER`=Your users. `CPTYORG`=Your counterparty organizations. |
| `inclCustomerPositions` | **boolean: (required)** `true`=Include customer positions in returned positions. `false`=Return only positions take by your organization. |


> Subscribe positions response example



```json
{ "positionSubscriptionResponses":[ {
    "request":{
      "clientReferenceId":"html",
      "customerId":"user1",
      "customerOrg":"CSDK1",
      "fromValueDate":"05/04/2020",
      "toValueDate":"7/17/2030",
      "pnlCurrency":"USD",
      "positionLevel":"ORG",
      "inclCustomerPositions":"true"
      },
      "positionRequestId":"1079782850",
      "status":"success"
    }
  ]
}
```

> Response body


| Attribute  | Description |
|  --- | --- |
| `clientReferenceId` | **string:** Your ID for the position subscription. |
| `customerId` | **string:** User ID subscribing to positions. |
| `customerOrg` | **string:** Organization ID subscribing to positions. |
| `fromValueDate` | **string:** The start date (inclusive) of the position date range in the format `MM/dd/yyyy`. |
| `toValueDate` | **string:** The end date (inclusive) of the position date range in the format `MM/dd/yyyy`. |
| `pnlCurrency` | **string:** The P&L reporting currency. |
| `positionLevel` | **string:** Positions calculated by the entity that took the position: `ORG`=Your organization. `USER`=Your users. `CPTYORG`=Your counterparty organizations. |
| `inclCustomerPositions` | **boolean:** `true`=Include customer positions in returned positions. `false`=Return only positions take by your organization. |
| `positionRequestId` | **string:** The Integral API ID for your position subscription request. |
| `status` | **string:** The status of your request. |


> Position example



```json
{ "position":{
    "side":"Short",
    "symbol":"USD/CHF",
    "level":"ORG",
    "levelValue":"CSDK1",
    "netOpenBase":15000000.00,
    "netOpenterm":12906962.70,
    "rate":0.8604642,
    "realizedPnL":0.00,
    "unrealizedPnL":(1,716,667.89),
    "pnlCurrency":"USD",
    "requestId":"1079782850"
  }
}
```

> Returns


| Attribute  | Description |
|  --- | --- |
| `side` | **string:** Long or short. |
| `symbol` | **string:** Base and term currency separated by a slash "/" (for example `EUR/USD`). |
| `valuedate` | **string:** The value date of the trades that make up the position. |
| `level` | **string:** The level of the position calculation:USER: For an individual user.ORG: For an organization. |
| `levelValue` | **string:** The ID of either the user or organization based on the value of `level`. |
| `netOpenBase` | **double:** Net open amount in base currency. |
| `netOpenterm` | **double:** Net open amount in term currency. |
| `rate` | **double:** The weighted average buy or sell rate of the current position. |
| `realizedPnL` | **double:** The profit or loss in the base currency determined by taking all trades(or portions thereof) that are closed and computing the profit for each pair of opposing buy/sell trades. |
| `unrealizedPnL` | **double:** The profit or loss in the base currency determined by taking the position's currency pair rate against the current market rate at the position amount. Essentially, the unrealized P/L is the profit or loss if the position was closed at the current close rate. |
| `pnlCurrency` | **string:** The P&L reporting currency. |
| `children` | **list:** List of child positions. |


## Unsubscribe positions

Unsubscribe from position updates.

> Unsubscribe positions request example



```json
{ "positionUnsubscriptions":
  [ { "positionRequestId":"1242460608"
    }
  ]
}
```

> Request body


| Attribute  | Description |
|  --- | --- |
| `positionRequestId` | **string: (required)** The `positionRequestId` from the `positionSubscriptionResponses` message. |


> Unsubscribe positions response example



```json
{ "positionUnsubscriptionResponses":
  [ { "request":
      { "positionRequestId": "1242460608"
      },
      "status":"success"
     }
  ]
}
```

> Response body


| Attribute  | Description |
|  --- | --- |
| `positionRequestId` | **string: (required)** The `positionRequestId` from your unsubscribe response. |
| `status` | **string:** The status of your request. |