# 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="/pages/4FU0qmb5Sen3HnvFU2nY" %}
[API References](/api-references/sprinto-developer-api.md)
{% 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/diagram content="
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sprinto.com/settings/custom-integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.