List all recipients

GEThttps://api.omise.co/recipients

Retrieve a paginated list of all recipients belonging to your account. Results can be filtered by date range and sorted chronologically.

---

Request Parameters

Recommended - 5 fieldsRecommended Parameters

▼

`limit`INTEGER(optional)

Number of records to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100

Default:20

`offset`INTEGER(optional)

Number of records to skip before returning results. Used for pagination.

Example:0

Default:0

`order`STRING(optional)

Sort order for results based on creation date.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

`from`STRING(optional)

Filter recipients created on or after this UTC datetime. ISO 8601 format.

Example:"2025-01-01T00:00:00Z"

`to`STRING(optional)

Filter recipients created on or before this UTC datetime. ISO 8601 format.

Example:"2025-12-31T23:59:59Z"

---

Responses

200

Successful transaction

Recipients list retrieved successfully. Returns paginated list with metadata.

Response structure:

• object - Always "list"
• data - Array of recipient objects
• total - Total number of recipients matching filters
• limit - Number of records per page
• offset - Current pagination offset
• from, to - Applied date filters

Each recipient object in data contains:

• object - The value "recipient"
• id - Recipient identifier (recp_*)
• livemode - Live or test mode
• location - API path to the recipient object
• activated_at - Activation timestamp (ISO 8601)
• active - Whether recipient is active
• bank_account - Destination bank account object
• created_at - Creation timestamp (ISO 8601)
• default - Whether recipient is account default
• deleted - Whether recipient is deleted
• description - Recipient description
• email - Recipient email address
• failure_code - Failure reason code (name_mismatch, account_not_found, bank_not_found)
• metadata - Custom metadata
• name - Recipient name
• schedule - Transfer schedule (expandable)
• tax_id - Recipient tax ID
• type - Recipient type (individual, corporation)
• verified - Whether recipient is verified
• verified_at - Verification timestamp (ISO 8601)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid date format for from or to
• Invalid order value
• Negative offset or limit
• limit exceeds maximum (100)

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/recipients \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

recipients = Omise::Recipient.list(limit: 20, offset: 0)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

recipients = omise.Recipient.retrieve(limit=20, offset=0)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const recipients = await omise.recipients.list({
  limit: 20,
  offset: 0
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$recipients = OmiseRecipient::retrieve([
    'limit' => 20,
    'offset' => 0
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

ScopedList<Recipient> recipients = client.recipients()
    .list(new ScopedList.Options()
        .limit(20)
        .offset(0));

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var recipients = await client.Recipients.List(new ListOptions
{
    Limit = 20,
    Offset = 0
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

recipients, _ := client.Recipients().List(&operations.ListRecipients{
    Limit:  20,
    Offset: 0,
})

---

Pagination

Use limit and offset parameters to paginate through results:

# First page (0-19)
curl https://api.omise.co/recipients?limit=20&offset=0 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# Second page (20-39)
curl https://api.omise.co/recipients?limit=20&offset=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

---

🔑API Credentials

▼

Try it out

Recommended - 5 fields

▼

Your IP: ...Loading...