Skip to main content

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​

ParameterDefaultMaxDescription
pageSize10001000Records per page
pageNumber1—Page index (1-based)
limit100100Total 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​

FieldSub-fieldRequiredDescription
criteria—YesArray of filters
filter—YesSingle condition (multiple allowed)
sortOptions—NoSorting specification
sortBy—YesField to sort on
sortOrder—NoASC or DESC
limit—NoTotal records to return
offset—Noid offset (requires sort by id)
pageSize—NoRecords per page
pageNumber—NoPage to return
getTotalCount—NoInclude 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 CaseRequired Document
Customer KYC / Account openingSPAA
ACH pull from an external accountDebit 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.