Artham
ARTHAM

Prudent Integration API Specification

Version 0.1  ·  October 2026

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

  1. Artham APIs (A1, A2) — Artham hosts them, Prudent calls them.
  2. Prudent APIs (B1, B2) — Prudent builds them to this document, Artham calls them.
  3. Both directions use the same API key + HMAC signature (Section 2) and the same response format (Section 3).

API Summary

#MethodEndpointPurposeHosted by
A1POST/api/v1/partner/webview/linkSend distributor and/or client details; returns the URL that opens Artham in the webviewArtham
A2GET/api/v1/broker/strategy-holdingsDaily strategy holdings file for the BODArtham
B1GET/api/v1/clients/{clientCode}Client KYC and bank details, after DPDP consentPrudent
B2POST/api/v1/clients/{clientCode}/limit-openClient funds checkPrudent

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.

HeaderDescriptionExample
X-Api-KeyStatic API key issued by Artham to Prudentartham_live_k8Fj2mNp...
X-SignatureHMAC-SHA256 of the request, computed with the shared secreta1b2c3d4... (64 hex chars)

Credential Setup

  1. Artham issues one API Key and one Shared Secret to Prudent, separately for Sandbox and Production.
  2. The same pair is used in both directions — to sign your calls to Artham and to verify Artham's calls to you.
  3. 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
ComponentDescriptionExample
HTTP_METHODUppercase HTTP methodGET / POST
pathRequest path — no host, no query string/api/v1/clients/PL889900
bodyRaw 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

HTTPerror.codeWhen
401AUTH_REQUIREDX-Api-Key or X-Signature missing
401AUTH_TOKEN_INVALIDUnknown 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

StatusWhen to Use
200Success
400Invalid or missing request fields
401Invalid API key or signature
404Client or distributor not found
422Business rule violation (e.g. insufficient funds)
500Internal server error

Error Codes

CodeDescription
INVALID_REQUESTMissing or malformed request parameters
CLIENT_NOT_FOUNDThe clientCode does not exist
CLIENT_INACTIVEClient account is deactivated or suspended
DISTRIBUTOR_REQUIREDA new client was sent without its distributor
CLIENT_DISTRIBUTOR_MISMATCHThe client is mapped to a different distributor
DISTRIBUTOR_NOT_FOUNDThe distributorCode is not on Artham
INSUFFICIENT_LIMITClient does not have enough funds
INTERNAL_ERRORUnexpected 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.

POST /api/v1/partner/webview/link Send user details, get the webview URL

Endpoint & Method

ItemValue
MethodPOST
Path/api/v1/partner/webview/link
Hosted byArtham
AuthenticationX-Api-Key + X-Signature — see Section 2
Called fromPrudent'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

KeyTypeRequiredDescription
rolestringYesWho is opening Artham: "DISTRIBUTOR" or "CLIENT"
distributorobjectConditionalDistributor details. Required when role is "DISTRIBUTOR".
distributor.codestringYesDistributor's code at Prudent
distributor.namestringYesDistributor's name — shown on the dashboard and in client consent messages
distributor.emailAddressstringYesDistributor's email address
clientobjectConditionalClient details. Required when role is "CLIENT".
client.codestringYesClient code (UCC)
client.namestringYesClient's full name
client.emailAddressstringYesClient's registered email address
client.mobileNumberstringYesClient'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

FieldTypeDescription
urlstringOpen in the webview without modifying it
expiresAtstringExpiry time, ISO 8601 with IST offset
ttlSecondsintegerSeconds 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

HTTPerror.codeWhen
400INVALID_REQUESTrole missing or invalid, the object for that role not sent, or a required field missing
422DISTRIBUTOR_REQUIREDA new client sent without its distributor
422CLIENT_DISTRIBUTOR_MISMATCHThe 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.

GET /api/v1/broker/strategy-holdings Download the strategy holdings file (CSV)

Endpoint & Method

