v1.0 · REST API · Bearer Auth

Build Faster with Powerful APIs

Access customer insights, survey feedback, and engagement analytics through the RISPOSTA API. Secure, fast, and built for developers — integrate in minutes.

View Documentation Get API Key

99.98% uptime

~80ms latency

request.sh POST

curl -X POST https://api.risposta.app/api/tentativas \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-11-10",
    "end_date": "2025-11-13"
  }'

200 OK 218 attempts · 5 pages

total_attempts

218

Why RISPOSTA API

Everything you need to ship

A developer-first API designed for speed, security, and clarity.

Fast Integration

Authenticate and make your first call in under five minutes with copy-paste examples.

Secure Authentication

Bearer token authentication backed by Laravel Sanctum with token expiration controls.

RESTful Architecture

Predictable, resource-oriented endpoints with standard HTTP verbs and status codes.

Real-time Responses

Aggregated counts, survey stats, and customer data returned in a single fast request.

Developer Friendly

Consistent JSON envelopes, clear error messages, and a downloadable Postman collection.

Detailed Examples

Ready-to-use samples in cURL, PHP, JavaScript, and Python for every endpoint.

Documentation

Try it in your language

Every endpoint comes with ready-to-run examples and a predictable JSON response.

POST /api/tentativas

curl -X POST https://api.risposta.app/api/tentativas \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2025-11-10","end_date":"2025-11-13","page":1}'

$client = new GuzzleHttp\Client();

$response = $client->post('https://api.risposta.app/api/tentativas', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept'        => 'application/json',
    ],
    'json' => [
        'start_date' => '2025-11-10',
        'end_date'   => '2025-11-13',
        'page'       => 1,
    ],
]);

$data = json_decode($response->getBody(), true);

const res = await fetch('https://api.risposta.app/api/tentativas', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    start_date: '2025-11-10',
    end_date: '2025-11-13',
    page: 1,
  }),
});

const data = await res.json();

import requests

res = requests.post(
    "https://api.risposta.app/api/tentativas",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"},
    json={"start_date": "2025-11-10", "end_date": "2025-11-13", "page": 1},
)

data = res.json()

200 OK application/json

{
  "success": true,
  "message": "Tentativas retrieved successfully",
  "data": {
    "counts": {
      "total_attempts": 218,
      "by_time_of_day": { "Morning": 40, "Afternoon": 90, "Night": 88 }
    },
    "by_branch": [
      { "branch_id": 23210, "branch_name": "Sample Branch", "count": 45 }
    ],
    "tentativas": [
      {
        "branch_id": 23210,
        "branch_name": "Sample Branch",
        "business_name": "Sample Business",
        "device_id": 26839,
        "waiter_code": null,
        "timestamp": "2025-11-10T23:33:06.000000Z",
        "time_of_day": "Night"
      }
    ],
    "pagination": {
      "total": 218, "per_page": 50, "current_page": 1,
      "last_page": 5, "from": 1, "to": 50
    }
  },
  "status_code": 200
}

Authentication

Bearer token, the secure way

The RISPOSTA API uses Bearer Token Authentication powered by Laravel Sanctum. Log in to receive an access token, then send it in the Authorization header on every request.

1
Log in at /login with your email and password to receive an access & refresh token.
2
Authorize requests by attaching the token to the header.
3
Refresh expired tokens at /refresh-token without re-entering credentials.

Request header REQUIRED

Authorization: Bearer YOUR_API_TOKEN

POST /login

{
  "access_token": "1|aBcD...XyZ",
  "refresh_token": "2|eFgH...UvW",
  "token_type": "Bearer",
  "expires_at": "2025-11-13T17:00:00.000000Z"
}

Reference

API Endpoints

All endpoints are served from https://api.risposta.app/api

Method	Endpoint	Description	Status
POST	/login	Authenticate a user and issue access & refresh tokens.	Active
POST	/refresh-token	Exchange a valid refresh token for a new access token.	Active
POST	/logout	Revoke the current access token and end the session.	Active
POST	/customers	Retrieve customer records within a date range.	Active
POST	/customers/reports	Customer data enriched with survey & category stats.	Active
POST	/feedbacks/reports	Aggregated feedback reports for registered & anonymous users.	Active
POST	/tentativas	Survey request attempts with counts & pagination.	Active

Lock icon indicates the endpoint requires a Bearer token.

Full Reference

Endpoint details

Parameters, request bodies, and every possible response for each endpoint. All authenticated endpoints expect a Bearer token.

BASE URL https://api.risposta.app/api

