External Data API

Let an outside system, such as a vendor, an ERP or a weighbridge, work with your SmartTables over a secure API: entries, attachments, settings, approval workflows, access and folders. The same rules apply as in the app.

Overview

The vendor gets its own client ID and secret, not a PersivApps user account. It signs in to get a short-lived access token, then calls the API with it. Every call goes through the same logic the app uses: formulas, autofill, auto-numbered fields, approval workflows, notifications, automations and the audit trail all run as if a person had done it.

• Base URL: your PersivApps API address, for example https://your-host/persivapps/service. Every path below starts with <base URL>/external/v1/. A trailing slash is optional.
• Every call with sample requests and responses: the API Reference, searchable, with a downloadable Postman collection and PDF.
• Machine-readable reference: GET <base URL>/external/v1/openapi.json describes every call, for tools such as Postman.
• Earlier paths: /external/auth/login, /external/smarttables/data/save and /external/smarttables/data/<id>/update (without /v1) still work and behave the same.

What a vendor can and can't do

• Only what it has permission for. Each vendor is given permissions such as entries:read or smarttables.settings:write. Each call below lists the permission it needs; a token without it gets permission_denied.
• Only the SmartTables (or folders) its permission covers. Each permission covers all of your organization's SmartTables, chosen ones, or those in chosen folders. Anything outside returns "not found", the same as an ID that doesn't exist. Nothing in another organization is ever reachable.
• Only its own entries, by default. Updating, deleting, restoring and changing attachments work only on entries the vendor created, unless it is allowed to change any entry.
• Only these calls. The vendor's token is refused everywhere else in PersivApps, and these calls don't accept a normal user's login. The vendor can't sign in to the app; what it saves shows as created by a dedicated integration user named after it.
• Users are read only. A vendor with users:read can list users, roles and user attributes, but never create, change or disable users, or see passwords and signatures.
• Never: custom scripts, automations, changing users or passwords, organizations, or the organization's system administrator account.

GET /external/v1/me lists the vendor's permissions and the SmartTables each one covers.

Authentication

Send the client ID and secret in the body, or as HTTP Basic authentication:

POST <base URL>/external/v1/auth/login
Content-Type: application/json

{
  "client_id": "ext.acme-logistics.1a2b3c4d",
  "client_secret": "your-client-secret"
}

{
  "access_token": "pvx_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "entries:read entries:write",
  "refresh_token": "pvx_rt_..."
}

• Send the access token on every call as Authorization: Bearer <access_token>. It lasts 1 hour.
• To renew, sign in again, or exchange the refresh token at POST <base URL>/external/v1/auth/token with grant_type=refresh_token plus your client ID and secret. Each refresh token works once.
• scope (optional): a space-separated list of permissions, to get a token with fewer permissions than the vendor has. The response's scope lists what the token can do. Asking only for permissions the vendor doesn't have returns invalid_scope.
• Limits on your secret. A secret can have an expiry date and can be limited to your servers' IP addresses. If sign-in suddenly returns 401 from a new server, or after a date, ask us to update it.

Requests, responses and errors

• JSON in and out, except file uploads (multipart/form-data) and downloads.
• Field IDs: entry values are keyed by field ID, the id of each field in the SmartTable's schema (GET /external/v1/smarttables/<id>).
• Two IDs per entry: smarttable_data_entry_id identifies an entry; smarttable_data_id identifies one row (an observation) of it. Most row calls take the row ID.
• Paging: lists take page (from 1) and page_size, and return total_count and total_pages.
• Successful responses have "status": "success".

Errors come back as {"status": "error", "error": "…", "code": "…"}. Program against code; the error text may change.

Sign-in and token errors follow the OAuth 2.0 format instead: {"error": "invalid_client" | "invalid_grant" | "invalid_scope" | "unsupported_grant_type", "error_description": "…"}.

Entries

Create an entry

POST <base URL>/external/v1/smarttables/data/save
Authorization: Bearer pvx_at_...
Content-Type: application/json

{
  "smarttable_id": 61,
  "smarttable_values": { "1": "Truck MH12AB1234", "3": 12.5, "8": "Arrived" },
  "is_submit": false,
  "client_op_id": "acme-dispatch-000123"
}

{
  "status": "success",
  "message": "Saved",
  "duplicate": false,
  "smarttable_id": 61,
  "smarttable_data_id": 189862,
  "smarttable_data_entry_id": 195569,
  "observation_number": 1
}

Update an entry

