Partner API

Connect your store's own system to MezuSafe — verify mezuzot, manage inventory, and record sales programmatically.

Base URL

https://mezusafe-backend.jourist.cloud

Authentication

Public endpoints need no authentication. Store endpoints require your API key in the X-Api-Key header — generate one from Account Settings → Settings → API Key. Shown once at creation time, so store it securely.

Header
X-Api-Key: YOUR_API_KEY
Every endpoint is rate-limited (see each endpoint below) — exceeding the limit returns HTTP 429 with: {"error": "rate_limit_exceeded"}

Public Endpoints

No authentication required. Rate-limited by IP address.

POST

/api/v1/public/check-mezuzah

Check a Mezuzah

Public — no auth10 requests / minute / IP

Upload a photo of a mezuzah to check whether it is already registered, and get back its certification details if so. This is the same check used by the "Check Your Mezuzah" tool on the MezuSafe website.

Form Fields

image

file
required

Photo of the mezuzah scroll

Possible Errors
400

{"msg":"No matches found.","status":"not_found"}

No registered mezuzah matches the photo.
400

{"msg":"You uploaded invalid image!","status":"invalid"}

The scroll text could not be read from the photo.
curl -X POST "https://mezusafe-backend.jourist.cloud/api/v1/public/check-mezuzah" \
  -F "image=@/path/to/mezuzah.jpg"
Example response · 200
{
  "status": "success",
  "uuid": "k7Qz9pXsN3vT2m",
  "preview_url": "static/mezuzah/preview/k7Qz9pXsN3vT2m.jpg",
  "create_time": "2025-01-15 10:30:00",
  "examinated_time": "2025-01-10 00:00:00",
  "font": "Beit Yosef",
  "owner": {
    "username": "Chaim Levi",
    "lat": 40.7128,
    "lng": -74.006,
    "country": "USA",
    "role": "user",
    "uuid": "a1B2c3D4e5"
  },
  "sofer": "Yosef Cohen",
  "megiah": "David Katz"
}
POST

/api/v1/public/compare-mezuzot

Compare Two Mezuzot

Public — no auth10 requests / minute / IP

Upload two mezuzah photos to check whether they are photos of the same physical scroll.

Form Fields

image1

file
required

First photo

image2

file
required

Second photo

Possible Errors
200

{"msg":"please select correct images","status":"invalid"}

One or both photos didn't contain a readable scroll.
curl -X POST "https://mezusafe-backend.jourist.cloud/api/v1/public/compare-mezuzot" \
  -F "image1=@/path/to/mezuzah-a.jpg" \
  -F "image2=@/path/to/mezuzah-b.jpg"
Example response · 200
{
  "similarity": 92.4,
  "is_matched": true,
  "status": "success"
}
GET

/api/v1/public/scan-qrcode/{code}

Resolve a Scanned QR Code

Public — no auth30 requests / minute / IP

Resolve the short code printed on a mezuzah QR sticker to its current status. Use this if you scan the QR code from your own app instead of a browser.

Possible Errors
404

{"status":"not_found"}

No verified mezuzah matches this code.
200

{"status":"already_sold","uuid":"k7Qz9pXsN3vT2m"}

This mezuzah has already been sold to an end customer.
curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/public/scan-qrcode/k7Qz9"
Example response · 200
{
  "status": "found",
  "uuid": "k7Qz9pXsN3vT2m"
}

Store Endpoints

Require your API key in the X-Api-Key header. Generate one from Account Settings → Settings → API Key. Rate-limited per key.

POST

/api/v1/store/register-mezuzah

Register a New Mezuzah

API Key required30 requests / minute / key· Agent accounts only

Register a new mezuzah scroll into your inventory (received from a Sofer, not yet sold). Only available to agent accounts — this matches the same permission the dashboard "Add Mezuzah" screen already enforces.

Form Fields

mezuzah

file
required

Photo of the scroll

sofer

string
required

The scribe's user uuid

megiah

string
required

The examiner's user uuid

writtendate

string
required

YYYY-MM-DD

examinateddate

string
required

YYYY-MM-DD

font

string
required

Script font used

size

string
required

Scroll size

note

string

Optional note

owner_uuid

string

Set immediately if already sold to a known buyer (consumes a credit)

Possible Errors
403

{"msg":"Only an agent account may register a new mezuzah."}

400

{"msg":"Mezuzah already exists.","status":"duplicate"}

400

{"msg":"You have no credits left.","status":"no_credits"}

Only if owner_uuid was set.
curl -X POST "https://mezusafe-backend.jourist.cloud/api/v1/store/register-mezuzah" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "mezuzah=@/path/to/mezuzah.jpg" \
  -F "sofer=<sofer_uuid>" \
  -F "megiah=<megiah_uuid>" \
  -F "writtendate=2025-01-10" \
  -F "examinateddate=2025-01-14" \
  -F "font=Beit Yosef" \
  -F "size=12cm" \
  -F "note=" \
  -F "owner_uuid="
Example response · 200
{
  "msg": "Successfully added."
}
GET

/api/v1/store/inventory

List Your Inventory

API Key required60 requests / minute / key

List mezuzot currently owned by your store — i.e. received but not yet sold.

Query Parameters

page

string

0-indexed page number

per_page

string

Results per page

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/inventory?page=0&per_page=10" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "total": 1,
  "page": 0,
  "per_page": 10,
  "mezuzot": [
    {
      "uuid": "k7Qz9pXsN3vT2m",
      "is_verified": true,
      "note": "",
      "size": "12cm",
      "font": "Beit Yosef",
      "create_time": "2025-01-14 09:00:00",
      "written_time": "2025-01-10 00:00:00",
      "examinated_time": "2025-01-14 00:00:00",
      "last_repaired_time": "",
      "certificate_pdf_url": "",
      "sofer": {
        "uuid": "a1B2c3D4e5",
        "username": "Yosef Cohen"
      },
      "megiah": {
        "uuid": "f6G7h8I9j0",
        "username": "David Katz"
      }
    }
  ]
}
GET

