Skip to main content
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:
ReasonWhen to use
not_interestedUser doesn’t care about this product/category
irrelevantAd doesn’t relate to the conversation
offensiveAd content is objectionable
repetitiveUser has seen this ad too many times
misleadingAd 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.