> ## Documentation Index > Fetch the complete documentation index at: https://docs.scaleo.io/llms.txt > Use this file to discover all available pages before exploring further. # List advertisers > Returns paginated list of advertisers. Alias: /api/v2/network/brand. ## OpenAPI ````yaml /network.bundled.yaml get /api/v2/network/advertisers openapi: 3.1.0 info: title: Scaleo Network API version: 0.1.1 summary: REST API for external integrations with the Scaleo affiliate platform. contact: name: Scaleo Support email: support@scaleo.io description: > The Scaleo Public API gives external systems the same capabilities as the dashboard, organised by user role — **Advertiser**, **Affiliate**, and **Manager** — plus shared reference data. Use the sidebar guides to get started: | Guide | Covers | |---|---| | [Authentication](#tag/Authentication) | API keys, role scoping | | [Errors](#tag/Errors) | Response envelope, error codes | | [Pagination](#tag/Pagination) | List params, pagination headers | | [Versioning](#tag/Versioning) | Version prefix, compatibility | | [Conventions](#tag/Conventions) | Timestamps, IDs, currencies | ## Quick start Authenticate with your API key using the `X-API-Key` HTTP header (preferred): ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile X-API-Key: YOUR_KEY ``` The legacy `api-key` query parameter is still accepted but **deprecated** — see [Authentication](#tag/Authentication) for migration details. Every response uses a consistent JSON envelope: ```json { "message": "OK", "success": true, "info": { } } ``` `success` is `true` for 2xx responses and `false` for errors. See [Errors](#tag/Errors) for the full format and error codes. ## Roles | Role | Endpoint prefix | |---|---| | Manager | `/api/v2/network/...` | | Advertiser | `/api/v2/advertiser/...` | | Affiliate | `/api/v2/affiliate/...` | Each API key is bound to one role and cannot call endpoints of another role. servers: - url: https://{domain} description: Customer-specific deployment. variables: domain: default: demo.scaletrk.com description: Your Scaleo instance domain. security: - ApiKeyHeaderAuth: [] - ApiKeyAuth: [] tags: - name: Overview x-displayName: Overview description: > The Scaleo Public API exposes the same data and operations available in the web dashboard, organised by user role — **Advertiser**, **Affiliate**, and **Manager** — plus a small set of shared resources. It is a REST API. All endpoints accept and return JSON, except for binary download endpoints (invoice PDFs, creative assets) which return raw file data. ## What you can do | Role | Capabilities | |---|---| | **Advertisers** | Offers, profile, statistics. | | **Affiliates** | Offers, campaigns, payouts, click/conversion/referral stats. | | **Managers** | Full administration: advertisers, affiliates, offers, billing, tracking, reporting. | | **All roles** | Shared reference data — countries, categories, tags, tiers. | ## URL conventions | URL prefix | Role | |---|---| | `/api/v2/network/...` | Manager | | `/api/v2/advertiser/...` | Advertiser | | `/api/v2/affiliate/...` | Affiliate | `{id}` in paths is a numeric resource ID. All timestamps are ISO 8601 UTC. ## Where to start 1. Read **Authentication** in the sidebar and obtain an API key. 2. Read **Errors** to understand the response envelope. 3. Try `GET /api/v2/affiliate/profile` (or the equivalent for your role) to verify your key works. 4. Browse the role-scoped sections for the endpoints relevant to your integration. ## Support For integration support, contact your account manager or [support@scaleo.io](mailto:support@scaleo.io). - name: Authentication x-displayName: Authentication description: > All Public API requests are authenticated with an **API key**. Pass it in the `X-API-Key` HTTP request header — this is the **preferred** method: ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile X-API-Key: YOUR_KEY ``` The user account that owns the key must have `api_status` enabled. ## Deprecated: `api-key` query parameter The `api-key` URL query parameter is still accepted for backwards compatibility but is **deprecated** and will be removed in a future release: ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile?api-key=YOUR_KEY ``` :::warning Deprecated Migrate to the `X-API-Key` header. Support for the `api-key` query parameter will be removed approximately 6 months after this notice. ::: ## Role scoping Each API key is bound to a specific user role and **cannot** call endpoints outside that role: | Role | Endpoint prefix | |---|---| | Manager | `/api/v2/network/...` | | Advertiser | `/api/v2/advertiser/...` | | Affiliate | `/api/v2/affiliate/...` | Calling an endpoint with the wrong role's key returns `403 Forbidden`. ## Where to find your key * **Affiliate / Advertiser** — dashboard → **Profile → API**. * **Manager** — admin panel → **Users → Managers → {user} → API**. Keys can be regenerated at any time. Regeneration invalidates the previous key immediately. ## Security best practices :::tip The `X-API-Key` header keeps your API key out of URLs, request logs, and browser history — always prefer the header over the query parameter. ::: * Use **HTTPS** only — HTTP does not protect the key in transit. * If a key is leaked, rotate it from the dashboard immediately. * For server-to-server integrations, store keys in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) rather than in source control. - name: Errors x-displayName: Errors description: > Every Public API response uses the same JSON envelope regardless of whether the request succeeded: ```json { "message": "OK", "success": true, "info": { } } ``` | Field | Description | |---|---| | `message` · string | Human-readable result summary. | | `success` · boolean | `true` for 2xx, `false` for errors. | | `info` · object | Payload. Omitted when the response carries no data. | :::info The HTTP status code is the authoritative signal. `success` is a convenience for clients that cannot easily inspect HTTP status codes. ::: ## Standard error responses | HTTP status | When you see it | |---|---| | `400 Bad Request` | Invalid JSON, unknown parameter, or malformed request. | | `401 Unauthorized` | Missing or invalid API key (`X-API-Key` header or `api-key` query param), or `api_status` disabled. | | `403 Forbidden` | Key is valid but belongs to a different role. | | `404 Not Found` | Resource not found or not visible to this account. | | `422 Unprocessable Entity` | Validation failed — see `info.errors`. | | `500 Internal Server Error` | Server-side problem. Retry with backoff. | ## Validation errors (422) When validation fails the server returns `422`. Each key in `info.errors` is the failing field name; the value is an array of error strings: ```json { "message": "Validation error", "success": false, "info": { "errors": { "email": ["Email cannot be blank."], "currency": ["Currency must be a valid ISO code."] } } } ``` ## Retry guidance * `4xx` — client problem, fix the request before retrying. * `5xx` — transient server problem. Retry with exponential backoff (start 1 s, max 60 s, add 0–25% jitter). * `GET` and `PUT` on a known resource are always safe to retry. - name: Pagination x-displayName: Pagination description: > List endpoints support consistent query parameters for pagination, filtering, and sorting. ## Pagination parameters | Parameter | Default / Max | |---|---| | `page` · integer | default `1` | | `perPage` · integer | default `10`, max `1000` | :::info Pagination metadata is in response headers, not in the body. ::: Paginated responses carry metadata in **HTTP response headers**: | Header | Value | |---|---| | `X-Pagination-Current-Page` | Current page number | | `X-Pagination-Total-Count` | Total items across all pages | | `X-Pagination-Page-Count` | Total number of pages | | `X-Pagination-Per-Page` | Page size used for this request | Example response for a list endpoint: ```json { "message": "Affiliates List", "success": true, "info": { "affiliates": [] } } ``` With HTTP headers: ``` X-Pagination-Current-Page: 2 X-Pagination-Total-Count: 137 X-Pagination-Page-Count: 7 X-Pagination-Per-Page: 20 ``` ## Sorting | Parameter | Values | |---|---| | `sortField` | endpoint-specific field name | | `sortDirection` | `asc` (default) \| `desc` | ``` GET /api/v2/network/affiliates?sortField=created_at&sortDirection=desc&page=1&perPage=50 ``` ## Filtering | Parameter | Meaning | |---|---| | `field=value` | Exact match — e.g. `status=1` | | `field[]=v1&field[]=v2` | Match any value — e.g. `country[]=US&country[]=GB` | | `field_from` / `field_to` | Date or numeric range | | `q` | Full-text search | ## Date format All date and datetime filters accept ISO 8601. If no timezone is given, UTC is assumed. * Date only: `2026-01-20` * Datetime UTC: `2026-01-20T13:45:00Z` - name: Versioning x-displayName: Versioning description: > The Public API uses a path-based version prefix. | Version | Status | Prefix | |---|---|---| | **v2** | Stable, default | `/api/v2/...` | ## Compatibility policy * **Additive changes** (new fields, new endpoints) can appear without notice. Clients must tolerate unknown fields. * **Breaking changes** require a new major version, announced with a minimum 6-month deprecation window. * **Bug fixes** that alter response shape are treated as breaking. - name: Conventions x-displayName: Conventions description: > Conventions used across the entire Public API. ## Time and dates All timestamps are **ISO 8601 in UTC** unless explicitly noted: ``` 2026-01-20T13:45:00Z ``` Date-only fields (report ranges, billing periods) use `YYYY-MM-DD`. ## Identifiers * Resource IDs are positive integers. * Country IDs use **GeoNames** numeric IDs: `6252001` (US), `2635167` (GB). Full list: `GET /api/v2/common/lists/countries`. ## Currencies and monetary values * Currency codes follow **ISO 4217**: `USD`, `EUR`, `GBP`. * Monetary amounts have up to 4 decimal places: `12.5000`. Display rounding is the client's responsibility. ## Status values Many resources use a numeric `status` field: | Value | Meaning | |---|---| | `1` | Active | | `2` | Disabled / Inactive | | `3` | Pending review | | `4` | Rejected | Per-endpoint documentation lists the exact allowed values and any resource-specific additions. ## Booleans JSON booleans are always native `true` / `false`. Some legacy filters accept `1` / `0` as a fallback — prefer native booleans. ## Null and empty values * Optional fields absent from the record are returned as `null`, not omitted. * Empty collections are returned as `[]` (arrays) or `{}` (objects). * In `POST` / `PUT` bodies: sending `null` clears the field; omitting the key keeps the current value (unless noted in the endpoint description). ## Localisation Display strings (offer names, descriptions, creative captions) are returned in the network's configured primary language. There is no per-request locale override. - name: Advertiser / Profile x-displayName: Profile description: View and update advertiser account profile. - name: Advertiser / Offers x-displayName: Offers description: Browse and inspect offers available to the advertiser account. - name: Advertiser / Statistics / Reports x-displayName: Reports description: Aggregated statistics reports with breakdowns and column options. - name: Advertiser / Statistics / Clicks x-displayName: Clicks description: Click-level statistics and reporting options for advertisers. - name: Advertiser / Statistics / Conversions x-displayName: Conversions description: Conversion-level statistics, columns, and reporting options. - name: Affiliate / Profile x-displayName: Profile description: View and update affiliate account profile and basic info. - name: Affiliate / Dashboard x-displayName: Dashboard description: Aggregated network summary for the affiliate dashboard. - name: Affiliate / Offers x-displayName: Offers description: Browse offers, request access, and download offer assets. - name: Affiliate / Campaigns x-displayName: Campaigns description: Manage tracking campaigns associated with offers. - name: Affiliate / Postbacks x-displayName: Postbacks description: Configure server-to-server postback URLs for conversion tracking. - name: Affiliate / Leads x-displayName: Leads description: Retrieve leads attributed to the affiliate. - name: Affiliate / Billing / Balances x-displayName: Balances description: View affiliate balances and submit payout requests. - name: Affiliate / Billing / Invoices x-displayName: Invoices description: List affiliate invoices and download invoice PDFs. - name: Affiliate / Billing / Payment Methods x-displayName: Payment Methods description: Manage affiliate payment methods and supported currencies. - name: Affiliate / Billing / Preferences x-displayName: Billing Preferences description: View and update affiliate billing preferences. - name: Affiliate / Statistics / Reports x-displayName: Reports description: Aggregated statistics with flat and tree breakdowns. - name: Affiliate / Statistics / Clicks x-displayName: Clicks description: Click statistics and report options. - name: Affiliate / Statistics / Conversions x-displayName: Conversions description: Conversion statistics and report options. - name: Affiliate / Statistics / Referrals x-displayName: Referrals description: Referral program statistics. - name: Manager / Dashboard x-displayName: Dashboard description: Top affiliates and top offers summaries for the network dashboard. - name: Manager / Activity Log x-displayName: Activity Log description: Network-wide activity and audit log. - name: Manager / Auth Tools x-displayName: Auth Tools description: Login link generation, 2FA login links, and password reset utilities. - name: Manager / Advertisers x-displayName: Advertisers description: Create, list, view, and update advertiser accounts. - name: Manager / Affiliates / Management x-displayName: Affiliates description: Create, list, view, and update affiliate accounts and filters. - name: Manager / Affiliates / Postbacks x-displayName: Affiliate Postbacks description: Manage postbacks at the affiliate level. - name: Manager / Affiliates / Promo Codes x-displayName: Promo Codes description: Manage affiliate promo codes individually or in bulk. - name: Manager / Offers / Management x-displayName: Offers description: Manage offers — create, update, list, and approve access requests. - name: Manager / Offers / Affiliate Access x-displayName: Affiliate Access description: Control which affiliates can access specific offers. - name: Manager / Offers / Creatives x-displayName: Creatives description: Upload and manage creative assets attached to offers. - name: Manager / Offers / Custom Parameters x-displayName: Custom Parameters description: Configure custom tracking parameters per offer. - name: Manager / Offers / Goals x-displayName: Goals description: Define conversion goals for offers. - name: Manager / Offers / Landing Pages x-displayName: Landing Pages description: Manage offer landing page URLs. - name: Manager / Offers / Targeting x-displayName: Targeting description: Configure offer targeting rules (geo, device, etc.). - name: Manager / Offers / Tracking Settings x-displayName: Tracking Settings description: Per-offer tracking configuration. - name: Manager / Campaigns x-displayName: Campaigns description: Manage tracking campaigns at the network level. - name: Manager / Leads x-displayName: Leads description: List and update leads across the network. - name: Manager / Billing x-displayName: Billing description: Advertiser billing — preferences and invoicing. - name: Manager / Billing / Affiliate Billing x-displayName: Affiliate Billing description: Affiliate billing — balances, invoices, payment methods, preferences. - name: Manager / Statistics / Reports x-displayName: Reports description: Aggregated statistics — flat and tree breakdowns, columns config. - name: Manager / Statistics / Clicks x-displayName: Clicks description: Network-level click statistics. - name: Manager / Statistics / Conversions x-displayName: Conversions description: Network-level conversion statistics, including status changes. - name: Manager / Statistics / Logs x-displayName: Logs description: Raw click logs and inbound/outbound postback logs. - name: Manager / Tracking / Clicks x-displayName: Clicks description: Server-side click tracking — single and batch insert. - name: Manager / Tracking / Conversions x-displayName: Conversions description: Server-side conversion tracking and conversion lookups. - name: Manager / Tracking / Promo Codes x-displayName: Promo Code Tracking description: Server-side promo-code tracking endpoints. - name: Common / Lists x-displayName: Reference Lists description: >- Static reference data — countries, categories, tags, tiers, traffic sources. paths: /api/v2/network/advertisers: get: tags: - Manager / Advertisers summary: List advertisers description: 'Returns paginated list of advertisers. Alias: /api/v2/network/brand.' operationId: getV2_networkAdvertisers parameters: - name: page in: query description: Page number. schema: type: integer - name: perPage in: query description: Items per page. schema: type: integer - name: sortField in: query description: Sort field. schema: type: string - name: sortDirection in: query description: Sort direction. schema: type: string enum: - asc - desc - name: search in: query description: Search by text or ID. schema: type: string - name: columns in: query description: Comma-separated column keys. schema: type: string responses: '200': description: Advertisers list. content: application/json: schema: type: object properties: status: type: string example: success code: type: integer example: 200 name: type: string example: OK message: type: string info: type: object properties: advertisers: type: array items: type: object properties: id: type: integer external_id: type: string description: >- External identifier for integration with third-party systems. email: type: string firstname: type: string lastname: type: string auth_key: type: - string - 'null' description: Authentication key (internal use). access_token: type: - string - 'null' description: Session access token. expiration_time: type: - string - 'null' description: Token expiration timestamp. contacts: type: - string - 'null' description: JSON-encoded contact information. custom_fields: type: - string - 'null' description: JSON-encoded custom field values. account_balance: type: - string - 'null' description: >- Current account balance (string-encoded decimal). company_name: type: string description: Advertiser company name. website_url: type: string description: Advertiser website URL. phone: type: string description: Contact phone number. image: type: string description: Profile image URL. notes: type: string description: Public notes about the advertiser. payment_details: type: - string - 'null' description: JSON-encoded payment method details. status: type: integer description: >- Account status: 1=active, 2=disabled, 3=pending, 4=rejected. api_status: type: integer description: 'API access status: 1=enabled, 0=disabled.' api_key: type: - string - 'null' description: | SCL-12692. Last 8 characters (suffix) of the advertiser's hashed API key. The full plain-text key is never returned in profile responses — it is shown only once via POST /user/change-api-key immediately after generation. Null or empty when API access is disabled or no key has been generated. country: type: integer description: Country geoname_id. region: type: string description: Region/state name. city: type: string description: City name. address: type: string description: Street address. postal_code: type: string description: Postal or ZIP code. tags: type: string description: Comma-separated tag labels. ip: type: string description: Last known IP address. number_format_id: type: integer description: Number format preference ID. date_format_id: type: integer description: Date format preference ID. timezone: type: string description: IANA timezone identifier. conversions: type: integer description: Total approved conversion count. email_notifications: type: integer description: >- Email notifications setting: 1=enabled, 0=disabled. email_mailroom: type: integer description: >- Mailroom email notifications: 1=enabled, 0=disabled. created: type: integer description: Unix timestamp of account creation. updated: type: integer description: Unix timestamp of last account update. visited: type: integer description: Unix timestamp of last login. activity: type: integer description: Unix timestamp of last activity. twoFA_enabled: type: integer description: 'Two-factor authentication enabled: 1=yes, 0=no.' require_postback_token: type: integer description: Whether postback token verification is required. postback_token: type: - string - 'null' description: Postback security token. registration: type: string description: Registration date (ISO 8601). tags_selected: type: array items: type: object properties: id: type: string description: Tag ID. title: type: string description: Tag label. managers_assigned: type: string description: >- Comma-separated IDs of managers assigned to this advertiser. country_selected: type: string description: Country name derived from country geoname_id. offers_count: type: integer description: >- Total number of offers associated with this advertiser. live_stats: type: object properties: key: type: string current: type: object properties: ranges: type: array items: type: string series: type: array items: type: integer total: type: integer total_change: type: integer previous: type: object properties: ranges: type: array items: type: string series: type: array items: type: integer total: type: integer total_change: type: integer show_affiliate_details: type: integer description: >- Whether affiliate details are shown to this advertiser: 1=yes, 0=no. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: responses: BadRequest: description: >- Malformed request — invalid JSON, unknown query parameter, or other request-level problem. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Request could not be parsed. success: false info: errors: {} Unauthorized: description: >- Missing or invalid API key (`X-API-Key` header or `api-key` query param), or the user has `api_status` disabled. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: API key is invalid or missing. success: false Forbidden: description: >- API key is valid but role-scoped — the endpoint is not available for this role. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: This endpoint is not available for your role. success: false NotFound: description: Resource does not exist or is not visible to the calling account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Resource not found. success: false InternalServerError: description: Unexpected server-side problem. Safe to retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: An unexpected error occurred. success: false info: errors: {} schemas: ErrorResponse: type: object description: | Standard error envelope returned by all non-2xx responses. See the **Errors** guide for full details and retry guidance. required: - message - success properties: message: type: string description: Human-readable description of the error. success: type: boolean enum: - false description: Always `false` for error responses. info: type: - object - 'null' description: >- Additional error details. Present for 400 and 500 responses; absent for 401, 403, 404. properties: errors: type: object description: >- Map of field names to arrays of error messages (present on 400/500). additionalProperties: type: array items: type: string securitySchemes: ApiKeyHeaderAuth: type: apiKey in: header name: X-API-Key description: >- Preferred authentication method. Pass the API key in the `X-API-Key` HTTP request header. The user account must have `api_status` enabled. ApiKeyAuth: type: apiKey in: query name: api-key description: >- Deprecated. Pass the API key as the `api-key` query parameter. Supported for backwards compatibility — migrate to the `X-API-Key` header instead. ````