Safeguard listing check

Safeguard reads a listing the way a careful buyer would before spending their own money, scores it from 0 to 10 for how ready a buyer could be to buy it exactly as it stands, and tells the seller what to fix.

What a result means, and what it does not

• A high score means the listing is complete and consistent: a buyer is told what the item is, what condition it is in and what is included. It does not mean the item is genuine.
• Safeguard can sometimes miss a problem, including a difference between a photo and the description. It supports a human decision rather than replacing it.
• Safeguard is not fraud prevention. It cannot inspect, test or authenticate an item, it cannot tell whether a seller is honest, and a complete listing of a fake can score well. It does flag a claim that the photos or the listing contradict, a price far from what the item sells for, and signs of a scam.
• The score is the AI's own judgement against a fixed scale (shown below). PCIFIC checks that the answer is complete and real, but never changes the score. The same listing can score slightly differently if you check it more than once. In our testing the difference is normally within 1 point, and we are actively working to make scores more consistent. Visual findings and wording can still vary even when scores match; check the evidence itself.
• passed and the verdict are your shop's decision made visible. Safeguard never publishes, blocks, buys, bids or messages anyone.

What you can use it for

Safeguard also gives the buyer side something to show: questions a careful buyer would still ask (questions), a buyer FAQ written from the listing (faq), and suggested new wording (rewrite).

Before you start

