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