PUT <base URL>/external/v1/smarttables/data/189862/update
Authorization: Bearer pvx_at_...
Content-Type: application/json

{
  "smarttable_values": { "8": "Unloaded" },
  "cleared_fields": ["3"]
}

• Send only the fields you want to change; the others keep their values.
• An empty string means "no change", not "clear". To blank a field, list its ID in cleared_fields.
• is_submit: true submits a draft. A submitted entry can be changed only if the SmartTable's settings allow it.

List entries

• page_size is 50, 100, 200 or 500 (default 100).
• search matches any field's value. sort is a field ID or created_at, updated_at, observation_number, entry_id, with dir=asc|desc. submitted=1|0 filters on submitted.
• filters is a JSON list, for example [{"column_id": "3", "operator": "equals", "value": "Arrived"}]; at most 20.
• updated_after, updated_before, created_after, created_before limit the list to a time window, as an ISO 8601 date (2026-10-01, midnight UTC) or date-time (2026-10-01T09:30:00+05:30; no offset means UTC). after includes the moment, before excludes it. To fetch only what changed since your last run, send updated_after with the time you last fetched and sort=updated_at&dir=asc.
• deleted=1 lists deleted rows instead, and needs entries:delete.
• The SmartTable's own "Show entries" setting applies: on a SmartTable set to show users only their own entries, the vendor sees only the entries it created.

Delete, restore and admin actions

• Delete is a soft delete; POST …/restore brings the row back.
• entries:admin deletes permanently (cannot be undone), unsubmits a submitted row, and releases an edit lock someone left open. These aren't limited to the vendor's own entries.

Bulk operations

• Send up to 500 row IDs as {"smarttable_data_ids": [...]}. Each ID is checked on its own: the response lists what was done and, under failed, each ID that wasn't with the reason. An ID the vendor may not use is reported as "Not found".
• Bulk delete and restore, like single ones, work only on rows the vendor created unless it may change any entry. Permanent delete and the version update (entries.bulk:admin) aren't limited to its own rows.
• Version update moves rows to the SmartTable's latest approved schema ("update": "entry"), display layout ("display") or both (default). Fields removed from the schema since a row was saved stop showing for it.
• Excel upload works on relational SmartTables only: multipart/form-data, the workbook under file (.xlsx or .xls, at most 10 MB), first row = field names. Up to 10 uploads per hour per vendor.

Attachments

• Upload with multipart/form-data, each file under the key files, up to 20 per call.
• Download: the list call returns each file's path; fetch it with GET <base URL>/external/v1/<path>.
• You can also attach files while creating or updating an entry: send that request as multipart/form-data, smarttable_values as a JSON string, and each file under attachments__<field_id>.

curl -X POST https://your-host/persivapps/service/external/v1/smarttables/data/189862/attachments/6 \
  -H "Authorization: Bearer pvx_at_..." \
  -F files=@weighbridge-slip.pdf

Comments

Comments are plain text, up to 5,000 characters. The list includes notes added in the app.

Approval status

Read-only: approvers still approve or reject in the app or from their notification. The status lists each step, who approved it and any comment; signatures are never returned. An entry whose SmartTable has no approval workflow returns "approval_enabled": false.

Attestation and eSign

• Attest a submitted row with a signature image: multipart/form-data with the file under image, or JSON {"image": "<base64>"}. PNG or JPEG, at most 1 MB.
• The attestation is recorded as signed by the vendor's integration user, not by a person, and the row's history shows it.
• eSign (Aadhaar / eMudhra) is read only: the status call returns whether a row's document was e-signed and the transaction ID. Starting an eSign needs a person's own mobile number and OTP, so it can only be done in the app.

Exports

The PDF is the entry's printed layout. Add include_attachments=false to leave attached PDFs out. Up to 30 PDFs per minute per vendor.

Many at once: POST …/bulk/pdf with {"smarttable_data_entry_ids": [...]} (at most 50) returns one zip. Entries the vendor can't read are left out and listed in the X-Skipped-Entry-Ids response header. Up to 5 zips per 5 minutes per vendor.

SmartTables and schema

• A field has the same columns as the schema builder: name, ui_smarttable_element (text, textarea, number, date, month, time, dropdown, multi_select_dropdown, radio_button, button_group, checkbox, attachment), optional, hide, allowed_data, properties and the other columns in the SharePoint column reference.
• Creating a SmartTable needs smarttables:write on all SmartTables. The new SmartTable waits for approval in the app before entries can be saved.
• Changing the schema sends the full list of fields. Keep each existing field's id; a field without an id is added. Leaving out an existing field is refused unless you send "allow_remove": true, and changing a field's type unless "allow_type_change": true, because stored values are kept by field ID and would no longer show.