POST https://api.risposta.app/api/login Active

Authenticates a user with email and password, returning an access token (valid 60 minutes) and a refresh token (valid 30 days).

Parameters

Name	Type	Required	Description
email	string	required	Registered user email address.
password	string	required	Account password.

Request

{
  "email": "user@example.com",
  "password": "your-password"
}

Responses

200 OK Authenticated

{
  "access_token": "1|aBcD...XyZ",
  "refresh_token": "eFgH...UvW",
  "token_type": "Bearer",
  "expires_at": "2025-11-10T18:00:00.000000Z"
}

401 Unauthorized Invalid credentials

{
  "message": "Invalid credentials"
}

422 Unprocessable Validation error

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

POST https://api.risposta.app/api/refresh-token Active

Issues a new access token (and a rotated refresh token) using a valid refresh token, without re-sending credentials.

Parameters

Name	Type	Required	Description
refresh_token	string	required	The refresh token returned by /login.

Request

{
  "refresh_token": "eFgH...UvW"
}

Responses

200 OK New token issued

{
  "access_token": "3|iJkL...RsT",
  "refresh_token": "mNoP...QwE",
  "token_type": "Bearer",
  "expires_at": "2025-11-10T19:00:00.000000Z"
}

401 Unauthorized Invalid or expired refresh token

{
  "message": "Invalid or expired refresh token"
}

422 Unprocessable Validation error

{
  "message": "The refresh token field is required.",
  "errors": {
    "refresh_token": ["The refresh token field is required."]
  }
}

POST https://api.risposta.app/api/logout Active

Revokes all of the authenticated user's tokens and ends the session. Send the access token in the Authorization header; no request body is required.

Request

Authorization: Bearer YOUR_API_TOKEN

No request body required.

Responses

200 OK Logged out

{
  "message": "Logged out successfully"
}

401 Unauthorized Missing or invalid token

{
  "message": "Unauthenticated."
}

POST https://api.risposta.app/api/customers Active

Retrieves customer records within a date range. The range must not exceed 4 days.

Parameters

Name	Type	Required	Description
start_date	string (date)	required	Start date in YYYY-MM-DD format.
end_date	string (date)	required	End date in YYYY-MM-DD format; on/after start_date, within 4 days.

Request

Authorization: Bearer YOUR_API_TOKEN

{
  "start_date": "2025-11-10",
  "end_date": "2025-11-13"
}

Responses

200 OK Customers retrieved

{
  "success": true,
  "message": "Customers retrieved successfully",
  "data": {
    "total_customer": 27,
    "customers": [
      {
        "email_id": "customer@example.com",
        "buisness_name": "Sample Business",
        "branch_name": "Sample Branch",
        "timestamp": "2025-11-10 06:25:48",
        "name": "John Doe",
        "phone_no": "55(22) 12345678",
        "birthday": "1990-01-01",
        "postcode": "12345"
      }
    ]
  },
  "status_code": 200
}

422 Unprocessable Validation error / range > 4 days

{
  "success": false,
  "message": "Validation Error",
  "errors": {
    "end_date": ["The end date field is required."]
  },
  "status_code": 422
}

403 Forbidden Unauthorized access

{
  "success": false,
  "message": "Unauthorized access",
  "errors": [],
  "status_code": 403
}

POST https://api.risposta.app/api/customers/reports Active

Customer records enriched with survey answers, category scores, and subcategory scores. The range must not exceed 4 days.

Parameters

Name	Type	Required	Description
start_date	string (date)	required	Start date in YYYY-MM-DD format.
end_date	string (date)	required	End date in YYYY-MM-DD format; on/after start_date, within 4 days.

Request

Authorization: Bearer YOUR_API_TOKEN

{
  "start_date": "2025-11-10",
  "end_date": "2025-11-13"
}

Responses

200 OK Customers retrieved

{
  "success": true,
  "message": "Customers retrieved successfully",
  "data": {
    "total_customer": 27,
    "customers": [
      {
        "email_id": "customer@example.com",
        "buisness_name": "Sample Business",
        "branch_name": "Sample Branch",
        "timestamp": "2025-11-10 06:25:48",
        "name": "John Doe",
        "phone_no": "55(22) 12345678",
        "birthday": "1990-01-01",
        "postcode": "12345",
        "survey": {
          "Sua idade": "46 - 55 anos",
          "Genero": "Masculino"
        },
        "categories": {
          "Comida": "10.00",
          "Servico": "10.00"
        },
        "subcategories": {
          "Limpeza": "10.00"
        }
      }
    ]
  },
  "status_code": 200
}

