Source: https://sprinto-test.docs-staging.pageloop.ai/settings/custom-integrations

# Custom Integrations

Custom Integrations allow you to seamlessly send data from your third-party systems—or any data you maintain—directly into Sprinto. This data can then be used as evidence for compliance and audits.

This guide explains how **sessions** work within the Sprinto Custom Integration Entities Sync API, how to use them effectively, and how Sprinto processes and manages your data throughout the integration.

[API Reference](/api-reference/sprinto-developer-api)

### What are sessions?

A **session** groups a burst of batched uploads (pages) into one logical sync. You start a session, push pages of `entities`, then **close** the session to `apply` all accepted data. If you `discard`, nothing is applied. If you **do nothing**, the session **expires** after inactivity and the data is retained temporarily but is not applied.

### Lifecycle & States

```mermaid

stateDiagram-v2
    [*] --> active

    active --> processing: close(apply)
    processing --> processed: success

    active --> cancelled: close(discard)
    active --> expired: inactivity timeout
    expired --> processed: apply

```

```
[active] --close(apply)--> [processing] --success--> [processed]  
   |
   +--close(discard)--> [cancelled]
   |
   +--inactivity timeout--> [expired] --apply--> (processed)
```

#### **State meanings**

- `active` — Accepting pages (`entities` batches) via **POST /entities**.
- `processing` — Sprinto is applying staged pages to internal models.
- `processed` — All staged data applied successfully.
- `cancelled` — Discarded everything; no changes applied.
- `expired` — Inactivity timeout hit; Sprinto will not process that data but will retain it temporarily.

> **Timeout:** Default **60 minutes** since the last request on the session.

### Batching, pagination & sizing

- **Recommended page size:** up to **100** items total across all entity types per call.
- **Max request size:** e.g., **5 MB** (compressed allowed). Exceeding returns **413 Payload Too Large**.
- **Ordering:** Pages are applied in the order they were accepted. Within a page, ordering is not guaranteed across entity types.

### Concurrency rules

- **One active session per integration** (default). Attempting to start a new session while one is `active` returns **409 Conflict**. You can start another after closing/cancelling/expiry.
- Multiple **read** calls (`GET status`) are fine at any time.

### Validation & anomalies

- Page-level validation runs on receipt. If **any** record in a page is invalid, the **entire page** is rejected with **400** and structured errors.
- Sprinto records **anomalies** for failed pages (visible internally; surfaced via activity logs). If you still **complete**, Sprinto applies only **accepted** pages.

### Best practices

- Keep pages ≤ **100** items and under size limits; compress if large.
- Implement exponential backoff on **429** (respect `Retry-After`).
- Track your own `page_hint`/correlation keys inside payloads for easier debugging.

## FAQs

**Q: Can I push different entity types in the same page?**\
Yes. The `entities` object is a map; each key is an array for that type.

**Q: How do I resume after a validation error?**\
Fix the failing records and re-send the **same page**.

**Q: Can multiple sessions run concurrently for one custom integration?**\
Only one `active` session per integration.