> For the complete documentation index, see [llms.txt](https://docs.reviewcraze.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reviewcraze.com/api-version-1.md).

# 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

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

### Error Response

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

## Endpoints

{% stepper %}
{% step %}

### Get Locations

Retrieve all locations associated with your account.

Endpoint: GET /public/v1/locations

Authentication: Required (API Key)

Response:

```json
{
  "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:

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

{% endstep %}

{% step %}

### 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:

```json
{
  "data": [
    {
      "id": 2,
      "name": "Kasun@aa.com",
      "email": "Kasun@aa.com",
      "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": "james@james.com",
      "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:

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

{% endstep %}

{% step %}

### 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:

```json
{
  "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": "Kasun@aa.com",
        "email": "Kasun@aa.com",
        "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": "james@james.com",
        "contactNumber": null
      },
      "location": {
        "id": 1,
        "name": "TWC Innovations (Pvt) Ltd"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}
```

Example Request:

```bash
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'
```

{% endstep %}

{% step %}

### 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:

```json
{
  "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:

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

{% endstep %}
{% endstepper %}

## Data Models

### Location Object

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

### Customer Object

```typescript
{
  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

```typescript
{
  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

```typescript
{
  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

{% stepper %}
{% step %}

### Security

* Never expose your API key in client-side code
* Rotate your API keys periodically
* Use environment variables to store API keys
  {% endstep %}

{% step %}

### Performance

* Use pagination for large datasets
* Cache responses when appropriate
* Implement exponential backoff for retries
* Monitor your API usage
  {% endstep %}

{% step %}

### Error Handling

Always implement proper error handling in your integration:

```javascript
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
}
```

{% endstep %}

{% step %}

### Pagination

When working with paginated endpoints, iterate through all pages:

```javascript
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;
}
```

{% endstep %}
{% endstepper %}

## Support

For API support, please contact:

* Email: <support@reviewcraze.com>
* 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

<details>

<summary>How do I get started with the API?</summary>

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

</details>

<details>

<summary>Can I test the API before implementing?</summary>

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

</details>

<details>

<summary>How do I handle pagination?</summary>

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

</details>

<details>

<summary>What data formats are supported?</summary>

The API returns JSON format only.

</details>

<details>

<summary>How do I report bugs or request features?</summary>

Contact our support team at <support@reviewcraze.com> or submit a ticket through your dashboard.

</details>

*Last Updated: December 21, 2025*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.reviewcraze.com/api-version-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.