> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Referred Businesses
> Retrieves a paginated list of the businesses that registered through your referral links, newest first. `data` is the array of businesses and `pagination` sits beside it at the top level rather than inside `data`.
Retrieve a paginated list of businesses you have referred. Filter by referral status.
**Broker activation is required.** Broker accounts are activated by the Rolla admin team — you cannot activate a broker account yourself through the API. Once your business has been activated as a broker by Rolla, all broker endpoints become available. Until then, all requests will return a `403 Forbidden` error. Contact [support@rolla.xyz](mailto:support@rolla.xyz) to request broker activation.
## Example Request
```bash theme={null}
curl -X GET "https://api.rolla.xyz/api/v1/external/broker/referred-businesses?page=1&pageSize=20&status=completed" \
-H "X-API-Key: your_api_key_here"
```
## Query Parameters
| Parameter | Type | Description |
| ---------- | ------- | -------------------------------------------------------------------------- |
| `page` | integer | Page number (default: 1) |
| `pageSize` | integer | Results per page (default: 20, max: 100) |
| `status` | string | Filter by onboarding status: `created`, `started`, `completed`, `approved` |
Businesses are returned newest first. `data` is the array of businesses and `pagination` sits beside it at the top level, not inside `data`.
## Example Response
```json theme={null}
{
"status": 200,
"message": "Referred businesses fetched successfully",
"success": true,
"data": [
{
"id": "d4e5f6a7-b8c9-4123-9def-456789012345",
"name": "Acme Corp Ltd",
"email": "contact@acmecorp.com",
"status": "completed",
"created_at": "2024-01-15T10:30:00.000Z",
"application_status": "approved",
"negotiation_enabled": false
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 15,
"totalPages": 1
}
}
```
`status` is the business's own onboarding status (`created`, `started`, `completed`, `expired`). The KYB decision is `application_status` (`draft`, `submitted`, `approved`, `rejected`, `changes_requested`, `deactivated`, `blacklisted`, `deleted`), and it is `null` until the business starts a KYB application. Once `application_status` is `approved` the business is live and you start earning commissions from its transactions.
The `status` filter is matched against the business's onboarding status, so filtering by `approved` returns no rows. Filter by `completed` and read `application_status` instead.
## OpenAPI
````yaml GET /broker/referred-businesses
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/broker/referred-businesses:
get:
summary: Get Referred Businesses
description: >-
Retrieves a paginated list of the businesses that registered through
your referral links, newest first. `data` is the array of businesses and
`pagination` sits beside it at the top level rather than inside `data`.
operationId: getReferredBusinesses
parameters:
- name: page
in: query
description: Page number
schema:
type: integer
default: 1
minimum: 1
example: 1
- name: pageSize
in: query
description: Results per page
schema:
type: integer
default: 20
minimum: 1
maximum: 100
example: 20
- name: status
in: query
description: >-
Filter by the business's onboarding status. `approved` is accepted
but matches no rows: the KYB decision is reported separately as
`application_status`.
schema:
type: string
enum:
- started
- completed
- created
- approved
example: completed
responses:
'200':
description: Referred businesses fetched successfully
content:
application/json:
schema:
type: object
required:
- status
- message
- success
- data
- pagination
properties:
status:
type: integer
example: 200
message:
type: string
example: Referred businesses fetched successfully
success:
type: boolean
example: true
data:
type: array
items:
$ref: '#/components/schemas/ReferredBusiness'
pagination:
$ref: '#/components/schemas/Pagination'
example:
status: 200
message: Referred businesses fetched successfully
success: true
data:
- id: d4e5f6a7-b8c9-4123-9def-456789012345
name: Acme Corp Ltd
email: contact@acmecorp.com
status: completed
created_at: '2024-01-15T10:30:00.000Z'
application_status: approved
negotiation_enabled: false
pagination:
page: 1
pageSize: 20
total: 15
totalPages: 1
'400':
description: Invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 400
message: Validation failed
errors:
- path:
- status
message: >-
Invalid enum value. Expected 'started' | 'completed' |
'created' | 'approved'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - the business is not activated as a broker
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
status: 403
message: Business is not activated as a broker
components:
schemas:
ReferredBusiness:
type: object
description: A business that registered through one of your referral links.
required:
- id
- name
- email
- status
- created_at
- application_status
- negotiation_enabled
properties:
id:
type: string
format: uuid
description: Business identifier
example: d4e5f6a7-b8c9-4123-9def-456789012345
name:
type: string
description: Referred business name
example: Acme Corp Ltd
email:
type: string
format: email
description: Business email
example: contact@acmecorp.com
status:
type: string
enum:
- created
- started
- completed
- expired
description: >-
The business's own onboarding status. The KYB decision is
`application_status`.
example: completed
created_at:
type: string
format: date-time
description: When the business registered through your link.
example: '2024-01-15T10:30:00.000Z'
application_status:
type: string
nullable: true
enum:
- draft
- submitted
- approved
- rejected
- changes_requested
- deactivated
- blacklisted
- deleted
- null
description: >-
KYB application status, or null until the business starts an
application.
example: approved
negotiation_enabled:
type: boolean
description: Whether rate negotiation is enabled for this business.
example: false
Pagination:
type: object
description: >-
Paging block used by the listings that nest one. The transaction
listings do not: they return `totalCount`, `page`, `pageSize` and
`totalPages` flat alongside `transactions`.
required:
- page
- pageSize
- total
- totalPages
properties:
page:
type: integer
description: Page just returned, starting at 1.
example: 1
pageSize:
type: integer
description: Rows per page.
example: 20
total:
type: integer
description: Total rows matching the filters.
example: 150
totalPages:
type: integer
description: How many pages there are in total.
example: 8
Error:
type: object
required:
- status
- message
description: >-
Error envelope. Some errors add further top-level fields (for example
`accountBlocked`, `provider`, `missingFields`); the endpoint documents
them where they apply.
additionalProperties: true
properties:
status:
type: integer
description: HTTP status code, repeated in the body as a number
example: 400
message:
type: string
description: Human-readable description of what went wrong
example: Validation failed
code:
type: string
description: >-
Machine-readable error code, present on some errors only. See the
Errors concept page for the taxonomy.
example: ACCOUNT_RESTRICTED
errors:
type: array
description: 'Present on `400` validation failures: one entry per offending field'
items:
type: object
properties:
path:
type: array
items:
type: string
example:
- amount
message:
type: string
example: >-
amount must be a whole number of smallest currency units (e.g.
cents)
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````