All documentation
Documentation
Base path
Most SDK endpoints are under:
/sdk/v1
The compact campaign creator list is versioned separately at:
GET /sdk/v2/campaigns/:campaignId/creators
Authentication (required on every request)
Send these headers on every request:
X-Application-Id: Your SDK application ID.X-Api-Key: Your SDK API key secret.
If the application has an origin allowlist configured:
- If the request includes an
Originheader, it must match the allowlist. - If the request omits
Origin(common server-to-server), allowlist checks are skipped.
Scopes (what a key is allowed to do)
Every API key carries a set of scopes, chosen when the key is created and editable
afterwards from the developer portal. A scope is written <domain>:<action>, where
the action is read or write.
| Domain | Covers |
|---|---|
analytics |
Tracked media, collections, and performance metrics. |
campaigns |
Campaigns, campaign creators, contracts, campaign media, crosspost groups, and bonus templates. |
payouts |
Wallet balance, transactions, invoices, payout history, and sending payouts. |
approvals |
Read payout approval requests and approve, reject, or cancel them. |
disputes |
Read payout disputes and their proof, reply to them, and resolve or reject them. |
kyc |
Recipient onboarding and identity verification. |
write does not imply read, so a domain has four possible states and the portal
offers all of them: No access, Read only, Write only, and Read and write. A key
that should both list and mutate a domain needs both scopes.
A call whose key is missing the required scope answers 403 and names what is missing:
{
"success": false,
"message": "This API key is missing the required scope: payouts:write"
}
Two notes worth knowing before you design around this:
- The HTTP method is not the rule. Several endpoints are
POSTbut are pure reads, and they require:read, not:write. That includesPOST /payouts/status,POST /payouts/pending,POST /payouts/pending-bulk,POST /wallet/check-payout-balance[-bulk], and the twoPOST /campaign-creators/.../queryendpoints. So a read-only key can still check a balance before a payout is approved elsewhere. - Reference endpoints need no scope.
GET /timezonesandGET /settingsanswer for any valid key.
Keys that existed before scopes shipped were granted every scope, so nothing changed for
them. Newly introduced domains such as approvals and disputes must be granted explicitly. Rotating a key preserves its scopes.
Idempotency (required on payout, crosspost, and dispute writes)
These endpoints require X-Idempotency-Key:
POST /sdk/v1/payouts/triggerPOST /sdk/v1/payouts/trigger-bulkPOST /sdk/v1/payouts/confirmPOST /sdk/v1/payouts/confirm-bulkPOST /sdk/v1/payouts/cancelPOST /sdk/v1/campaign-creators/payouts/bulkPOST /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-payPOST /sdk/v1/campaign-creators/:campaignCreatorRecordId/crosspost-groupsPATCH /sdk/v1/campaign-creators/:campaignCreatorRecordId/crosspost-groups/membershipsPOST /sdk/v1/campaign-creators/:campaignCreatorRecordId/crosspost-groups/recomputePOST /sdk/v1/disputes/:id/replyPOST /sdk/v1/disputes/:id/resolve
Idempotency keys are scoped per application and operation. Re-using the same key returns the previously stored response.
Dispute keys are scoped per dispute and return the dispute as it is now. See Payout disputes.
Reading Quick Pay approval status or
GET /sdk/v1/payouts/approvals/:approvalId (approval requests created by
Payouts when approval mode is on) requires payouts:read but does
not require X-Idempotency-Key.
Limits and validation
- Supported payout currencies:
USD,CAD,GBP,EUR - Currency precision: money amounts must be positive and have max 2 decimals
- Payout batches: up to 100 items per request
- Campaign creator v1 reads: up to 100 creators per page
- Campaign creator v2 reads: up to 500 creators per page or request
- Eligibility score batches: up to 500 media items per request
- Pending payout TTL: 7 days
- Exports: require
fromandtoand are capped at 10,000 rows
Response conventions
- Most JSON endpoints return
{ success: boolean, ... }. - Balance check endpoints return
{ sufficient: boolean }(nosuccesswrapper). - Export endpoints and invoice PDFs return file content (
text/csvorapplication/pdf).
Pages
- MCP server — connect an MCP-compatible AI client to your Grade account
- Payouts
- Campaign quick pay — custom one-off payments attributed to a campaign
- Bonus templates
- Wallet
- Transactions
- Creators
- KYC
- Invoices
- Settings
- Timezones — list accepted IANA names and display-friendly labels
- Standalone analytics — track accounts and posts outside campaigns, manage collections, and query performance
Campaign management
- Campaigns — create, list, update, delete campaigns and manage campaign creators
- Campaign creators (v2) — use the compact response for new integrations
- Campaign creators (v1 legacy) — preserve the original response for existing clients
- Campaign creator visibility — hide or unhide a creator within a campaign
- Move a creator — move a creator and their history between campaigns in your agency
- Payout report data — read the rows and totals behind a creator's payout report as JSON
- Campaign contracts — manage creator contracts and payment terms (optional)
- Campaign media — track media, manage creator content, and read performance metrics
- Media eligibility — read and update eligibility scores for tracked posts
- Payment exclusions — exclude tracked posts or accounts from fixed-rate and performance payments, or undo those exclusions
Minimal example (curl)
BASE_URL="https://<your-backend-host>"
APP_ID="app_..."
API_KEY="sk_..."
curl -sS "$BASE_URL/sdk/v1/wallet/balance" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY"
Platform workflows
- Campaign media management: freeze/unfreeze performance, restore, restart account tracking, tracking settings, and manual analytics.
- Content review: review queue, filters, decisions, and undo.
- Payment templates: full template management and application.
- Payout approvals: queue and decisions with separate permissions.
- Payment adjustments and scoring: pending bonus, recurring-cycle waivers, and scoring controls.
