1. Overview
Prudent's distributors offer Artham's advisory strategies to their clients inside a webview in the Prudent app. This document lists the APIs between Artham and Prudent.
How It Works
- Artham APIs (A1, A2) — Artham hosts them, Prudent calls them.
- Prudent APIs (B1, B2) — Prudent builds them to this document, Artham calls them.
- Both directions use the same API key + HMAC signature (Section 2) and the same response format (Section 3).
API Summary
| # | Method | Endpoint | Purpose | Hosted by |
| A1 | POST | /api/v1/partner/webview/link | Send distributor and/or client details; returns the URL that opens Artham in the webview | Artham |
| A2 | GET | /api/v1/broker/strategy-holdings | Daily strategy holdings file for the BOD | Artham |
| B1 | GET | /api/v1/clients/{clientCode} | Client KYC and bank details, after DPDP consent | Prudent |
| B2 | POST | /api/v1/clients/{clientCode}/limit-open | Client funds check | Prudent |
Base URLs
Hosted by Artham (A1, A2)
Production: https://api.artham.co
Sandbox: https://distributor-api.artham.co
Hosted by Prudent (B1, B2)
Production: To be confirmed by Prudent
Sandbox: To be confirmed by Prudent
All traffic is HTTPS over TLS 1.2+, in both directions.
2. Authentication
Every request carries two headers. Prudent sends them on A1 and A2; Artham sends them on B1 and B2.
| Header | Description | Example |
X-Api-Key | Static API key issued by Artham to Prudent | artham_live_k8Fj2mNp... |
X-Signature | HMAC-SHA256 of the request, computed with the shared secret | a1b2c3d4... (64 hex chars) |
Credential Setup
- Artham issues one API Key and one Shared Secret to Prudent, separately for Sandbox and Production.
- The same pair is used in both directions — to sign your calls to Artham and to verify Artham's calls to you.
- Keep the secret on your server, never in the mobile app.
Signature Computation
message = "{HTTP_METHOD}\n{path}\n{body}"
signature = HMAC-SHA256(key: SHARED_SECRET, message: message)
→ output as lowercase hex string
| Component | Description | Example |
HTTP_METHOD | Uppercase HTTP method | GET / POST |
path | Request path — no host, no query string | /api/v1/clients/PL889900 |
body | Raw JSON body exactly as sent. Empty string "" for GET. | {"role":"DISTRIBUTOR",...} |
Verifying: recompute the signature with the shared secret and compare it in constant time. Reject with
401 if the key or signature does not match. Code samples:
Broker Integration API, Section 7.
Authentication Errors
| HTTP | error.code | When |
401 | AUTH_REQUIRED | X-Api-Key or X-Signature missing |
401 | AUTH_TOKEN_INVALID | Unknown API key, or signature does not match |
3. Error Handling
Response Envelope
All JSON responses, in both directions, use this structure.
Success
{
"success": true,
"data": { ... },
"error": null
}
Error
{
"success": false,
"data": null,
"error": {
"code": "CLIENT_NOT_FOUND",
"message": "No client found with code PL889900."
}
}
HTTP Status Codes
| Status | When to Use |
200 | Success |
400 | Invalid or missing request fields |
401 | Invalid API key or signature |
404 | Client or distributor not found |
422 | Business rule violation (e.g. insufficient funds) |
500 | Internal server error |
Error Codes
| Code | Description |
INVALID_REQUEST | Missing or malformed request parameters |
CLIENT_NOT_FOUND | The clientCode does not exist |
CLIENT_INACTIVE | Client account is deactivated or suspended |
DISTRIBUTOR_REQUIRED | A new client was sent without its distributor |
CLIENT_DISTRIBUTOR_MISMATCH | The client is mapped to a different distributor |
DISTRIBUTOR_NOT_FOUND | The distributorCode is not on Artham |
INSUFFICIENT_LIMIT | Client does not have enough funds |
INTERNAL_ERROR | Unexpected server error |
4. API A1 — Onboard User & Webview Link Required
Prudent calls this when a user taps the Artham icon, and opens the returned URL in the webview. Each request sends the distributor's details, the client's details, or both. Artham stores or updates them, signs the user in and handles the rest of the flow.
Endpoint & Method
| Item | Value |
| Method | POST |
| Path | /api/v1/partner/webview/link |
| Hosted by | Artham |
| Authentication | X-Api-Key + X-Signature — see Section 2 |
| Called from | Prudent's backend, not the app |
Request Body
{
"role": "DISTRIBUTOR",
"distributor": {
"code": "DST1023",
"name": "Amit Shah",
"emailAddress": "amit@example.com"
},
"client": {
"code": "PL889900",
"name": "Rajesh Kumar",
"emailAddress": "rajesh@example.com",
"mobileNumber": "9876543210"
}
}
Request Fields
| Key | Type | Required | Description |
role | string | Yes | Who is opening Artham: "DISTRIBUTOR" or "CLIENT" |
distributor | object | Conditional | Distributor details. Required when role is "DISTRIBUTOR". |
distributor.code | string | Yes | Distributor's code at Prudent |
distributor.name | string | Yes | Distributor's name — shown on the dashboard and in client consent messages |
distributor.emailAddress | string | Yes | Distributor's email address |
client | object | Conditional | Client details. Required when role is "CLIENT". |
client.code | string | Yes | Client code (UCC) |
client.name | string | Yes | Client's full name |
client.emailAddress | string | Yes | Client's registered email address |
client.mobileNumber | string | Yes | Client's registered mobile number (10 digits) — used for the DPDP consent OTP |
Name and contact details only. No PAN, date of birth or bank details in this request — Artham fetches those from
API B1 after the client gives DPDP consent.
Response — 200 OK
{
"success": true,
"data": {
"url": "https://invest.artham.co/dashboard?t=eyJhbGciOi...",
"expiresAt": "2026-11-02T10:35:00+05:30",
"ttlSeconds": 300
},
"error": null
}
Response Fields
| Field | Type | Description |
url | string | Open in the webview without modifying it |
expiresAt | string | Expiry time, ISO 8601 with IST offset |
ttlSeconds | integer | Seconds until expiry (300 = 5 minutes) |
The link works once and expires in 5 minutes. Request it when the user taps, open it immediately, and never log or share it.
Error Responses
| HTTP | error.code | When |
400 | INVALID_REQUEST | role missing or invalid, the object for that role not sent, or a required field missing |
422 | DISTRIBUTOR_REQUIRED | A new client sent without its distributor |
422 | CLIENT_DISTRIBUTOR_MISMATCH | The client is already mapped to a different distributor |
5. API A2 — Strategy Holdings File Required
Prudent downloads this CSV file once a day before its BOD. It lists the shares each client holds through Artham, per strategy. Shares only — no cash.
Endpoint & Method
| Item | Value |
| Method | GET |
| Path | /api/v1/broker/strategy-holdings |
| Hosted by | Artham |
| Authentication | X-Api-Key + X-Signature — see Section 2 |
| Response | CSV file (strategy_holdings_YYYYMMDD.csv) |
Query Parameters
| Parameter | Type | Required | Description |
date | string | No | YYYY-MM-DD. Default: today. Files are kept for 90 days. |
Response — 200 OK
clientCode,strategyId,isin,symbol,exchange,quantity
PL889900,ARTMUSE00001,INE002A01018,RELIANCE,NSE,25.0000
PL889900,ARTMUSE00001,INE467B01029,TCS,NSE,8.0000
PL445566,ARTQUAL00002,INE009A01021,INFY,NSE,40.0000
Response Headers
| Header | Description |
X-As-Of | Date the file belongs to |
X-Row-Count | Number of data rows |
X-Checksum-SHA256 | SHA-256 of the file. If rows or checksum don't match, download again. |
File Columns
| Column | Type | Description |
clientCode | string | Client code |
strategyId | string | 12-character Artham strategy ID |
isin | string | 12-character ISIN |
symbol | string | NSE symbol, or BSE scrip code when exchange is BSE |
exchange | string | NSE or BSE |
quantity | decimal | Quantity held, 4 decimal places |
Full snapshot. One row per client × strategy × scrip, corporate actions applied. Replace your stored data with each file.
Error Responses
| HTTP | error.code | When |
404 | FILE_NOT_FOUND | No file for that date |
409 | FILE_NOT_READY | Today's file is not ready yet — retry after a few minutes |
6. API B1 — Client KYC Details Required
Artham calls this after the client gives DPDP consent, to pre-fill onboarding. The data is used for the agreement, mandate and invoices.
Endpoint & Method
| Item | Value |
| Method | GET |
| Path | /api/v1/clients/{clientCode} |
| Hosted by | Prudent |
| Authentication | X-Api-Key + X-Signature — see Section 2 |
Path Parameters
| Parameter | Type | Description |
clientCode | string | Client code |
Response — 200 OK
{
"success": true,
"data": {
"clientCode": "PL889900",
"rmCode": "DST1023",
"name": "Rajesh Kumar",
"pan": "ABCDE1234F",
"dateOfBirth": "1990-05-15",
"address1": "123 MG Road",
"address2": "Andheri West",
"address3": "",
"city": "Mumbai",
"state": "Maharashtra",
"pinCode": "400058",
"emailAddress": "rajesh@example.com",
"mobileNumber": "9876543210",
"accountNo": "1234567890",
"ifscCode": "HDFC0001234",
"accountType": "S",
"clientTypeCode": 1,
"isNRI": false,
"isPoliticallyExposedPerson": false
},
"error": null
}
Response Fields
| Field | Type | Required | Description |
clientCode | string | Yes | Client code |
rmCode | string | Yes | Client's distributor code |
name | string | Yes | Full name as per KYC |
pan | string | Yes | PAN (10 characters) |
dateOfBirth | string | Yes | Date of birth, YYYY-MM-DD |
address1 | string | No | Address line 1 |
address2 | string | No | Address line 2 |
address3 | string | No | Address line 3 |
city | string | No | City |
state | string | No | State |
pinCode | string | No | PIN code (6 digits) |
emailAddress | string | Yes | Registered email address |
mobileNumber | string | Yes | Registered mobile number (10 digits) |
accountNo | string | Yes | Account number of the client's active / default bank account |
ifscCode | string | Yes | IFSC code (11 characters) |
accountType | string | Yes | "S" Savings, "C" Current, "O" Other |
clientTypeCode | integer | Yes | Client type, e.g. 1 Individual, 6 HUF — full list in Broker Integration API, API 1 |
isNRI | boolean | Yes | true if the client is a Non-Resident Indian |
isPoliticallyExposedPerson | boolean | Yes | true if the client is a Politically Exposed Person |
Bank account: send only the account marked active / default at Prudent. The client's mandate is registered on this account only.
Error Responses
| HTTP | Error Code | When |
404 | CLIENT_NOT_FOUND | No client exists with this clientCode |
422 | CLIENT_INACTIVE | Client account is deactivated or suspended |
7. API B2 — Funds Check Required
Artham calls this before sending an investment consent and before a rebalance, to check the client has enough funds in their Prudent account.
Endpoint & Method
| Item | Value |
| Method | POST |
| Path | /api/v1/clients/{clientCode}/limit-open |
| Hosted by | Prudent |
| Authentication | X-Api-Key + X-Signature — see Section 2 |
Request Body
{
"subAccountCode": null,
"amount": 50000,
"segment": "EQUITY",
"purpose": "INVEST"
}
Request Fields
| Key | Type | Required | Description |
amount | number | Yes | Amount needed in rupees. 0 for REBALANCE. |
purpose | string | Yes | "INVEST" or "REBALANCE" — see formula below |
segment | string | Yes | Always "EQUITY" |
subAccountCode | string | No | Always null |
Available funds — calculated by Prudent:
purpose | Available |
INVEST | cash_ledger − margin_utilised |
REBALANCE | cash_ledger + CFS − margin_utilised |
Response — 200 OK (sufficient)
{
"success": true,
"data": {
"sufficient": true,
"availableLimit": 82500.50
},
"error": null
}
Response — 422 (insufficient)
{
"success": false,
"data": {
"sufficient": false,
"availableLimit": 12000.00
},
"error": {
"code": "INSUFFICIENT_LIMIT",
"message": "Available funds are below the requested amount."
}
}
Response Fields
| Field | Type | Description |
sufficient | boolean | true if available funds ≥ amount |
availableLimit | number | Available funds in rupees (can be negative) |
Error Responses
| HTTP | Error Code | When |
404 | CLIENT_NOT_FOUND | No client exists with this clientCode |
422 | INSUFFICIENT_LIMIT | Available funds are below amount — return data as above |
8. Sandbox & Testing
- Artham shares Sandbox credentials (API Key + Shared Secret).
- Prudent shares its Sandbox base URL for B1 and B2.
- Both sides test every API in Sandbox, then switch to Production credentials and URLs.