ItemValue
MethodGET
Path/api/v1/broker/strategy-holdings
Hosted byArtham
AuthenticationX-Api-Key + X-Signature — see Section 2
ResponseCSV file (strategy_holdings_YYYYMMDD.csv)

Query Parameters

ParameterTypeRequiredDescription
datestringNoYYYY-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

HeaderDescription
X-As-OfDate the file belongs to
X-Row-CountNumber of data rows
X-Checksum-SHA256SHA-256 of the file. If rows or checksum don't match, download again.

File Columns

ColumnTypeDescription
clientCodestringClient code
strategyIdstring12-character Artham strategy ID
isinstring12-character ISIN
symbolstringNSE symbol, or BSE scrip code when exchange is BSE
exchangestringNSE or BSE
quantitydecimalQuantity held, 4 decimal places
Full snapshot. One row per client × strategy × scrip, corporate actions applied. Replace your stored data with each file.

Error Responses

HTTPerror.codeWhen
404FILE_NOT_FOUNDNo file for that date
409FILE_NOT_READYToday'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.

GET /api/v1/clients/{clientCode} Fetch client KYC and account details

Endpoint & Method

ItemValue
MethodGET
Path/api/v1/clients/{clientCode}
Hosted byPrudent
AuthenticationX-Api-Key + X-Signature — see Section 2

Path Parameters

ParameterTypeDescription
clientCodestringClient 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

FieldTypeRequiredDescription
clientCodestringYesClient code
rmCodestringYesClient's distributor code
namestringYesFull name as per KYC
panstringYesPAN (10 characters)
dateOfBirthstringYesDate of birth, YYYY-MM-DD
address1stringNoAddress line 1
address2stringNoAddress line 2
address3stringNoAddress line 3
citystringNoCity
statestringNoState
pinCodestringNoPIN code (6 digits)
emailAddressstringYesRegistered email address
mobileNumberstringYesRegistered mobile number (10 digits)
accountNostringYesAccount number of the client's active / default bank account
ifscCodestringYesIFSC code (11 characters)
accountTypestringYes"S" Savings, "C" Current, "O" Other
clientTypeCodeintegerYesClient type, e.g. 1 Individual, 6 HUF — full list in Broker Integration API, API 1
isNRIbooleanYestrue if the client is a Non-Resident Indian
isPoliticallyExposedPersonbooleanYestrue 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

HTTPError CodeWhen
404CLIENT_NOT_FOUNDNo client exists with this clientCode
422CLIENT_INACTIVEClient 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.

POST /api/v1/clients/{clientCode}/limit-open Check client funds

Endpoint & Method

ItemValue
MethodPOST
Path/api/v1/clients/{clientCode}/limit-open
Hosted byPrudent
AuthenticationX-Api-Key + X-Signature — see Section 2

Request Body

{
  "subAccountCode": null,
  "amount": 50000,
  "segment": "EQUITY",
  "purpose": "INVEST"
}

Request Fields

KeyTypeRequiredDescription
amountnumberYesAmount needed in rupees. 0 for REBALANCE.
purposestringYes"INVEST" or "REBALANCE" — see formula below
segmentstringYesAlways "EQUITY"
subAccountCodestringNoAlways null

Available funds — calculated by Prudent:

purposeAvailable
INVESTcash_ledger − margin_utilised
REBALANCEcash_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

FieldTypeDescription
sufficientbooleantrue if available funds ≥ amount
availableLimitnumberAvailable funds in rupees (can be negative)

Error Responses

HTTPError CodeWhen
404CLIENT_NOT_FOUNDNo client exists with this clientCode
422INSUFFICIENT_LIMITAvailable funds are below amount — return data as above

8. Sandbox & Testing

  1. Artham shares Sandbox credentials (API Key + Shared Secret).
  2. Prudent shares its Sandbox base URL for B1 and B2.
  3. Both sides test every API in Sandbox, then switch to Production credentials and URLs.