/api/v1/store/mezuzah/{uuid}

Get Mezuzah Status

API Key required60 requests / minute / key

Status/details of one mezuzah — only works for a uuid your store currently owns.

Possible Errors
403

{"msg":"This mezuzah does not belong to your store."}

404

{"msg":"mezuzah not found."}

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/mezuzah/k7Qz9pXsN3vT2m" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "uuid": "k7Qz9pXsN3vT2m",
  "is_verified": true,
  "note": "",
  "size": "12cm",
  "font": "Beit Yosef",
  "create_time": "2025-01-14 09:00:00",
  "written_time": "2025-01-10 00:00:00",
  "examinated_time": "2025-01-14 00:00:00",
  "last_repaired_time": "",
  "certificate_pdf_url": "",
  "sofer": {
    "uuid": "a1B2c3D4e5",
    "username": "Yosef Cohen"
  },
  "megiah": {
    "uuid": "f6G7h8I9j0",
    "username": "David Katz"
  }
}
GET

/api/v1/store/mezuzah-certificate/{uuid}

Get the Certificate

API Key required30 requests / minute / key

Fetch the certificate PDF/PNG URLs for a mezuzah, e.g. to print or email at the point of sale.

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/mezuzah-certificate/k7Qz9pXsN3vT2m" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "pdf_url": "static/print/pdf/9xY8z.pdf",
  "doc_url": "",
  "img_url": "static/print/img/9xY8z.png"
}
POST

/api/v1/store/sell-mezuzah/{uuid}

Record a Sale

API Key required30 requests / minute / key

Record a sale to a customer at checkout. Send `to_uuid` for a buyer who already has a MezuSafe account, or the buyer's details for one who doesn't — either way this consumes one credit, exactly like selling from the dashboard.

Possible Errors
400

{"msg":"Owner have no credits left.","status":"no_credits"}

404

{"msg":"mezuzah not found."}

curl -X POST "https://mezusafe-backend.jourist.cloud/api/v1/store/sell-mezuzah/k7Qz9pXsN3vT2m" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to_uuid": "a1B2c3D4e5",
  "note": "Sold in-store"
}'
Example response · 200
{
  "msg": "mezuzah sold successfully."
}
GET

/api/v1/store/sales-history

Your Sales History

API Key required60 requests / minute / key

Your store's own past sales, for reconciling against your own order records.

Query Parameters

page

string

0-indexed page number

per_page

string

Results per page

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/sales-history?page=0&per_page=20" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "total": 1,
  "page": 0,
  "per_page": 20,
  "sales": [
    {
      "mezuzah_uuid": "k7Qz9pXsN3vT2m",
      "create_time": "2025-01-20 14:00:00",
      "note": "Sold in-store",
      "to": {
        "uuid": "a1B2c3D4e5",
        "username": "Chaim Levi"
      }
    }
  ]
}
GET

/api/v1/store/credits

Check Your Credit Balance

API Key required60 requests / minute / key

Remaining credit balance — check this before a sale to avoid a no_credits error.

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/credits" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "credits": 42
}
GET

/api/v1/store/sofers-megiahs

List Sofers & Megiahs

API Key required60 requests / minute / key

Directory of confirmed sofers and megiahs — useful for picking the sofer/megiah uuid to pass into Register a New Mezuzah.

Query Parameters

page

string

0-indexed page number

per_page

string

Results per page (max 100)

role

string

Optional — 'sofer' or 'megiah'. Omit to get both.

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/sofers-megiahs?page=0&per_page=20&role=sofer" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "total": 1,
  "page": 0,
  "per_page": 20,
  "sofers_megiahs": [
    {
      "uuid": "a1B2c3D4e5",
      "username": "Yosef Cohen",
      "email": "yosef@example.com",
      "role": "sofer",
      "megiah_type": null,
      "company": null,
      "avatar": "static/avatar/f3g4h5.jpg",
      "diploma_url": "static/diploma/j6k7l8.jpg",
      "country": "Israel",
      "state": "",
      "city": "Jerusalem",
      "create_time": "2024-11-02 09:00:00"
    }
  ]
}
GET

/api/v1/store/sofers-megiahs/lookup

Look Up a Sofer or Megiah

API Key required60 requests / minute / key

Fetch a single sofer/megiah by exact email or username (case-insensitive). Provide one, not both.

Query Parameters

email

string

Exact email match (case-insensitive)

username

string

Exact username match — only used if 'email' is omitted

Possible Errors
400

{"msg":"Provide an email or username query parameter."}

404

{"msg":"No sofer/megiah found."}

curl -X GET "https://mezusafe-backend.jourist.cloud/api/v1/store/sofers-megiahs/lookup?email=yosef%40example.com&username=yosef.cohen" \
  -H "X-Api-Key: YOUR_API_KEY"
Example response · 200
{
  "uuid": "a1B2c3D4e5",
  "username": "Yosef Cohen",
  "email": "yosef@example.com",
  "role": "sofer",
  "megiah_type": null,
  "company": null,
  "avatar": "static/avatar/f3g4h5.jpg",
  "diploma_url": "static/diploma/j6k7l8.jpg",
  "country": "Israel",
  "state": "",
  "city": "Jerusalem",
  "create_time": "2024-11-02 09:00:00"
}
logo

Company

Contacts

More

Please contact MezuSafe by email at contact@mezusafe.com Having an account you will be able to chat with the MezuSafe admin in real time.

@2026 Mezusafe.com

Privacy policy

Terms & conditions