> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augustus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Sessions

> The Data Session object and its endpoints

## Data Session Object

The Data Session object represents a session for connecting to financial institutions and retrieving account data. It allows you to request access to a user's accounts and permissions, and to retrieve the data for those accounts.

### Properties

<ResponseField name="id" type="string" required>
  Unique identifier for the session
</ResponseField>

<ResponseField name="permissions" type="array" required>
  List of permissions requested for this session: - `accounts` - Access to
  account data - `transactions` - Access to transaction data - `balances` -
  Access to balance data - `holders` - Access to account holder data
</ResponseField>

<ResponseField name="referenceId" type="string">
  Your unique identifier for this session
</ResponseField>

<ResponseField name="metadata" type="object">
  Key-value pairs that can be used to store additional information about the
  session
</ResponseField>

<ResponseField name="locale" type="string">
  The language to display the interface in (e.g., 'en')
</ResponseField>

<ResponseField name="market" type="string">
  The market where the session is created (e.g., 'de')
</ResponseField>

<ResponseField name="successCallbackUrl" type="string">
  The URL to redirect to after the session is completed
</ResponseField>

<ResponseField name="errorCallbackUrl" type="string">
  The URL to redirect to after the session fails
</ResponseField>

<ResponseField name="status" type="enum" required>
  The status of the session: - `open` - Session is currently active -
  `closed` - Session completed successfully - `expired` - Session has expired
</ResponseField>

<ResponseField name="expiresAt" type="timestamp" required>
  The time at which the session will expire
</ResponseField>

<ResponseField name="createdAt" type="timestamp" required>
  Time at which the session was created
</ResponseField>

## Endpoints

### Create Session

Creates a new data session for connecting to financial institutions.

```json theme={null}
POST /api/services/data/session/create
```

**Request**

<ParamField query="referenceId" type="string">
  Your unique identifier for this session
</ParamField>

<ParamField query="metadata" type="object">
  Key-value pairs that can be used to store additional information about the
  session
</ParamField>

<ParamField query="locale" type="string">
  The language to display the interface in (e.g., 'en')
</ParamField>

<ParamField query="market" type="string">
  The market where the session is created (e.g., 'de')
</ParamField>

<ParamField query="successCallbackUrl" type="string">
  The URL to redirect to after the session is completed
</ParamField>

<ParamField query="errorCallbackUrl" type="string">
  The URL to redirect to after the session fails
</ParamField>

```json Response theme={null}
{
  "id": "681887166e5e01e4bb78849e",
  "referenceId": "your-unique-id",
  "metadata": {
    "merchant-id": "1234567890",
    "random-key": "random-value"
  },
  "locale": "en",
  "market": "de",
  "successCallbackUrl": "https://your-app.com/callback",
  "errorCallbackUrl": "https://your-app.com/callback",
  "status": "open",
  "expiresAt": "2024-01-27T11:00:00Z",
  "createdAt": "2024-01-27T10:00:00Z"
}
```

### Retrieve Session

Retrieves a data session by its ID.

```json theme={null}
POST /api/service/data/session/details
```

**Request**

<ParamField query="id" type="string" required>
  The ID of the session to retrieve
</ParamField>

```json Response theme={null}
{
  "id": "ds_12345",
  "referenceId": "your-unique-id",
  "metadata": {
    "merchant-id": "1234567890",
    "random-key": "random-value"
  },
  "successCallbackUrl": "https://your-app.com/callback",
  "errorCallbackUrl": "https://your-app.com/callback",
  "status": "completed",
  "accounts": ["acc_12345", "acc_12346"],
  "expiresAt": "2024-01-27T11:00:00Z",
  "createdAt": "2024-01-27T10:00:00Z"
}
```