Skip to main content

​
🤝 Third-party activity integration

Although Megaphone supports many first-party quests, there are non-standard quests and verifications that require a custom third-party API integration. This guide explains how you can integrate a custom third-party API to power custom onchain checks, in-app integrations, etc.

​
🔑 Auth

Your API endpoint should not require any auth and should be an open API endpoint. In the future, we plan to allow custom headers required for the API (ex: API keys).

​
🎟️ Input/request from Megaphone to your API

Whenever a Megaphone campaign user verifies doing an activity on your Megaphone page, our backend will make a request to your open API endpoint using your specific query key identity type.
URL: https://<endpoint>/<path>?<queryParamKey?=<queryParamValue>>
  • <endpoint>/<path>: your base API endpoint
  • <queryParamKey?><queryParamValue>: identity-specific static query params. Supported queryParams are evmAddress and emailAddress. If you would like other identity options, please request them on our public Megaphone roadmap.
    For evmAddress, we normalize the string to lowercase. Make sure that your endpoint supports lookup by lowercase address to prevent issues!
    For emailAddress, note that Megaphone automatically blocks signups from temporary/disposable email services as part of our anti-sybil protections.
    • evmAddress: evmAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045
    • emailAddress: emailAddress=vitalik@buterin.com
Example requests evmAddress 
https://api.example.com/v1/verify?&evmAddress=0xd8da6bf26964af9d7eed9e03e53415d37aa96045
emailAddress 
https://api.example.com/v1/verify?&emailAddress=vitalik@buterin.com

​
🚪 Expected Output / Response from your API

We expect a particular response format from your open API endpoint. We will throw a 500 error if we detect any response that doesn’t conform to the below format.
Response Schema 
type ThirdPartyApiResonse = {
  status: "eligible";
  points?: number; // If not provided, we will default to 0
} | {
  status: "ineligible";
} |
{
  status: "error";
  message: string;
}
Megaphone expects these status codes to be returned from your api endpoint for different response types:
  • status: eligible — 200
  • status: ineligible — 200
  • status error
    • 4xx if Megaphone made a bad request
    • 5xx if your API service is unavailable
Example (Eligible) HTTP Status: 200 
{
  "status": "eligible",
  "points": 100
}
Example (Ineligible) HTTP Status: 200 
{
  "status": "ineligible"
}
Example (Error) HTTP Status: 4xx 
{
  "status": "error",
  "message": "Invalid query param."
}

​
❓ FAQ

You can let us know if you want:(A) users who are ineligible to be handled as receiving “0” points and completing the activityOR(B) users who are ineligible will temporarily fail the activity and then will be allowed to retry the activity after a cooldown periodWe will configure the appropriate behavior on the Megaphone platform side.