Introduction to the Walr Demand API

This guide provides a comprehensive overview of the Walr Demand API, which enables programmatic access to audience data and management capabilities. The API allows partners to retrieve and manage audience information, including details about status, targeting, and performance metrics.

Quick Start

1. Obtain your API credentials
2. Understand the API structure
3. Explore available endpoints
4. Implement best practices

Prerequisites

Before you begin, ensure you have:

• A valid Walr account with Demand API access
• A supplier access token for authentication
• Understanding of your audience requirements
• Test and live URLs for your surveys

To obtain your supplier access token, please contact support@walr.com.

API Overview

The Walr Demand API provides comprehensive access to audience data and management capabilities. Key features include:

• Audience Data Retrieval: Access detailed information about audiences
• Status Monitoring: Track audience status and performance
• Targeting Details: View audience targeting criteria

Getting Started

Base URLs

Environment	URL
Staging	https://api-staging.walr.com/au/demand
Production	https://api.walr.com/au/demand

Authentication

All API requests require authentication using a supplier access token:

supplier-access-token: YOUR_TOKEN

API Reference

Audience Data Structure

The API returns detailed audience information in the following structure:

[
    {
        "id": "d7bda891-8f9c-4fdd-81fa-d4b425f0b419",
        "name": "First Audience - PC batch (1)",
        "audienceStatus": "Live",
        "locale": "eng_gb",
        "countryName": "United Kingdom",
        "languageName": "English",
        "prescreens": false,
        "incidenceRate": 80,
        "quantity": 10,
        "cpi": 0.16,
        "currency": "GBP",
        "lengthOfInterview": 1,
        "surveyGroupId": null,
        "liveUrl": "https://welcome.walr.com/surveyin/asdfsad/1?id=[%RID%]&platform=999",
        "testUrl": "https://welcome.walr.com/surveyin/asdfsad/1?id=[%RID%]&platform=999&t=1",
        "targeting": {
            "type": 1,
            "existingId": null,
            "screenings": [
                {
                    "questionId": "1002",
                    "name": "Gender",
                    "text": "Are you...?",
                    "localizedText": "Are you...?",
                    "isInclude": true,
                    "answers": [
                        {
                            "id": "1",
                            "text": "Male",
                            "localizedText": "Male",
                            "start": null,
                            "end": null
                        },
                        {
                            "id": "2",
                            "text": "Female",
                            "localizedText": "Female",
                            "start": null,
                            "end": null
                        }
                    ]
                }
            ],
            "quotas": null
        },
        "targetEndDate": null,
        "createdUtc": "2024-10-25T11:26:25.4692689Z",
        "lastModifiedUtc": null
    }
]

Field Descriptions

Field	Type	Description
id	string	Unique identifier for the audience
name	string	Name of the audience
audienceStatus	string	Current status of the audience (Active, Paused, Completed)
countryName	string	Country where the audience is targeting
quantity	integer	Target number of completes
cpi	number	Cost per interview
incidenceRate	number	Expected incidence rate percentage
lengthOfInterview	number	Estimated length of interview in minutes
liveUrl	string	URL for live survey
testUrl	string	URL for test survey
createdUtc	string	Creation timestamp in UTC
languageName	string	Primary language of the audience
locale	string	Locale code for the audience
targetEndDate	string	Target completion date in UTC

Targeting Structure

The targeting object contains detailed information about audience criteria:

Quotas

• questionId: Identifier for the quota question
• name: Name of the quota
• text: Question text
• localizedText: Localized version of the question text
• targets: Array of quota targets
  • id: Target identifier
  • targetCompletes: Number of completes for this target
  • answers: Array of answer ranges

Screenings

• questionId: Identifier for the screening question
• name: Name of the screening
• text: Question text
• localizedText: Localized version of the question text
• isInclude: Whether to include or exclude matching answers
• answers: Array of answer ranges

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "details": {
      "field": "quantity",
      "reason": "Must be greater than 0"
    }
  }
}

Common error codes:

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error
• 503 Service Unavailable: Service temporarily unavailable

Best Practices

1. Authentication

   • Store your access token securely
   • Use environment-specific tokens

2. Error Handling

   • Implement proper error handling
   • Log error responses
   • Implement retry logic for transient errors

3. Data Management

   • Cache frequently accessed data

Rate Limits

• 100 requests per minute per token

Support

For additional support:

• Email: support@walr.com
• Status page: https://status.walr.com