First API Call

Learn how to make your first API call to Pullbay and understand the response structure. This hands-on guide shows you real code examples and explains every step.

Prerequisites

Before making your first API call, ensure you have:

• A Pullbay account (sign up at https://dashboard.pullbay.com)

• Your API key copied from the API Keys section of your dashboard

• A tool for making HTTP requests (cURL, Postman, programming language, etc.)

• Basic familiarity with JSON responses

The Example Request

We'll fetch App Store reviews for Facebook (App Store ID: 284882215) to demonstrate a real API call.

• Endpoint: GET https://api.pullbay.com/appstore/reviews

• Parameters: appId=284882215 (Facebook's iOS App Store ID)

• Authentication: Header Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key.

cURL

curl -X GET "https://api.pullbay.com/appstore/reviews?appId=284882215" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python (requests library)

import requests

api_key = "YOUR_API_KEY"
url = "https://api.pullbay.com/appstore/reviews"
params = {"appId": "284882215"}
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)

Node.js (Axios)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const url = 'https://api.pullbay.com/appstore/reviews';
const params = { appId: '284882215' };
const headers = { 'Authorization': `Bearer ${apiKey}` };

async function getReviews() {
  try {
    const response = await axios.get(url, { params, headers });
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

getReviews();

Node.js (Native Fetch)

const apiKey = 'YOUR_API_KEY';
const url = 'https://api.pullbay.com/appstore/reviews?appId=284882215';

const response = await fetch(url, {
  method: 'GET',
  headers: { 'Authorization': `Bearer ${apiKey}` },
});

const data = await response.json();
console.log(data);

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$appId = '284882215';

$url = 'https://api.pullbay.com/appstore/reviews?appId=' . $appId;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: HTTP $httpCode\n";
    echo "Response: $response\n";
}
?>

Understanding the Response

Here's what a successful response from this API call looks like:

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "10293847561",
      "date": "2026-01-15T10:30:00Z",
      "userName": "HappyUser123",
      "userUrl": "https://itunes.apple.com/us/reviews/id1632846422",
      "version": "5.2.1",
      "score": 5,
      "title": "Great app!",
      "text": "This app has changed how I work. The interface is intuitive and features are powerful. Highly recommended!",
      "url": "https://itunes.apple.com/us/review?id=284882215",
      "country": "US"
    },
    {
      "id": "10293847562",
      "date": "2026-01-14T15:45:00Z",
      "userName": "CriticalReviewer",
      "userUrl": "https://itunes.apple.com/us/reviews/id1632846423",
      "version": "5.2.0",
      "score": 3,
      "title": "Good but needs work",
      "text": "The core features are solid and the performance is decent. However, the app could use better error handling and more customization options.",
      "url": "https://itunes.apple.com/us/review?id=284882215",
      "country": "US"
    },
    {
      "id": "10293847563",
      "date": "2026-01-13T08:15:00Z",
      "userName": "BugHunter42",
      "userUrl": "https://itunes.apple.com/us/reviews/id1632846424",
      "version": "5.2.0",
      "score": 2,
      "title": "Crashes on startup",
      "text": "The app keeps crashing when I try to open it on iOS 17. This happened after the last update. Please fix!",
      "url": "https://itunes.apple.com/us/review?id=284882215",
      "country": "US"
    }
  ],
  "pagination": {
    "page": 1,
    "hasNextPage": true,
    "cursor": null,
    "offset": null
  },
  "pricing": {
    "creditsCharged": 4
  }
}

Response Field Explanations

The response contains a top-level envelope plus data, pagination, and pricing.

Top level

Field	Type	Description
requestId	String	Unique identifier for this request (useful for debugging and support)
status	Integer	HTTP status code
message	String	Human-readable status message
success	Boolean	Whether the request succeeded

data (Array)

Each review object has these fields:

Field	Type	Description
id	String	Unique identifier for this review
date	ISO 8601	Timestamp when the review was posted
userName	String	Username or display name of the reviewer
userUrl	String	URL to the reviewer's profile
version	String	App version the reviewer was using
score	Integer	Star rating given by the reviewer (1–5)
title	String	Review title or headline
text	String	Full text of the review
url	String	URL to the review
country	String	Country code of the review

pagination (Object)

Field	Type	Description
page	Integer	Current page number
hasNextPage	Boolean	true if more pages are available
cursor / offset	String	Used only by cursor-/offset-paginated services (e.g. Google Maps); null for App Store

pricing (Object)

