API Version 1

Base URL

https://reviewcraze.com/api

Authentication

The ReviewCraze API uses API key authentication for public endpoints. Include your API key in the request header:

x-api-key: YOUR_API_KEY

Getting Your API Key

1. Log in to your ReviewCraze account

2. Navigate to Profile Settings

3. Click "Generate API Key" or "Regenerate API Key"

4. Copy and securely store your API key

Response Format

All API responses follow a consistent JSON structure:

Success Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

Error Response

{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

Endpoints

1

Get Locations

Retrieve all locations associated with your account.

Endpoint: GET /public/v1/locations

Authentication: Required (API Key)

Response:

{
  "data": [
    {
      "id": 1,
      "name": "TWC Innovations (Pvt) Ltd",
      "isDefault": true,
      "createdAt": "2025-12-20T18:08:41.071Z",
      "updatedAt": "2025-12-20T18:09:08.816Z"
    }
  ],
  "total": 1
}

Example Request:

curl -X GET 'https://reviewcraze.com/api/public/v1/locations' \
  -H 'x-api-key: YOUR_API_KEY'

2

Get Customers

Retrieve a paginated list of customers with optional filtering.

Endpoint: GET /public/v1/customers

Authentication: Required (API Key)

Query Parameters:

Parameter	Type	Required	Default	Description
locationId	number	Yes	-	The location ID to filter customers
page	number	No	1	Page number for pagination
limit	number	No	10	Number of results per page
search	string	No	-	Search term for customer name or email
marketingConsent	boolean	No	-	Filter by marketing consent status

Response:

{
  "data": [
    {
      "id": 2,
      "name": "[email protected]",
      "email": "[email protected]",
      "contactNumber": null,
      "marketingConsent": true,
      "locationId": 1,
      "createdAt": "2025-12-20T18:25:17.062Z",
      "updatedAt": "2025-12-20T18:25:17.062Z",
      "location": {
        "id": 1,
        "name": "TWC Innovations (Pvt) Ltd"
      }
    },
    {
      "id": 1,
      "name": "James",
      "email": "[email protected]",
      "contactNumber": null,
      "marketingConsent": true,
      "locationId": 1,
      "createdAt": "2025-12-20T18:23:32.570Z",
      "updatedAt": "2025-12-20T18:23:32.570Z",
      "location": {
        "id": 1,
        "name": "TWC Innovations (Pvt) Ltd"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

Example Request:

curl -X GET 'https://reviewcraze.com/api/public/v1/customers?locationId=1&page=1&limit=10' \
  -H 'x-api-key: YOUR_API_KEY'

3

Get Reviews

Retrieve a paginated list of reviews with optional filtering.

Endpoint: GET /public/v1/reviews

Authentication: Required (API Key)

Query Parameters:

Parameter	Type	Required	Default	Description
locationId	number	Yes	-	The location ID to filter reviews
page	number	No	1	Page number for pagination
limit	number	No	10	Number of results per page

Response:

{
  "data": [
    {
      "id": 2,
      "rating": 1,
      "review": "Bad",
      "sentiment": "TERRIBLE",
      "flow": "LINK",
      "origin": null,
      "locationId": 1,
      "createdAt": "2025-12-20T18:25:21.454Z",
      "updatedAt": "2025-12-20T18:25:21.454Z",
      "customer": {
        "id": 2,
        "name": "[email protected]",
        "email": "[email protected]",
        "contactNumber": null
      },
      "location": {
        "id": 1,
        "name": "TWC Innovations (Pvt) Ltd"
      }
    },
    {
      "id": 1,
      "rating": 5,
      "review": null,
      "sentiment": "EXCELLENT",
      "flow": "LINK",
      "origin": null,
      "locationId": 1,
      "createdAt": "2025-12-20T18:23:33.113Z",
      "updatedAt": "2025-12-20T18:23:33.113Z",
      "customer": {
        "id": 1,
        "name": "James",
        "email": "[email protected]",
        "contactNumber": null
      },
      "location": {
        "id": 1,
        "name": "TWC Innovations (Pvt) Ltd"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

Example Request:

curl -X GET 'https://reviewcraze.com/api/public/v1/reviews?locationId=1&rating=5&page=1&limit=10' \
  -H 'x-api-key: YOUR_API_KEY'

4

Get Statistics

Retrieve comprehensive statistics for your locations.

Endpoint: GET /public/v1/stats

Authentication: Required (API Key)

Query Parameters:

Parameter	Type	Required	Default	Description
locationId	number	No	-	Filter stats by specific location (omit for all locations)

Response:

{
  "overview": {
    "totalLocations": 1,
    "totalCustomers": 2,
    "totalReviews": 2,
    "averageRating": 3
  },
  "ratings": [
    {
      "rating": 5,
      "count": 1
    },
    {
      "rating": 1,
      "count": 1
    }
  ],
  "sentiments": [
    {
      "sentiment": "EXCELLENT",
      "count": 1
    },
    {
      "sentiment": "TERRIBLE",
      "count": 1
    }
  ],
  "flows": [
    {
      "flow": "LINK",
      "count": 2
    }
  ]
}

Example Request:

curl -X GET 'https://reviewcraze.com/api/public/v1/stats?locationId=1' \
  -H 'x-api-key: YOUR_API_KEY'

Data Models

Location Object

{
  id: number;
  name: string;
  isDefault: boolean;
  createdAt: string; // ISO 8601 timestamp
  updatedAt: string; // ISO 8601 timestamp
}

Customer Object

{
  id: number;
  name: string;
  email: string;
  contactNumber: string | null;
  marketingConsent: boolean;
  locationId: number;
  createdAt: string; // ISO 8601 timestamp
  updatedAt: string; // ISO 8601 timestamp
  location: {
    id: number;
    name: string;
  };
}

Review Object

{
  id: number;
  rating: number; // 1-5
  review: string | null;
  sentiment: "EXCELLENT" | "GOOD" | "NEUTRAL" | "BAD" | "TERRIBLE";
  flow: "LINK" | "QR";
  origin: string | null;
  locationId: number;
  createdAt: string; // ISO 8601 timestamp
  updatedAt: string; // ISO 8601 timestamp
  customer: {
    id: number;
    name: string;
    email: string;
    contactNumber: string | null;
  };
  location: {
    id: number;
    name: string;
  };
}

Stats Object

{
  overview: {
    totalLocations: number;
    totalCustomers: number;
    totalReviews: number;
    averageRating: number;
  };
  ratings: Array<{
    rating: number;
    count: number;
  }>;
  sentiments: Array<{
    sentiment: string;
    count: number;
  }>;
  flows: Array<{
    flow: string;
    count: number;
  }>;
}

Error Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Best Practices

1

Security

• Never expose your API key in client-side code

• Rotate your API keys periodically

• Use environment variables to store API keys

2

Performance

• Use pagination for large datasets

• Cache responses when appropriate

• Implement exponential backoff for retries

• Monitor your API usage

3

Error Handling

Always implement proper error handling in your integration:

try {
  const response = await fetch('https://reviewcraze.com/api/public/v1/locations', {
    headers: {
      'x-api-key': process.env.REVIEWCRAZE_API_KEY
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  const data = await response.json();
  // Process data
} catch (error) {
  console.error('API request failed:', error);
  // Handle error appropriately
}

4

Pagination

When working with paginated endpoints, iterate through all pages:

async function getAllCustomers(locationId) {
  let allCustomers = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://reviewcraze.com/api/public/v1/customers?locationId=${locationId}&page=${page}&limit=100`,
      {
        headers: { 'x-api-key': process.env.REVIEWCRAZE_API_KEY }
      }
    );
    
    const data = await response.json();
    allCustomers = allCustomers.concat(data.data);
    
    hasMore = page < data.pagination.totalPages;
    page++;
  }
  
  return allCustomers;
}

Support

For API support, please contact:

• Email: [email protected]

• Documentation: https://docs.reviewcraze.com

Changelog

Version 1.0.0 (Current)

• Initial public API release

• Support for locations, customers, reviews, and stats endpoints

• API key authentication

• Pagination support

FAQ

How do I get started with the API?

1. Sign up for a ReviewCraze account

2. Generate your API key from Profile Settings

3. Make your first API call using the examples above

4. Review the documentation for available endpoints

Can I test the API before implementing?

Yes, use tools like Postman, Insomnia, or cURL to test API endpoints before implementing in your application.

How do I handle pagination?

Use the page and limit query parameters. The response includes pagination metadata showing total pages and records.

What data formats are supported?

The API returns JSON format only.

How do I report bugs or request features?

Contact our support team at [email protected] or submit a ticket through your dashboard.

Last Updated: December 21, 2025