Ad Feedback

Let users react to ads with thumbs-up / thumbs-down.

POST /ad-feedback

curl -X POST https://platform.trygravity.ai/ad-feedback \
  -H "X-API-Key: <your_publisher_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "impUrl": "https://api.trygravity.ai/ack?p=<encrypted_token_from_ad_response>",
    "sentiment": "thumbs_down",
    "reasons": ["not_interested", "repetitive"]
  }'

End users can submit feedback on served ads — thumbs up, thumbs down, and optional reasons. This helps Gravity improve ad quality and relevancy over time, and gives publishers a signal for user satisfaction.

Base URL

https://platform.trygravity.ai

Headers

X-API-Key · string · required

Your Gravity publisher API key.

Body

sessionId · string · required

Session identifier. Same value you passed when requesting the ad.

impUrl · string · required

The impUrl from the ad response object. The server decrypts this to extract the ad’s tracking IDs (grclid, gradid, campaignId, publisherId) automatically — you don’t need to parse or extract anything yourself.

sentiment · string · required

User’s reaction. One of thumbs_up or thumbs_down.

reasons · array

Optional. Why the user reacted this way. Array of reason strings. Suggested values:

Reason	When to use
not_interested	User doesn’t care about this product/category
irrelevant	Ad doesn’t relate to the conversation
offensive	Ad content is objectionable
repetitive	User has seen this ad too many times
misleading	Ad claims don’t match the landing page
helpful	(thumbs up) Ad was useful or well-matched

You can send any string — the values above are suggestions, not an enum.

comment · string

Optional. Free-text feedback from the user (max 1,000 characters).

placement · string

Optional. Placement type where the ad was shown (e.g. below_response).

placementId · string

Optional. Publisher’s slot identifier for the placement.

userId · string

Optional. Publisher’s end-user identifier.

device · object

Optional. Device signals — same shape as the ad request’s device object.

curl -X POST https://platform.trygravity.ai/ad-feedback \
  -H "X-API-Key: <your_publisher_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "impUrl": "https://api.trygravity.ai/ack?p=<encrypted_token_from_ad_response>",
    "sentiment": "thumbs_down",
    "reasons": ["not_interested", "repetitive"]
  }'

Response

200 — feedback recorded.

{
  "status": "ok",
  "feedbackId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

401 — invalid API key.

422 — invalid impUrl. The URL could not be decrypted. Make sure you’re sending the exact impUrl from the ad response.

429 — rate limit exceeded. The endpoint allows up to 30 feedback submissions per session per minute.

503 — internal error. Safe to retry.

Best practices

Surface feedback controls after the ad renders

Show a small thumbs-up / thumbs-down UI once the ad is visible. Don’t interrupt the user — feedback should be one tap, not a modal.

function AdWithFeedback({ ad, sessionId, apiKey }) {
  const [sent, setSent] = useState(false);

  const sendFeedback = async (sentiment, reasons) => {
    setSent(true);
    await fetch('https://platform.trygravity.ai/ad-feedback', {
      method: 'POST',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        sessionId,
        impUrl: ad.impUrl,
        sentiment,
        reasons,
      }),
    });
  };

  if (sent) return <span>Thanks for your feedback</span>;

  return (
    <div>
      <GravityAd ad={ad} variant="card" />
      <button onClick={() => sendFeedback('thumbs_up')}>👍</button>
      <button onClick={() => sendFeedback('thumbs_down', ['not_interested'])}>👎</button>
    </div>
  );
}

Collect reasons on thumbs-down

When a user taps thumbs-down, show a quick follow-up with checkboxes or chips for not_interested, irrelevant, repetitive, offensive. Send the selected reasons in the reasons array. This gives Gravity actionable signal to improve matching.

Don’t gate the experience on feedback

Feedback is fire-and-forget. If the request fails, swallow the error — never block the user’s workflow because a feedback call didn’t land.

Just pass through impUrl

Every ad response includes an impUrl. Simply store the ad object and pass ad.impUrl back when submitting feedback — the server handles all the tracking ID extraction automatically. No need to parse URLs or decrypt tokens on the client side.

What’s next

Show ads

Render ads with the pre-built React component or your own UI.

Contextual ads endpoint

Full request / response reference for POST /api/v1/ad.