PersivX Data API

Fetch data from any datasource connected to PersivX through one standard endpoint.

Whether the data lives in an external relational database, a data lake, or was imported into PersivX, the Data API provides a single endpoint for fetching it in the format you want.

There are two steps:

1. Authenticate using OAuth 2.0
2. Consume data using the Data API

🔐 Authentication

All Data API endpoints require authentication with OAuth 2.0. Your application must obtain a valid access token and include it in the request header.

Endpoint

POST https://app.persivx.com/api/o/token/

Headers

Content-Type: application/x-www-form-urlencoded

Body

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Response

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

📥 The Data API

Fetches data from any datasource connected to PersivX. Each datasource has a unique id, available in the PersivX Report Designer UI.

Endpoint

POST https://app.persivx.com/api/queryDatasource/

Request Headers

Authorization: Bearer your-access-token

Request Body

{
  "dataSourceId": PERSIVX_DATASOURCE_ID,
  "query": "SELECT client_name, SUM(bill_total) as sale_total FROM sales_summary WHERE region = 'West'",
  "responseFormat": "JSON"
}

Supported response formats are JSON, XML, CSV, and PARQUET. We're always looking to expand this list — if the format you need isn't here, contact info@persivx.com and we'll work with you on it.

Response

{
  "requestProcessed": true,
  "data": [
    {
      "client_name": "Client A",
      "sale_total": 1302977.08
    },
    {
      "client_name": "Client B",
      "sale_total": 16669.00
    },
    {
      "client_name": "Client C",
      "sale_total": 169970.25
    }
  ]
}

🔒 Security

• All endpoints are HTTPS-only.
• OAuth 2.0 tokens are short-lived and scoped per client.
• API access is restricted by IP and/or domain — ask your admin to whitelist yours.

Rate Limits and Query Timeouts

✅ Best Practices

• Refresh your token when the expires_in time elapses.
• Avoid queries that perform full table scans unless you need them.
• Use pagination — limit and offset — for large datasets.
• When a query returns more than 100,000 rows, PARQUET is the recommended response format.

⚙️ Query Generation with PersivX

The request specifies which columns you need and which filters to apply. PersivX handles the rest, generating optimized queries and returning results based on:

• Known schema relationships — foreign keys, primary keys, and relationships defined at the PersivX layer
• Available indexes
• Large dataset optimizations
• Cross-database querying and merging

This gives external applications a complete data abstraction layer, so they can focus on their workflows while PersivX does the data-fetching heavy lifting.

📞 Support

Need help integrating the API? Contact info@persivx.com for technical guidance, access credentials on a PersivX instance, or enterprise onboarding.