Introduction to the Walr Buyer API

This guide provides a comprehensive overview of the Walr Buyer API, which enables programmatic creation and management of Walr Audiences and Samples. The API allows external partners to integrate Walr's audience targeting capabilities directly into their applications and workflows.

Quick Start

1. Obtain your API credentials
2. Set up your first project
3. Create and manage samples
4. Monitor and control your samples

Prerequisites

Before you begin, ensure you have:

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

To obtain your bearer token, follow the instructions in our authentication guide.

API Overview

The Walr Buyer API provides a complete set of endpoints for managing the entire lifecycle of audience samples. Key features include:

• Project Management: Create and manage research projects
• Sample Creation: Define and configure audience samples with detailed targeting criteria
• Pricing & Feasibility: Get real-time pricing and feasibility information
• Sample Control: Launch, pause, and close samples programmatically

Getting Started

Base URLs

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

Authentication

All API requests require authentication using a bearer token:

Authorization: Bearer YOUR_API_KEY

Typical Workflow

The Buyer API follows a structured workflow for creating and managing samples. Here's a detailed breakdown of the typical process:

1. Project Setup

   • Create a new project using the Create Project endpoint
   • Store the returned Project ID for subsequent operations

2. Sample Creation

   • Create a sample within your project using the Project ID
   • Define targeting criteria, screening questions, and quotas
   • Specify sample size, incidence rate, and length of interview
   • Set test and live URLs for your survey

3. Sample Review Process

   • The sample will be processed by Walr's system
   • Monitor the sample status using Get Sample Details
   • Possible status transitions:
     • Submitted → Accepted/Declined
     • Accepted → Live (after price acceptance)
     • Live → Paused/Completed

4. Pricing and Feasibility

   • Check sample feasibility using Get Sample Feasibility
   • Review pricing details using Get Sample Pricing
   • The price is valid for a limited time (indicated by the priceKey)

5. Sample Activation

   • If the price is acceptable, accept it using Accept Sample Pricing
   • Launch the sample using Launch Sample
   • Monitor the sample's progress through Get Sample Details

6. Sample Management

   • Use Update Sample to modify parameters if needed
   • Hold Sample to temporarily pause data collection
   • Close Sample when data collection is complete

Status Flow Diagram

Submitted → Accepted → Live → Completed
     ↓          ↓         ↓
  Declined    Paused   InReconciliation

API Reference

1. Create a Project

Creates a new project in your account.

Endpoint: POST /projects

Request Body:

{
    "name": "New Project",
    "description": "Description of the project"
}

Response: 201 Created

{
    "id": "project-123",
    "name": "New Project",
    "description": "Description of the project",
    "createdAt": "2024-01-01T00:00:00Z"
}

2. Get Project Details

Retrieves details about a specific project.

Endpoint: GET /projects/{projectid}

Query Parameters:

• includeAudiences (boolean, optional): Include samples in the response

Response: 200 OK

{
    "id": "project-123",
    "name": "New Project",
    "description": "Description of the project",
    "samples": [
        {
            "id": "sample-456",
            "name": "Sample 1",
            "status": "Live"
        }
    ]
}

3. Create Sample

Creates a new sample within a project.

Endpoint: POST /projects/{projectid}/samples

Request Body:

{
    "name": "My Sample",
    "market": "eng_us",
    "quantity": 1000,
    "incidenceRate": 90,
    "lengthOfInterview": 15,
    "liveUrl": "https://example.com/live",
    "testUrl": "https://example.com/test",
    "containsPersonalData": false,
    "notes": "Sample notes",
    "targeting": {
        "type": "NatRep"
    },
    "targetEndDate": "2024-12-31T23:59:59Z",
    "panelSources": [
        "A"
    ]
}

Response: 201 Created

{
    "id": "sample-456",
    "name": "My Sample",
    "status": "Submitted",
    "createdAt": "2024-01-01T00:00:00Z"
}

4. Get Sample Details

Retrieves details about a specific sample.

Endpoint: GET /projects/{projectid}/samples/{sampleId}

Response: 200 OK

{
    "id": "sample-456",
    "name": "My Sample",
    "status": "Accepted",
    "market": "eng_us",
    "quantity": 1000,
    "incidenceRate": 90,
    "lengthOfInterview": 15,
    "liveUrl": "https://example.com/live",
    "testUrl": "https://example.com/test",
    "containsPersonalData": false,
    "notes": "Sample notes",
    "targeting": {
        "type": "NatRep"
    },
    "panelSources": [
        "A"
    ],
    "targetEndDate": "2024-12-31T23:59:59Z",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
}

5. Update Sample

Updates an existing sample.

Endpoint: PUT /projects/{projectid}/samples/{sampleId}

Request Body:

{
  "name": "US National Study",
  "market": "eng_us",
  "containsPersonalData": true,
  "notes": "Client requested fast turnaround",
  "liveUrl": "https://survey.example.com/live",
  "testUrl": "https://survey.example.com/test",
  "quantity": 1000,
  "incidenceRate": 35,
  "lengthOfInterview": 15,
  "targetEndDate": "2025-05-01T00:00:00Z",
  "etag": "W/\"123456789\""
}

6. Get Sample Pricing

Retrieves pricing information for a sample.

Endpoint: GET /projects/{projectid}/samples/{sampleId}/price

Response: 200 OK

{
    "name": "My Sample",
    "id": "sample-456",
    "currency": "USD",
    "price": 5000.00,
    "priceKey": "A123DSD789"
}

7. Get Sample Feasibility

Checks the feasibility of a sample.

Endpoint: GET /projects/{projectid}/samples/{sampleId}/feasible

Response: 200 OK

{
    "feasibilityStatus": "Feasible"
}

8. Accept Sample Pricing

Accepts the pricing for a sample.

Endpoint: PUT /projects/{projectid}/samples/{sampleId}/acceptprice

Request Body:

{
    "priceKey": "A123DSD789"
}

Response: 200 OK

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 API key securely
   • Use environment-specific keys

2. Error Handling

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

3. Sample Management

   • Monitor sample status regularly

4. Performance

   • Cache project and sample details
   • Implement rate limiting

Rate Limits

• 100 requests per minute per API key
• 1000 requests per hour per API key
• Rate limit headers included in responses

Support

For additional support:

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