Get all Purpose Codes (Legacy)

Overview

This service is used to gather all purpose codes in the system used for regulatory compliance and payment dispatch. Because specifying a purpose code is mandatory when initiating payment requests, you need this information when calling Create Payment Request.

Resource Access

• HTTP Method: GET
• Endpoint: /profile/v2.1/purpose
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
x-api-key	string	No	API key for additional authentication

Query Parameters

Parameter	Type	Required	Description
purpose	boolean	Yes	Must be set to true to retrieve purpose codes.

Response

Success Response (200 OK)

{
  "documentTypes": [
    {
      "id": 12,
      "category": "Payment Purpose",
      "title": "Purchase of Good(s)",
      "createdAt": "2021-04-19T08:19:57.000Z",
      "updatedAt": "2021-04-19T08:19:57.000Z"
    },
    {
      "id": 13,
      "category": "Payment Purpose",
      "title": "Purchase of Professional Service(s)",
      "createdAt": "2021-04-19T08:19:57.000Z",
      "updatedAt": "2021-04-19T08:19:57.000Z"
    },
    {
      "id": 14,
      "category": "Payment Purpose",
      "title": "Professional fees payment(i.e. legal, accountant)",
      "createdAt": "2021-04-19T08:19:57.000Z",
      "updatedAt": "2021-04-19T08:19:57.000Z"
    },
    {
      "id": 15,
      "category": "Payment Purpose",
      "title": "Payroll/Personnel Payment",
      "createdAt": "2021-04-19T08:19:57.000Z",
      "updatedAt": "2021-04-19T08:19:57.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
documentTypes	array	List of purpose code objects.
documentTypes[].id	number	Unique ID of the purpose code (use in payment request).
documentTypes[].category	string	Category name (e.g. Payment Purpose).
documentTypes[].title	string	Description of the purpose code.
documentTypes[].createdAt	string (date-time)	Creation timestamp.

Error Responses

• 400 Bad Request: Invalid parameters or malformed request
• 401 Unauthorized: Missing or invalid Bearer authentication token
• 403 Forbidden: Insufficient account permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: An internal server error occurred

Code Examples

Base URL

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

cURL

curl -X GET \
  'https://gateway.ahrvo.network/banking/ibans/v2/profile/v2.1/purpose?purpose=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/profile/v2.1/purpose"
params = {"purpose": "true"}
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/profile/v2.1/purpose';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const params = { purpose: true };

axios.get(url, { headers, params })
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response ? error.response.data : error.message));

Usage Notes

• Query parameter purpose=true is required.
• Cache purpose codes locally as they rarely change.

Interactive API Explorer