Skip to main content

Buyer

This guide will walk you through the process of setting up Audiences programmatically in Walr.

Prerequisites​

  • A valid bearer token for your customer in the request authorization header. You can find more on how to obtain this here.

Introduction​

This documentation provides an overview of the Buyers API, designed for external partners to create and access Walr Audiences/Samples. The API initially allows external clients to create surveys with "natrep" as targeting.

Getting Started​

Base URL​

Authentication​

To use the API, you need an API key. Include your API key in the request header as shown below:

Authorization: Bearer YOUR_API_KEY

Further authentication details: Getting started with the Walr Platform | Walr Docs

Available Functionality​

  • Create a Project
  • Get Project Details
  • Create Sample
  • Get Sample Details
  • Update Sample
  • Get Sample Pricing
  • Get Sample Feasibility
  • Accept Sample Pricing
  • Launch Sample
  • Hold Sample
  • Close Sample

Typical Workflow​

  1. Create a project (if not already created).
  2. Create a sample, using the Project ID from #1.
  3. The sample will be processed by Walr.
  4. Check the Sample status (#3 Get Sample Details) for BuyerStatus: Accepted.
  5. If the status is "Accepted" and the price is acceptable, accept the price using #8 Accept Sample Pricing.
  6. Launch the sample using #9 Launch Sample.

Endpoints and Details​

1. Create a Project​

  • Endpoint: POST /projects
  • Description: Creates a new project.
  • Request Body:
    {
        "name": "New Project",
        "description": "Description of the project"
    }
  • Response:
    201 Created: Project successfully created. Returns the project details.

2. Get Project Details​

  • Endpoint: GET /projects/{projectid}
  • Description: Retrieves details about a specific project. Use the query parameter includeAudiences=true to also retrieve all samples in the project.
  • Request Parameters:
    • projectid (string, required): The ID of the project.
    • includeAudiences (boolean, optional): Set to true to include samples.
  • Response:
    200 OK: Returns project details.

3. Create Sample​

  • Endpoint: POST /projects/{projectid}/samples
  • Description: Creates a new sample within a project.
  • Request Parameters:
    • projectid (string, required): The ID of the project.
  • Request Body Sample:
    {
      "name": "string",
      "market": "string",
      "quantity": 0,
      "incidenceRate": 0,
      "lengthOfInterview": 0,
      "liveUrl": "string",
      "testUrl": "string",
      "containsPersonalData": true,
      "notes": "string",
      "targeting": {
        "type": "None",
        "existingId": "string",
        "screenings": [
          {
            "questionId": "string",
            "isInclude": true,
            "answers": [
              {
                "id": "string",
                "start": 0,
                "end": 0
              }
            ]
          }
        ],
        "quotas": [
          {
            "questionId": "string",
            "targets": [
              {
                "id": "string",
                "targetCompletes": 0,
                "answers": [
                  {
                    "id": "string",
                    "start": 0,
                    "end": 0
                  }
                ]
              }
            ]
          }
        ]
      },
      "targetEndDate": "2024-12-17T13:08:42.113Z"
    }
  • Response:
    201 Created: Sample successfully created. Returns the sample details.

4. Get Sample Details​

  • Endpoint: GET /projects/{projectid}/samples/{sampleId}
  • Description: Retrieves details about a specific sample within a project. The response includes a BuyerStatus property with possible values:
    • None
    • Submitted
    • Accepted
    • Declined
    • Live
    • Paused
    • Cancelled
    • InReconciliation
    • Completed
  • Request Parameters:
    • projectid (string, required): The ID of the project.
    • sampleId (string, required): The ID of the sample.
  • Response:
    200 OK: Returns sample details.

5. Update Sample​

  • Endpoint: PUT /projects/{projectid}/samples/{sampleId}
  • Description: Updates a specific sample within a project.
  • Request Parameters:
    • projectid (string, required): The ID of the project.
    • sampleId (string, required): The ID of the sample.
  • Request Body:
    {
        "sample_name": "Updated Sample",
        "sample_size": 150,
        "targeting_criteria": "updated_criteria"
    }
  • Response:
    • 200 OK: Sample successfully updated. Returns the updated sample details.

6. Get Sample Pricing​

  • Endpoint: GET /projects/{projectid}/samples/{sampleId}/price
  • Description: Retrieves pricing details about a specific sample.
  • Request Parameters:
    • projectid (string, required): The ID of the project.
    • sampleId (string, required): The ID of the sample.
  • Response:
    {
      "name": "string",
      "id": "string",
      "currency": "string",
      "price": 0,
      "priceKey": "string"
    }
    • 200 OK: Returns sample pricing details.

Note: The priceKey is vital in step 8 (Accept Sample Pricing).

7. Get Sample Feasibility​

  • Endpoint: GET /projects/{projectid}/samples/{sampleId}/feasible
  • Description: Retrieves feasibility details about a specific sample.
  • Request Parameters:
    • projectid (string, required): The ID of the project.
    • sampleId (string, required): The ID of the sample.
  • Response:
    • 200 OK: Returns sample feasibility details.

8. Accept Sample Pricing​

  • Endpoint: PUT /projects/{projectid}/samples/{sampleId}/acceptprice
  • Description: Accepts the specified price for a sample.
  • Request Parameters:
    • projectid (string, required): The ID of the project.
    • sampleId (string, required): The ID of the sample.
  • Request Body:
    {
      "priceKey": "string"
    }
  • Response:
    • 200 OK: Price accepted.

Typical Responses​

Common Error Responses:​

  • 400 Bad Request: The request could not be understood by the server due to malformed syntax.
  • 401 Unauthorized: Authentication failed or user does not have permissions for the desired action.
  • 403 Forbidden: Access denied.
  • 404 Not Found: The requested resource could not be found.
  • 500 Internal Server Error: An unexpected error occurred on the server.
  • 503 Service Unavailable: The service is temporarily unavailable.