Create an invitation
POSThttps://api.reviewit.gr/v1/invitations
Authenticate with the business's API key (Authorization: Bearer rvk_...), not with a session. With the test key (rvk_test_...) the response is the same, with test: true, but nothing is stored, sent or counted against the limit.
Send only the customer's email, their first name (optional) and the order number. The email is sent after the delay the business has set (24 hours by default) and the address is deleted as soon as it is sent, at the latest within 30 days. The same order is not sent twice, so retrying a call is safe.
If the order or the customer has already been invited (by the same business in the last 90 days), the response is 200 with state: skipped and a reason (duplicate, repeat). Nothing is sent to anyone who has asked not to receive invitations (from any business) or who has already written a review of the business, but the response is the same 202 as for a real invitation: no business is told who has reviewed it or opted out.
The business must have turned on invitations and confirmed that it tells its customers (403 invitations_disabled), have a plan (403 plan_required), and not have reached its plan's monthly limit (429 monthly_limit: Basic 300, Pro 1000, Premium 5000, Enterprise no limit).
Parameters
Headers
Authorizationstring requiredBearer YOUR_API_KEYThe business's API key (rvk_...), which the owner creates on the «My business» page
Content-Typestring requiredapplication/jsonThe body of the request is JSON.
Request body
emailstringemailrequiredThe customer's email
firstNamestringup to 80 charactersThe customer's first name (optional)
orderRefstringup to 100 charactersrequiredYour shop's order number: one invitation per order
Example request
curl -X POST https://api.reviewit.gr/v1/invitations \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"email":"customer@example.gr","firstName":"Maria","orderRef":"1001"}'<?php$ch = curl_init('https://api.reviewit.gr/v1/invitations');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'email' => 'customer@example.gr', 'firstName' => 'Maria', 'orderRef' => '1001', ]),]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status . ' ' . $body;// Node.js 18 or newer(async () => { const res = await fetch('https://api.reviewit.gr/v1/invitations', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ email: 'customer@example.gr', firstName: 'Maria', orderRef: '1001', }), signal: AbortSignal.timeout(10_000), });
console.log(res.status, await res.json());})();import requests
res = requests.post( "https://api.reviewit.gr/v1/invitations", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "email": "customer@example.gr", "firstName": "Maria", "orderRef": "1001", }, timeout=10,)
print(res.status_code, res.json())// Java 11 or newerimport java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.time.Duration;
public class Invite { public static void main(String[] args) throws Exception { String json = "{\"email\":\"customer@example.gr\",\"firstName\":\"Maria\",\"orderRef\":\"1001\"}";
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.reviewit.gr/v1/invitations")) .timeout(Duration.ofSeconds(10)) .header("Authorization", "Bearer YOUR_API_KEY") .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build();
HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body()); }}package main
import ( "fmt" "io" "net/http" "strings" "time")
func main() { body := `{"email":"customer@example.gr","firstName":"Maria","orderRef":"1001"}`
req, err := http.NewRequest("POST", "https://api.reviewit.gr/v1/invitations", strings.NewReader(body)) if err != nil { panic(err) } req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close()
out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out))}Replace YOUR_API_KEY. Start with the test key: nothing is sent.
Responses
200
Nothing will be sent (skipped): the order or the customer has already been invited
statestringskippedreasonstringduplicaterepeattestboolean
{ "state": "skipped", "reason": "duplicate"}202
The invitation was queued for sending
statestringqueuedtestbooleanOnly with the test key: nothing was queued
{ "state": "queued"}401
The API key is missing or wrong
403
invitations_disabled or plan_required
422
Invalid field: validation_failed, with the field and a message
errorstringvalidation_failedfieldstringmessagestring
{ "error": "validation_failed", "field": "email", "message": "Invalid email address"}429
monthly_limit: the plan's monthly limit has been reached
What to do for each response: responses and errors.