422 Unprocessable Validation error / range > 4 days

{
  "success": false,
  "message": "Validation Error",
  "errors": {
    "message": "The duration between start_date and end_date must not exceed 4 days."
  },
  "status_code": 422
}

403 Forbidden Unauthorized access

{
  "success": false,
  "message": "Unauthorized access",
  "errors": [],
  "status_code": 403
}

POST https://api.risposta.app/api/feedbacks/reports Active

Aggregated feedback reports split into anonymous and registered users, each with survey, category, and subcategory stats. The range must not exceed 4 days.

Parameters

Name	Type	Required	Description
start_date	string (date)	required	Start date in YYYY-MM-DD format.
end_date	string (date)	required	End date in YYYY-MM-DD format; on/after start_date, within 4 days.

Request

Authorization: Bearer YOUR_API_TOKEN

{
  "start_date": "2025-11-10",
  "end_date": "2025-11-13"
}

Responses

200 OK Feedbacks retrieved

{
  "success": true,
  "message": "Feedbacks retrieved successfully",
  "data": {
    "total_users": 42,
    "anonymous_users": [
      {
        "branch_name": "Sample Branch",
        "timestamp": "2025-11-10T20:15:00.000000Z",
        "survey": { "Genero": "Feminino" },
        "categories": { "Comida": "9.00" },
        "subcategories": { "Limpeza": "9.00" }
      }
    ],
    "registered_users": [
      {
        "email_id": "customer@example.com",
        "buisness_name": "Sample Business",
        "branch_name": "Sample Branch",
        "name": "John Doe",
        "phone_no": "55(22) 12345678",
        "birthday": "1990-01-01",
        "postcode": "12345",
        "timestamp": "2025-11-10T20:15:00.000000Z",
        "survey": { "Genero": "Masculino" },
        "categories": { "Comida": "10.00" },
        "subcategories": { "Limpeza": "10.00" }
      }
    ]
  },
  "status_code": 200
}

422 Unprocessable Validation error / range > 4 days

{
  "success": false,
  "message": "Validation Error",
  "errors": {
    "start_date": ["The start date field is required."]
  },
  "status_code": 422
}

403 Forbidden Unauthorized access

{
  "success": false,
  "message": "Unauthorized access",
  "errors": [],
  "status_code": 403
}

POST https://api.risposta.app/api/tentativas Active

Survey request attempts scoped to the user's branches, with time-of-day counts and a paginated list (50 per page). The range must not exceed 4 days.

Parameters

Name	Type	Required	Description
start_date	string (date)	required	Start date in YYYY-MM-DD format.
end_date	string (date)	required	End date in YYYY-MM-DD format; on/after start_date, within 4 days.
page	integer	optional	Page number for the tentativas list. Defaults to 1.

Request

Authorization: Bearer YOUR_API_TOKEN

{
  "start_date": "2025-11-10",
  "end_date": "2025-11-13",
  "page": 1
}

Responses

200 OK Tentativas retrieved

{
  "success": true,
  "message": "Tentativas retrieved successfully",
  "data": {
    "counts": {
      "total_attempts": 218,
      "by_time_of_day": { "Morning": 40, "Afternoon": 90, "Night": 88 }
    },
    "by_branch": [
      {
        "branch_id": 23210,
        "branch_name": "Sample Branch",
        "count": 45
      }
    ],
    "tentativas": [
      {
        "branch_id": 23210,
        "branch_name": "Sample Branch",
        "business_name": "Sample Business",
        "device_id": 26839,
        "waiter_code": null,
        "timestamp": "2025-11-10T23:33:06.000000Z",
        "time_of_day": "Night"
      }
    ],
    "pagination": {
      "total": 218, "per_page": 50, "current_page": 1,
      "last_page": 5, "from": 1, "to": 50
    }
  },
  "status_code": 200
}

422 Unprocessable Validation error / range > 4 days

{
  "success": false,
  "message": "Validation Error",
  "errors": {
    "message": "The duration between start_date and end_date must not exceed 4 days."
  },
  "status_code": 422
}

403 Forbidden Unauthorized access

{
  "success": false,
  "message": "Unauthorized access",
  "errors": [],
  "status_code": 403
}

Integrations

Works with your stack

Drop-in examples and clients for the most popular languages and frameworks.

PHP

Guzzle / cURL

Laravel

HTTP Client

Vue

Composition API

React

Hooks / fetch

Node.js

axios / fetch

Prefer Postman?

Import the full collection and start testing every endpoint in seconds.

Download Postman Collection