Getting Started

To integrate Ahrvo Banking into your application or website after your sandbox setup:

1. Obtain your API bearer token
   Contact your Ahrvo Banking representative to receive a sandbox API bearer token.

2. Test your integration
   Make a test API request against the sandbox environment to verify your integration:

   POST https://gateway.ahrvo.network/v1.0/some-endpoint
   Authorization: Bearer <YOUR_SANDBOX_TOKEN>
   x-api-key: {apiKey}
   Content-Type: application/json
   

Authentication

All API requests to Ahrvo Banking require a valid Bearer token and must be made over HTTPS:

• Bearer Token
  • Obtain your sandbox or production token from your Ahrvo Banking representative.
  • Include it in every request header as:

    Authorization: Bearer <YOUR_TOKEN>

• HTTPS Only
  • All calls must use https://.
  • Any request over plain http:// will be rejected.
• Rate Limits
  • 1000 requests per 10 seconds.
  • Exceeding this returns 429 Too Many Requests, and additional calls in that window are dropped.
• Failure Modes
  • Missing/invalid token → 401 Unauthorized
  • HTTP (non-HTTPS) → Connection refused or equivalent transport error
  • Rate limit exceeded → 429 Too Many Requests

Note: Be sure to test your token and HTTPS setup in the sandbox environment before moving to production.

Working With API

All figures and data in this guide are representational. For production access, contact your Ahrvo Network representative.

---

1. Request Header

For every request you must include your JWT:

Authorization: Bearer JWT token

---

2. Create Entities

• Use HTTP POST to create any entity.
• A successful request returns 201 Created and the entity URL in the Location response header.

---

3. Update Entities

• Use HTTP POST to update any entity.
• A successful update returns 204 No Content.

Notes
• Include only the nodes that need updating.
• Pass a node value of null to delete non-mandatory information.
• Use the delink API to detach an associated object.

---

4. Retrieve Entities by id or externalId

• Use HTTP GET to fetch an entity.
• Query by Ahrvo Network system id or your own externalId.

Notes
• The response includes all attributes.
• Non-mandatory attributes with null values are omitted.
• System fields (createdOn, createdBy, lastUpdatedOn, lastUpdatedBy) are always present.
• Associations are returned as objects containing their URLs—issue a separate GET to retrieve details.

---

5. List Entities

5.1 Overview

HTTP POST is used for bulk fetches (e.g., customers, transactions). POST secures sensitive data such as PII and account details.

5.2 Filters

Each list API supports multiple filters.

5.3 Sorting

Sort on any supported field. Default order: descending lastUpdatedOn.

5.4 Pagination

Parameter	Default	Max	Description
pageSize	1000	1000	Records per page
pageNumber	1	—	Page index (1-based)
limit	100	100	Total records when pageSize/pageNumber are absent
offset	—	—	Starting id (requires sort by id)

• If none of these parameters are supplied, defaults (pageSize, pageNumber) apply.
• When both sets are present, pageSize/pageNumber override limit/offset.

5.5 Response

Returns the records that match the filter plus:

• totalCount
• returnedCount
• offset

Only essential attributes are returned (not the full schema). Data lag: up to 30 minutes.

5.6 Request Body Schema

Field	Sub-field	Required	Description
criteria	—	Yes	Array of filters
filter	—	Yes	Single condition (multiple allowed)
sortOptions	—	No	Sorting specification
sortBy	—	Yes	Field to sort on
sortOrder	—	No	ASC or DESC
limit	—	No	Total records to return
offset	—	No	id offset (requires sort by id)
pageSize	—	No	Records per page
pageNumber	—	No	Page to return
getTotalCount	—	No	Include totalCount when true

---

6. Attribute metaData

Key-value store (max 20 keys) available on every entity. Not used internally by Ahrvo Network.
Warning: never store sensitive data (bank or card numbers).

---

7. Attribute tags

Simple labels to identify or group entities. Multiple entities can share a tag and be queried together.

---

8. Authorization Documents

Use Case	Required Document
Customer KYC / Account opening	SPAA
ACH pull from an external account	Debit authorization

8.1 Upload Options

1. Document API workflow

   1. Upload the file.
   2. Capture its system id (or provide externalId).
   3. Link the document to one or more entities.
      Best when one document applies to multiple entities.

2. Inline Base64
   Provide base64EncodedContent when creating or updating the entity—the document is stored and auto-linked.

---