{
  "name": "Dispatch Log",
  "is_relational": false,
  "fields": [
    { "name": "Truck number", "ui_smarttable_element": "text" },
    { "name": "Weight (t)", "ui_smarttable_element": "number", "optional": true }
  ]
}

Display layouts

The display layout is the printed form, as it came from the spreadsheet's display sheet: every cell with its value, style and size, and <pa_…> placeholders where entry values go. Add version=N for an older version, or include_unapproved=1 to include versions not approved yet. Layouts change only through the spreadsheet; to get a filled-in document, download the entry's PDF.

SharePoint and Google Sheets

• Refresh re-reads the SmartTable's spreadsheet, the same as Refresh in the app. Changed versions may need approval in the app. A SmartTable locked against spreadsheet sync, or built in the schema builder, returns 409.
• Create takes name, and sharepoint_url or google_sheets_url (an https link on *.sharepoint.com or docs.google.com), plus optional is_relational and observation_count. It needs both smarttables.sources:write and smarttables:write on all SmartTables, and the file must be shared with your organization's PersivApps connection.
• Up to 20 refreshes and creates per hour per vendor.

Settings

PATCH changes only the keys you send:

Linking and autofill, fonts, print orientation, who may edit submitted entries and notification buttons can only be changed in the app.

Approval workflow

{
  "enabled": true,
  "steps": [
    { "mode": "any", "approvers": [12, 15], "deadline_days": 2 },
    { "mode": "all", "approvers": [20] }
  ],
  "on_publish": {
    "notify_users": [12],
    "email_users": [30],
    "email": { "subject": "Approved", "body": "Please find the PDF attached.", "signature": "" }
  }
}

• Steps run in the order sent. mode is any (one approver is enough) or all.
• Optional: step0 (enabled, notify_on_later_steps, deadline_days), and per step notify_on_later_steps.
• The new workflow applies to entries created afterwards; entries already in progress keep the workflow they started with.
• Send {"enabled": false} to turn approvals off.

SmartTable Steps

The steps themselves come from the SmartTable's schema; this sets who is assigned to each. Send {"steps": [{"step_number": 1, "assignees": {"users": [12]}}]}. A step left out is deactivated, not deleted.

Access

• Roles are admin (SmartTable admin), user and viewer.
• Find user IDs with GET /external/v1/access/users?search=… (or the Users calls below, with users:read).
• Only active users of your organization can be given access. The organization's system administrator account, and other API clients, can't be changed.
• Entry-level access (PATCH …/data/<id>/access) overrides who can view, edit or admin one row, each as {"users": [...], "attributes": {...}} or null to go back to the SmartTable's default. It works when entry-level access is turned on.
• Entry access rules (…/entry-access) are the SmartTable-wide defaults behind the per-row ones. PUT takes "enabled" (true/false) and/or "rules": for view, edit and admin, a rule with any of users, attributes (attribute ID → allowed values), creator_only: true and match_creator_attribute (an attribute ID: same value as the row's creator), or null to clear it. Actions you leave out keep their rule. It saves a new version of the SmartTable's settings, and returns 409 if entry access control is switched off on the server.

{
  "enabled": true,
  "rules": {
    "view": { "match_creator_attribute": "5" },
    "edit": { "creator_only": true, "users": [12] },
    "admin": null
  }
}

Folders

• A SmartTable is in at most one folder: adding it to a folder takes it out of any other.
• Sharing a folder gives its users the user role on the folder's SmartTables; unsharing removes that role again.
• Creating a folder needs folders:write on all folders.

Users (read only)

• users:read is granted for the whole organization, never for chosen SmartTables.
• A user has user_id, name, username, email, role, active, mfa_enabled, attributes (each with attribute_id, name, value) and timestamps. Passwords, signatures and sign-in data are never returned.
• List filters: search (name, username or email), role, active=1|0, attribute_id with optional attribute_value. 100 per page.
• The organization's system administrator account and API clients' integration users aren't listed.
• …/users/<id>/smarttables lists the user's roles only on SmartTables the vendor's access:read covers.

History

The SmartTable history covers versions, approvals, settings changes and bulk uploads. A row's history covers saves, submits, approvals and deletes.