• A key with the safeguard permission. Use a test key while you build: it runs the real review and spends no credits, and each review, set of answers or retry counts as one AI request towards the shop's daily cap, shared by its test keys. PCIFIC's ceiling always applies, 200 per shop per UTC day by default, or your lower saved cap. Live keys spend credits after you choose Live key and press Activate live key on the API keys page. See API keys and permissions.
• Published listing fields (a schema, the files that describe your listing's fields) for the category you review. Safeguard reads each field's description, so write a clear one. Without a published version a review is refused with SAFEGUARD_NO_SCHEMA. See Set up your listing fields.
• Safeguard switched on. It is on by default. Starting a review, sending answers and retrying are all refused with SAFEGUARD_TURNED_OFF while it is off.
• Only if you send photos: Orbit switched on too. The photo upload belongs to Orbit, so it follows Orbit's switch. A key with the orbit or the safeguard permission can upload.
• Optional: your own minimum score, banned items and verdict names. Change them on the dashboard, or with PUT /api/v1/safeguard/settings and a test key that has the settings permission. A live key can read the settings but never change them. See Shop configuration.

How a review works

A review is kept for 30 minutes after its last change (started, finished, answered or retried), then deleted. Save the score and the updated listing on your side before then. Safeguard never saves your listing for you.

Quickstart

These steps assume a test key in $PCIFIC_TEST_KEY and a published Phones category like the one in Set up your listing fields. The price is a money field: amount is in minor units (pence or cents, so 31500 with GBP is £315) and currency is your shop's currency.

Step 1: read your settings (optional)

curl https://business.pcific.ai/api/v1/safeguard/settings \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"

{
  "enabled": true,
  "minimumScore": 7,
  "webSearch": true,
  "bannedItems": [],
  "instructions": null,
  "orbitDefault": false,
  "verdicts": [
    {
      "name": "High risk",
      "from": 0,
      "meaning": "block"
    },
    {
      "name": "Caution",
      "from": 4,
      "meaning": "review"
    },
    {
      "name": "Looks good",
      "from": 7,
      "meaning": "pass"
    }
  ],
  "categoryVerdictStarts": {}
}

Step 2: upload photos

At least one photo is required by default on POST /api/v1/safeguard/reviews, including when the listing comes from orbitRunId. A request with no photos is refused before work with PHOTOS_REQUIRED (422), with no charge. Strongly recommended: keep photos on. Set requirePhotos to false only when you choose a text-only request, for example for a service. Without photos results are less reliable and can vary more. Send each photo as a file in a multipart form (a form that carries files). You get a photo id for each, which lives for 30 minutes. Orbit's page has the full rules for photos.

curl -X POST https://business.pcific.ai/api/v1/images \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -F "photo=@front.jpg"

{
  "images": [
    {
      "id": "3f1c2a9e-5b7d-4c1e-9a52-7d0c6e8b1f34",
      "width": 3024,
      "height": 4032,
      "preview": "https://files.example/preview.webp",
      "listing": {
        "url": "https://files.example/listing.webp",
        "format": "webp"
      },
      "expiresAt": "2026-10-19T10:30:00Z",
      "fileName": "front.jpg"
    }
  ]
}

Step 3: start the review

curl -X POST https://business.pcific.ai/api/v1/safeguard/reviews \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"Phones","listing":{"title":"iPhone 13 128GB, good condition, works fine","description":"Selling my old phone. No box. Collection preferred.","brand":"Apple","model":"iPhone 13","storage_gb":128,"condition":"Good","price":{"amount":31500,"currency":"GBP"}},"images":["3f1c2a9e-5b7d-4c1e-9a52-7d0c6e8b1f34"],"requirePhotos":true,"review":true,"faq":false}'

Before work starts, Safeguard refuses wrong field types, values outside fixed options and unreadable prices with 400 INVALID_LISTING. problems has one entry per affected field, with path, problem and tryThis. No credits are spent. Missing details, including required fields, and unusual values that have the right type and are allowed still go to the AI judge. A price amount containing a decimal point or exponent, including 749.0, is refused. Send whole minor units, like 4500 pence for £45. Any price that cannot be read in a result is explained in pcific.priceProblems with path, problem and tryThis.

{
  "status": "working",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "tryThis": "Read the review with GET /api/v1/safeguard/reviews/1f9380fa-a135-4b3d-ab70-1dc1fc50f065 in a few seconds.",
  "warnings": []
}

The addresses inside tryThis and retry already use the public /api/v1/ prefix. Call them as returned.

Step 4: read the review until it is done

curl https://business.pcific.ai/api/v1/safeguard/reviews/1f9380fa-a135-4b3d-ab70-1dc1fc50f065 \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY"

{
  "status": "working",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "tryThis": "Read this again in a few seconds."
}

{
  "status": "done",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "score": 6,
  "passed": false,
  "minimumScore": 7,
  "verdict": {
    "name": "Caution",
    "meaning": "review"
  },
  "banned": {
    "isBanned": false,
    "reason": null
  },
  "review": {
    "summary": "Clear model and storage, but the battery health and lock status are missing.",
    "fixes": [
      {
        "field": "/battery_health",
        "importance": "important",
        "problem": "Battery health is not stated.",
        "fix": "Add the battery health percentage from Settings."
      },
      {
        "field": "/description",
        "importance": "important",
        "problem": "It does not say whether the phone is unlocked.",
        "fix": "Say whether the phone is unlocked or tied to a network."
      }
    ]
  },
  "questions": [
    "Has the screen or battery ever been replaced?"
  ],
  "sellerQuestions": [
    {
      "id": "q1",
      "question": "What is the battery health percentage?",
      "field": "/battery_health"
    },
    {
      "id": "q2",
      "question": "Is the phone unlocked or tied to a network?",
      "field": "/description"
    }
  ],
  "listing": {
    "title": "iPhone 13 128GB, good condition, works fine",
    "description": "Selling my old phone. No box. Collection preferred.",
    "brand": "Apple",
    "model": "iPhone 13",
    "storage_gb": 128,
    "condition": "Good",
    "price": {
      "amount": 31500,
      "currency": "GBP"
    }
  },
  "pcific": {
    "release": "2.0.0",
    "category": "Phones",
    "schemaVersion": 3,
    "prices": {
      "/price": {
        "amount": 31500,
        "currency": "GBP",
        "display": "£315.00"
      }
    },
    "warnings": []
  },
  "expiresAt": "2026-10-19T10:30:00Z"
}

Here the phone scores 6 because two important facts are missing, so passed is false against a minimum of 7 and the verdict is Caution, which means review. Show the fixes to the seller and ask the questions in sellerQuestions.

A fix carries field only when the seller would change that field's value. Photo fixes and fixes about the listing as a whole are general suggestions with no field, for example "Add a clear photo of the back." Show them under the photos or as a note on the listing. A fix that needs uploaded or replacement photos carries target: photos. Use that target to open your photo uploader; do not write the photo request into /description. Photo seller questions can carry the same target with no field. Upload the requested photos, then start a new review using the returned image ids.

Step 5: send the seller's answers (optional)

curl -X POST https://business.pcific.ai/api/v1/safeguard/reviews/1f9380fa-a135-4b3d-ab70-1dc1fc50f065/answers \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"answers":[{"id":"q1","answer":"91%"},{"id":"q2","answer":"It is unlocked, works on any network"}]}'

{
  "status": "working",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "tryThis": "Read the review with GET /api/v1/safeguard/reviews/1f9380fa-a135-4b3d-ab70-1dc1fc50f065 in a few seconds.",
  "warnings": []
}

Read the review again as in step 4. When it is done it holds the updated listing and a new score. The seller's answers changed two fields, and changes shows the seller's exact words for each:

{
  "status": "done",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "score": 9,
  "passed": true,
  "minimumScore": 7,
  "verdict": {
    "name": "Looks good",
    "meaning": "pass"
  },
  "banned": {
    "isBanned": false,
    "reason": null
  },
  "review": {
    "summary": "Clear model, storage, battery health and lock status. Only the charger is not mentioned.",
    "fixes": [
      {
        "importance": "minor",
        "problem": "It does not say whether a charger is included.",
        "fix": "Say whether the charger is included."
      }
    ]
  },
  "questions": [],
  "sellerQuestions": [],
  "changes": [
    {
      "field": "/battery_health",
      "before": null,
      "after": 91,
      "questionId": "q1",
      "quote": "91%"
    },
    {
      "field": "/description",
      "before": "Selling my old phone. No box. Collection preferred.",
      "after": "Selling my old phone. Unlocked, works on any network. No box. Collection preferred.",
      "questionId": "q2",
      "quote": "It is unlocked, works on any network"
    }
  ],
  "listing": {
    "title": "iPhone 13 128GB, good condition, works fine",
    "description": "Selling my old phone. Unlocked, works on any network. No box. Collection preferred.",
    "brand": "Apple",
    "model": "iPhone 13",
    "storage_gb": 128,
    "condition": "Good",
    "battery_health": 91,
    "price": {
      "amount": 31500,
      "currency": "GBP"
    }
  },
  "pcific": {
    "release": "2.0.0",
    "category": "Phones",
    "schemaVersion": 1,
    "prices": {
      "/price": {
        "amount": 31500,
        "currency": "GBP",
        "display": "£315.00"
      }
    },
    "warnings": []
  },
  "expiresAt": "2026-10-19T10:30:00Z"
}

Request fields

Send a JSON object (text in curly brackets) with the header Content-Type: application/json. Keys Safeguard does not know are ignored, and each is named in warnings so a typo does not pass silently. Your listing keeps your own field names. Safeguard asks for no field in particular, not even a title or description, and judges against the fields of the category you name.

What INVALID_FIELD means here

INVALID_FIELD (400) means a field has the wrong type or size. The error names it, and problems lists each place with a next step.

Numbers, true or false, and fixed options in your listing

Photo problems and listing-field problems are collected together in problems. A photo error keeps its 422 code; otherwise listing errors use 400 INVALID_LISTING. Required fields are judged, not validated. A missing required field is accepted (202); the judge flags the gap and can ask the seller. Each value supplied in listing must have the type your listing fields set. Text where a number belongs ("ninety"), a word where true or false belongs ("yes"), or a choice that is not one of the allowed options is refused with a 400 error, before any review starts. Nothing is charged. problems names each field, what is wrong with it and what to send instead. Missing details and unusual values of the right type that satisfy any fixed options are not refused: Safeguard mentions them in the review.

A price amount is a whole number in the smallest unit of the currency. Decimal points and exponents, including 749.0, are refused; send 4500 pence for £45. Text amounts are refused too. Any other amount (fractional, negative, missing or out of range) is refused in the same way, and problems names the price.

Response fields

Starting, answering and retrying all answer 202 with the same four fields. Fields not listed may be added at any time; ignore what you do not use.

GET /api/v1/safeguard/reviews/{reviewId} answers 200 with one of three shapes, chosen by status.

With review set to false there is no score, passed, verdict, review, questions or sellerQuestions. A rewrite still includes banned so a flagged listing never receives polished wording. You also get listing and pcific.

{
  "status": "failed",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "error": {
    "error": "Safeguard took over 180 seconds on this review.",
    "code": "SAFEGUARD_TIMED_OUT",
    "tryThis": "Try it again with POST /api/v1/safeguard/reviews/1f9380fa-a135-4b3d-ab70-1dc1fc50f065/retry. If it keeps happening, contact PCIFIC support with the reviewId."
  },
  "retry": "POST /api/v1/safeguard/reviews/1f9380fa-a135-4b3d-ab70-1dc1fc50f065/retry"
}

How the score is chosen

The judge goes through this scale in order and stops at the first line that fits. An important gap is something a careful buyer would not pay without knowing. A minor gap is something they would like to know but would still buy without. Every fix in review.fixes is one gap or warning sign, marked important, minor or warning, and the score must match them.

• If you opt out with requirePhotos: false, the judge treats missing photos of a physical item a buyer would want to see as an important gap. Tickets, services and bookings can use this opt-out when there is nothing to photograph.
• A required field that is empty is always a gap. A clear statement from the seller fills a gap.
• Things no listing can give are never gaps: independent authentication the seller does not claim, a valuation, the buyer's own inspection, a price comparison. They appear in questions for the buyer to ask.
• Prices are read in your shop's currency and are never converted. A price in another currency is an important gap. A price far from what the item sells for, with nothing to explain it, is a warning sign.
• A banned item always scores 0.

Your minimum score and your verdicts

Two settings decide how a score is shown. They are set once for your shop, not on each request. The full settings table is on Shop configuration.

• minimumScore (default 7) is your pass line. passed is true when the score reaches it, the item is not banned, and no fix is marked important or warning. Minor advice alone does not prevent a pass. On the scale above, 7 means one important gap is left and everything else is there.
• When reporting an Orbit listing as published, a latest Safeguard score below minimumScore with open seller questions is refused with 409 REQUEST_REFUSED. Answer every open seller question, wait for the review to finish, then report the outcome again.
• verdicts are your own names for ranges of the scale, lowest first, each meaning block, review or pass. The standard three are High risk from 0 (block), Caution from 4 (review) and Looks good from 7 (pass). You can set 2 to 5 of your own. Show verdict.name to people and branch your code on verdict.meaning.
• categoryVerdictStarts lets one category start its ranges at other scores, like {"Art": [0, 6, 9]}, for items that need stricter or looser reading.
• When a fix is marked important or warning, the verdict uses the highest non-pass range the score reaches, with your category starts and your own names. Verdicts never change the score or fixes. Otherwise they follow the score, while minimumScore remains a separate pass line. If you set minimumScore to 8 while Looks good starts at 7, a score of 7 shows Looks good with passed false. Pick one of them as your gate and use the other for wording.
• Safeguard decides nothing for you. block, review and pass are hints for your own code, such as hold back, send to a person or publish.
• Do not build logic that expects the exact same score to come back each time. Branch on verdict.meaning or passed, not on one exact score, and expect a listing that sits right on a line to land on either side of it now and then.

Answering the seller's questions

When the judge finds a gap only the seller can fill, it adds a question to sellerQuestions with an id, the field the answer fills, and that field's list of allowed values (options) when it has a short one. Show all of them on one screen and send all the answers in one request.

• Answers go in only while the review is done. Sending them while it works is REVIEW_NOT_READY.
• Each answer is at most 1,000 characters. A blank answer is stored as "(no answer)". It counts as answered, so that question is closed.
• A question you leave out of the request is stored as "(no answer)" too. This is why you send every answer in one request.
• The seller can send answers 3 times for one review. A fourth is refused with TOO_MANY_ANSWER_ROUNDS: start a new review with the updated listing.
• An answer can change several relevant fields, even when its question named no field. Fixed options use the same published field and option descriptions Orbit reads.
• Every update is returned in changes, including description and title updates. Its questionId and quote name the new answer; supportingAnswers lists other contributing answer ids and quotes, including earlier answers. Unchanged values are left out. The seller or shop decides what to accept and save.
• A price answer changes the whole price, as {amount, currency}, and only to the amount the seller said.

Retrying a failed review

FAQ and rewrites

Add "faq": true to also get 3 to 6 questions a buyer would ask on the listing page, each answered only from the listing, the photos and the seller's words, never from the web or a guess. A question the listing does not answer comes back with answer null and needsSeller true, so you can ask the seller. The review keeps web search when enabled. A separate FAQ writer sees only the listing, the photos and the seller's words, so FAQ answers never use web pages.

Add "rewrite": true to get suggested new wording for /title and /description, written in the listing style you set in the Orbit settings and kept within each field's limits in your schema. Name the fields yourself with "rewrite": ["/title"] (1 to 5 field paths, each once, none inside a list). Every suggestion has before and after, and the listing itself is not changed. When the AI flags the listing, rewrite is [] and rewriteSkippedReason explains why, including the flag reason. banned.kind is banned_item for an item on your banned list or illegal to sell, or scam for clear deception. banned.reason is required and points to the evidence in plain words. Spelling, grammar, formatting and missing details alone are never scam evidence. Send "review": false with either to get only the FAQ or the rewrite.

curl -X POST https://business.pcific.ai/api/v1/safeguard/reviews \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"Phones","listing":{"title":"iPhone 13 128GB, good condition, works fine","description":"Selling my old phone. No box. Collection preferred.","brand":"Apple","model":"iPhone 13","storage_gb":128,"condition":"Good","price":{"amount":31500,"currency":"GBP"}},"requirePhotos":false,"review":false,"rewrite":["/title"]}'

{
  "status": "done",
  "reviewId": "1f9380fa-a135-4b3d-ab70-1dc1fc50f065",
  "banned": {
    "isBanned": false,
    "reason": null
  },
  "rewrite": [
    {
      "field": "/title",
      "before": "iPhone 13 128GB, good condition, works fine",
      "after": "Apple iPhone 13 128GB, Good Condition"
    }
  ],
  "listing": {
    "title": "iPhone 13 128GB, good condition, works fine",
    "description": "Selling my old phone. No box. Collection preferred.",
    "brand": "Apple",
    "model": "iPhone 13",
    "storage_gb": 128,
    "condition": "Good",
    "price": {
      "amount": 31500,
      "currency": "GBP"
    }
  },
  "pcific": {
    "release": "2.0.0",
    "category": "Phones",
    "schemaVersion": 1,
    "prices": {
      "/price": {
        "amount": 31500,
        "currency": "GBP",
        "display": "£315.00"
      }
    },
    "warnings": []
  },
  "expiresAt": "2026-10-19T10:30:00Z"
}

Reviewing an Orbit listing

Orbit writes a listing from a seller's photos and notes. Safeguard can review it two ways, and in both it is told where Orbit got each value, so it can say plainly when Orbit added a fact nobody gave.

• As Orbit writes it: send "safeguard": true (and "faq": true for a FAQ) with POST /api/v1/listings. The finished listing comes back with the review in pcific.safeguard, which has the same shape as a review here, with its own reviewId. Answer its questions or retry it with that reviewId. Setting orbitDefault to true reviews every Orbit listing that does not say otherwise. Asking for either while Safeguard is off is refused by Orbit with SAFEGUARD_OFF (409).
• Later: send "orbitRunId" with the runId of the finished Orbit listing to POST /api/v1/safeguard/reviews. Its listing, category, photos and what the seller told Orbit come with it, so you need not send them. If you do send listing, category or images they replace Orbit's, and sellerNotes is added to what the seller told Orbit. An Orbit listing is deleted 30 minutes after its last change.

curl -X POST https://business.pcific.ai/api/v1/safeguard/reviews \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orbitRunId":"8c7a6f0e-2b4d-4e51-a9c3-5d1e7f2b9a40"}'

Errors

Every error is JSON with error (what went wrong), code (a fixed name your code can branch on), tryThis (the next step) and sometimes problems (each exact place at fault, as a path like /images/0 with its own next step). 4xx means fix the request. 5xx means a problem on PCIFIC's side: wait and try again.

Most errors also have a docs link to their own section on Safeguard errors, with the usual causes, how to fix it and a request that works. That page starts with the mistakes integrations make most often.

• Safeguard errors

Errors reach you in two places. Refused straight away: the call itself answers with an HTTP error, no review is started, and nothing is saved. Failed later: the review was accepted (202), then went wrong while it worked. Then GET answers HTTP 200 with status failed and the error inside, so read status before you read anything else.

Refused when you start a review

Refused when you answer or retry

SAFEGUARD_TURNED_OFF applies here too. Reading a review with an id that is unknown, belongs to another business or is older than 30 minutes is NOT_FOUND (404): start a new review.

Failed later, found when you read the review

These sit in error.code of a failed review. The HTTP column is the kind of fault, because the GET itself answers 200. SAFEGUARD_TURNED_OFF and CURRENCY_NOT_IN_SCHEMA can also appear here if the setting changes while a review waits.

Refused when you upload photos

These come from POST /api/v1/images, which is Orbit's address. See the Orbit page for the photo rules, including iPhone photos (HEIC).

The website checks body size first. Rust then checks retry headers, authentication, permission and the request fields. Network and key limits can refuse a request before later checks. Once a published category is identified, photo and listing-field problems are reported together, each with a next step. A 4xx refusal does not spend your Idempotency-Key: correct the request and send it again with the same key. A successful 202 replay returns the original reviewId ticket. Poll that reviewId for the current result, even if the ticket still says working. No second review is started.

Errors every address can give (a missing or revoked key, KEY_NOT_ALLOWED, INVALID_JSON, INVALID_FIELD, NOT_FOUND, RATE_LIMITED, TEST_DAILY_CAP_REACHED, OUT_OF_CREDITS and the rest) are on the Errors, limits and retries page. The same page explains the Idempotency-Key header, which POST /reviews, /answers and /retry all accept so that a repeated request is not done twice.

Limits

The request limit, the daily cap on test keys and your spend limits are on the Errors, limits and retries page and on API keys and permissions. Poll every 3 to 5 seconds, not in a tight loop. Starting a review, sending answers and retrying count as requests that start work.

Words used on this page

• Review: one run of Safeguard on one listing. It has a reviewId.
• Polling: asking again on a timer until the answer is ready.
• 202: the HTTP status for "accepted, still working".
• Schema or listing fields: the files that describe your listing's fields, which Safeguard reads.
• Minor units: pence or cents, so 31500 with GBP is £315.
• Gap: something a careful buyer needs that the listing does not say. Important gaps stop a purchase, minor gaps do not.
• Verdict: your own name for a range of scores, with a meaning of block, review or pass.
• Banned item: something on your own banned list, or plainly illegal or a scam. It always scores 0.
• Seller question: a question only the seller can answer, such as battery health.
• FAQ: frequently asked questions and answers, shown on the listing page.
• Test key and live key: see API keys and permissions.
• Idempotency-Key: a unique value you choose for each piece of work, so a repeated request is not done twice.

Related guides

• Getting started
• Build it yourself
• Orbit listing generation
• Set up your listing fields
• Shop configuration
• API keys and permissions
• Errors, limits and retries
• Bring your own AI