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

# Custom Integrations

---
description: >-
  Easily connect your systems with custom integrations to keep entity data 
  automatically in sync
icon: plug-circle-bolt
---

# 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.

{% content-ref url="https://app.gitbook.com/s/Esyn5VMU6e0OyGjRtKgx/api-reference" %}
[API Reference](https://app.gitbook.com/s/Esyn5VMU6e0OyGjRtKgx/api-reference)
{% endcontent-ref %}

### 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.