Field	Type	Description
creditsCharged	Integer	API credits consumed by this request (1 per request + 1 per item returned)

Fetching More Pages

When pagination.hasNextPage is true, fetch the next page by incrementing page:

cURL

curl -X GET "https://api.pullbay.com/appstore/reviews?appId=284882215&page=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

# Fetch the first page
response1 = requests.get(url, params=params, headers=headers)
data1 = response1.json()

# Check if more results are available
if data1["pagination"]["hasNextPage"]:
    params["page"] = 2
    response2 = requests.get(url, params=params, headers=headers)
    data2 = response2.json()

    all_reviews = data1["data"] + data2["data"]
    print(f"Fetched {len(all_reviews)} reviews total")

Node.js

// Fetch the first page
const response1 = await axios.get(url, {
  params: { appId: '284882215' },
  headers,
});
const data1 = response1.data;

// Check if more results are available
if (data1.pagination.hasNextPage) {
  const response2 = await axios.get(url, {
    params: { appId: '284882215', page: 2 },
    headers,
  });
  const data2 = response2.data;

  const allReviews = [...data1.data, ...data2.data];
  console.log(`Fetched ${allReviews.length} reviews total`);
}

Alternatively, use maxItems instead of page to pull a larger set in a single call (the two are mutually exclusive).

Check Your Usage in the Dashboard

1

Sign in

Sign in to https://dashboard.pullbay.com

2

Open Overview

Open your Overview to see your remaining credits

3

View Usage

Click Usage to see detailed request history: number of requests, breakdown by endpoint, requests over time, and credits consumed

Common Errors & Troubleshooting

All errors return the standard envelope with success: false and an error object:

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": {
    "code": "BAD_REQUEST"
  }
}

400 Bad Request — Invalid or missing parameters. Verify required parameters are included (e.g. appId or bundleId) and values are correct (app IDs are numeric strings, 8–12 digits).

402 Insufficient Credits — You've used all your available credits. Check your remaining credits in the Overview, then purchase more or upgrade your plan.

404 Not Found — The requested resource (e.g. an app or developer ID) couldn't be found. Verify the identifier.

401 Unauthorized — Your API key is missing, invalid, or expired. Verify it's copied correctly and sent as Authorization: Bearer YOUR_API_KEY. If compromised, revoke it and create a new one.

429 Too Many Requests — You've hit a rate limit. Wait before retrying and implement exponential backoff.

500 / 503 Server Error — A server-side error or temporary unavailability. Retry after a few seconds; if it persists, contact support with your requestId.

Error Reference Table

Status	Message	Action
400	Bad request	Verify request parameters
402	Insufficient credits	Purchase more credits
404	Not found	Verify the identifier
401	Unauthorized	Check your API key
429	Too many requests	Wait and retry with backoff
500 / 503	Server error / unavailable	Retry or contact support

Next Steps

Congratulations on making your first Pullbay API call! Here's what to explore next:

1

Pagination Guide

Page-based pagination and bulk pulls with maxItems

2

Authentication Guide

API keys and security best practices

3

App Store API Reference

Explore all available endpoints and parameters

4

Error Handling

Implement robust error handling in your application

FAQ

How do I find an app's ID?

iOS App IDs appear in the App Store URL — for https://apps.apple.com/app/facebook/id284882215, the ID is 284882215. You can also pass a bundleId (e.g. com.burbn.instagram) instead of appId.

What does appId 284882215 refer to?

284882215 is the official Apple App Store ID for Facebook. We use it as a demonstration because it's a well-known, widely available app with many reviews. You can replace it with any app ID to fetch reviews for other applications.

Can I fetch reviews for apps on different app stores?

Yes. Different services serve different stores:

• iOS reviews: GET /api/appstore/reviews (use the iOS appId or bundleId)

• Android reviews: GET /api/google-play/reviews (use the package name)

Check the API Reference for endpoint-specific documentation.

How often are reviews updated?

Reviews are refreshed regularly (typically within 24 hours of being posted). Check your dashboard or contact support for the refresh schedule for your account.

What if I make the same request twice?

You'll get fresh data, not cached results. Each request consumes credits (1 per request + 1 per item returned) and may return different reviews if new ones have been posted. There's no automatic deduplication, so account for that if you make repeated requests for the same data.

Can I filter reviews by rating or date?

The App Store reviews endpoint doesn't support rating or date filters. It supports sort (recent or helpful), country, and pagination via page / maxItems. Filtering and sorting options vary by endpoint, so check each endpoint's reference page.