Get Recipients

GET /api-access/api/recipients

Retrieve a paginated list of recipients.

Authentication

Required Headers:

Authorization: HMAC-SHA256 PUBLIC_KEY:PRIVATE_KEY
X-Origin: third-party-api
X-Timestamp: 2025-10-12T14:30:00.000Z
Content-Type: application/json

Request

Query Parameters:

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number (1-indexed)
limit	integer	No	10	Number of items per page
recipient_type	string	No	transaction	Filter by recipient type

Available recipient_type values:

• transaction - Recipients for transactions
• reversal - Recipients for reversals
• all - All recipients
• withdrawal - Recipients for withdrawals

Response

Success Response (200):

{
  "items": [
    {
      "id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "phone": "string",
      "country": "string",
      "withdrawal_channel": "ATM",
      "account_number": "string",
      "account_branch": "string",
      "account_type": "corporate",
      "bank_code": "string",
      "institution_number": "string",
      "transit_number": "string",
      "security_question": "string",
      "security_question_answer": "string",
      "transaction_type": "interac_send",
      "recipient_type": "reversal",
      "language": "en",
      "created_at": "2025-10-12T18:04:57.150Z",
      "updated_at": "2025-10-12T18:04:57.150Z",
      "avatar": "string",
      "provider": "string",
      "payee_name": "string",
      "payee_code": "string",
      "user_id": "string",
      "business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "total": 0,
  "offset": 0,
  "limit": 0
}

Response Fields:

Field	Type	Description
items	array	Array of recipient objects
items[].id	string	Recipient ID
items[].first_name	string	Recipient's first name
items[].last_name	string	Recipient's last name
items[].email	string	Email address
items[].phone	string	Phone number
items[].country	string	Country code
items[].withdrawal_channel	string	Withdrawal channel (e.g., ATM)
items[].account_number	string	Bank account number
items[].account_branch	string	Account branch
items[].account_type	string	Account type
items[].bank_code	string	Bank code
items[].institution_number	string	Institution number
items[].transit_number	string	Transit number
items[].transaction_type	string	Transaction type
items[].recipient_type	string	Recipient type
items[].language	string	Language preference
items[].provider	string	Mobile money provider
items[].payee_name	string	Payee name (for bill pay)
items[].payee_code	string	Payee code (for bill pay)
items[].user_id	string	User ID
items[].business_id	string	Business ID
items[].created_at	string	Creation timestamp (ISO 8601)
items[].updated_at	string	Last update timestamp (ISO 8601)
total	integer	Total number of recipients
offset	integer	Current offset
limit	integer	Items per page

Examples

cURL

curl -X GET "https://sandbox.mara.boo/api-access/api/recipients?page=1&limit=10&recipient_type=transaction" \
  -H "Authorization: HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY" \
  -H "X-Origin: third-party-api" \
  -H "X-Timestamp: 2025-10-12T14:30:00.000Z" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://sandbox.mara.boo/api-access/api/recipients?page=1&limit=10&recipient_type=transaction', {
  method: 'GET',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': '2025-10-12T14:30:00.000Z',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Python

import requests

response = requests.get(
    'https://sandbox.mara.boo/api-access/api/recipients',
    params={
        'page': 1,
        'limit': 10,
        'recipient_type': 'transaction'
    },
    headers={
        'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
        'X-Origin': 'third-party-api',
        'X-Timestamp': '2025-10-12T14:30:00.000Z',
        'Content-Type': 'application/json'
    }
)

data = response.json()

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid authentication
403	Forbidden - Missing required headers
500	Internal Server Error

Related

• Create Recipient
• Get Recipient