API Referencev1.1.0

Scravio API Documentation

Build high-quality email lists from public social profiles.

Validate emails, export leads, and manage credits.

Programmatically create campaigns.

Download exports from one API.

Base URLhttps://api.scravio.com/api

Get API Key

Scravio

Authentication

Endpoint badges show the supported auth modes.

Automation endpoints generally accept an API key.

Send it in the X-API-Key header.

They can also accept a user access token in Authorization: Bearer <accessToken>.

API keys start with sk_live_.

Create and manage your API keys in the API Keys dashboard.

curl https://api.scravio.com/api/auth/me \
  -H "X-API-Key: sk_live_example_key"

curl https://api.scravio.com/api/auth/me \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch('https://api.scravio.com/api/auth/me', {
  headers: {
    'X-API-Key': 'sk_live_example_key'
  }
});
const account = await res.json();

const res = await fetch('https://api.scravio.com/api/auth/me', {
  headers: {
    Authorization: 'Bearer <accessToken>'
  }
});
const account = await res.json();

Workspace context

Workspace-aware endpoints accept an optional X-Workspace-Id header.
Bearer/JWT requests without X-Workspace-Id use the account's current or default workspace.
Workspace-bound API keys are tied to one workspace. If you send X-Workspace-Id with that key, it must match the key's workspace.
Roles are owner, admin, member, and viewer. Endpoint cards list required permissions when a route checks one.
Validation-job routes and GET /credit-transactions require account-scoped API keys. Use Bearer/JWT auth when you need workspace selection on validation jobs.

Error Responses

When an API request fails, the response body contains a standard error object:

Error Response

{
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "param": "inputs.hashtag",
      "msg": "Hashtag is required for INSTAGRAM_HASHTAG campaigns",
      "location": "body"
    }
  ],
  "requestId": "req_abc123"
}

Status	Meaning
`400`	Bad Request — invalid parameters or request body
`401`	Unauthorized — missing or invalid credentials
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource does not exist or does not belong to you
`409`	Conflict — e.g. validation already running for this campaign
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — unexpected failure, retry later

Rate Limits

Some endpoints have per-account or per-resource rate limits to ensure fair usage. When you exceed a rate limit, the API returns 429 Too Many Requests. Rate limits are noted in each endpoint's description.

Endpoint	Limit
`POST /campaigns/{id}/stop`	5 requests/min per campaign
`POST /campaigns/{id}/validate`	3 requests/min per campaign
`POST /validation-jobs/text`	3 requests/hour
`POST /list-exports`	5 requests/hour

API Overview

Account

1 endpoint

Read the authenticated account and effective workspace context.

Campaigns

9 endpoints

Create campaigns, preview credit reservations, inspect leads, and start campaign validation.

Validation

3 endpoints

Submit pasted email lists and inspect standalone validation jobs.

Exports

5 endpoints

Create, list, inspect, and download campaign lead exports.

Credits

1 endpoint

Read the customer-safe credit transaction ledger.

Account

Read the authenticated account and effective workspace context.

GET/auth/me

API keyBearer/JWT

Get current account

Returns a customer-safe account profile, credit balance, email masking state, notification preferences, and the effective workspace context for the request.

X-Workspace-Id supportedWorkspace-scoped API keys supported

JWT requests without X-Workspace-Id use the account default workspace. Workspace-bound API keys use their assigned workspace.

Responses

200Account and workspace context

Field	Type	Description
`id`	`string`	Account ID.
`email`	`string<email>`	Account email.
`name`	`string`nullable	Display name.
`shouldMaskEmail`	`boolean`	Whether lead email values are masked for this account.
`emailRevealUsage`	`object`	Dashboard reveal quota summary.
├`used`	`integer`	Reveals used.
├`limit`	`integer`	Reveal limit.
`credits`	`number`	Available credit balance.
`subscription`	`object`	Current customer-visible subscription state.
├`planId`	`string`nullable	Plan identifier.
├`status`	`string`nullable	Subscription status.
├`concurrentCampaignLimit`	`integer`	Concurrent campaign limit.
`workspace`	`object`	Effective workspace context.
├`id`	`string`	Workspace ID.
├`name`	`string`	Workspace name.
├`role`	`string`	Workspace role. `owneradminmemberviewer`
├`permissions`	`array`	Workspace permissions granted to this account.
├`credits`	`number`	Workspace credit balance.
├`seatSummary`	`object`	Seat usage summary.
├`used`	`integer`	Seats used.
├`limit`	`integer`	Seat limit.

Example

curl -X GET https://api.scravio.com/api/auth/me \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/auth/me \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/auth/me', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/auth/me', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

Campaigns

Create campaigns, preview credit reservations, inspect leads, and start campaign validation.

POST/campaigns/reserve-preview

API keyBearer/JWT

Preview credit reservation

Returns the public credit reservation preview for a campaign request. Send the same type, inputs, targetEmails, maxCreditCap, enableEmailValidation, and enrichIgPosts values to POST /campaigns when launching. Campaign input rules: - INSTAGRAM_HASHTAG accepts inputs.hashtag or inputs.hashtags (max 20). - Instagram user follower/following campaigns accept inputs.targetUser or inputs.targetUsers. Paid workspaces support up to 20 targets; free and Project Pass workspaces support up to 2. - Instagram post liker/commenter campaigns accept inputs.mediaUrl or inputs.mediaUrls. Paid workspaces support up to 20 targets; free and Project Pass workspaces support up to 2. - INSTAGRAM_PROFILE_LIST accepts inputs.profileTargets (max 10000) and does not use targetEmails. - Keyword search types, TIKTOK_SEARCH_USERS, and YOUTUBE_CHANNEL_SEARCH accept inputs.keyword or inputs.keywords (max 20, 2-200 characters each). - YOUTUBE_CHANNEL_SEARCH accepts inputs.youtubeDiscoverySource as channel or video; default is channel. - GOOGLE_MAPS_SEARCH requires inputs.query, one country or countries value, lat, lng, and optional zoom from 1 to 21. The backend controls lang, limit, and offset. - X_FOLLOWERS, X_FOLLOWING, TIKTOK_USER_FOLLOWERS, and TIKTOK_USER_FOLLOWING use inputs.targetUser. - X_RETWEETS, X_REPLIERS, and TIKTOK_POST_COMMENTERS use inputs.mediaUrl. - Optional inputs.countries applies to Instagram, X, YouTube channel search, and keyword search. - Optional inputs.followerFilter with min and max applies to supported profile, list, post, TikTok, X, and YouTube channel campaigns. - Optional Instagram filters scrapeBusinessAccountsOnly and scrapePrivateAccounts apply to non-keyword Instagram campaigns. - targetEmails is required for new lead-target campaigns except INSTAGRAM_PROFILE_LIST. - maxCreditCap is optional and must be positive when provided. - enableDeepEmailSearch is accepted for backward compatibility; unsupported email-only types ignore it. - enrichIgPosts is Instagram-only and defaults to false.

X-Workspace-Id supportedPermission: create_campaignWorkspace-scoped API keys supported

Request Bodyrequired

application/json

Field	Type	Description
`type`required	`string`	Campaign type to estimate. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERSGOOGLE_MAPS_SEARCH`
`inputs`required	`object`	Type-specific campaign inputs.
├`hashtag`	`string`	Single hashtag for INSTAGRAM_HASHTAG campaigns. Omit the # prefix.(max 100 chars)
├`hashtags`	`array`	Multiple hashtags for INSTAGRAM_HASHTAG campaigns.(max 20 items)
├`targetUser`	`string`	Single profile handle for user-based campaigns.(max 100 chars)
├`targetUsers`	`array`	Multiple profile handles for supported Instagram user campaigns.(max 20 items)
├`mediaUrl`	`string<uri>`	Single public post URL for post-based campaigns.(max 2048 chars)
├`mediaUrls`	`array`	Multiple public post URLs for supported Instagram post campaigns.(max 20 items)
├`profileTargets`	`array`	Profile handles or URLs for INSTAGRAM_PROFILE_LIST campaigns.(max 10000 items)
├`keyword`	`string`	Single search keyword for keyword campaigns.(max 200 chars)
├`keywords`	`array`	Multiple search keywords.(max 20 items)
├`youtubeDiscoverySource`	`string`	Discovery source for YOUTUBE_CHANNEL_SEARCH.Default: `channel` `channelvideo`
├`query`	`string`	Search query for GOOGLE_MAPS_SEARCH.(max 200 chars)
├`country`	`string`	Country code for GOOGLE_MAPS_SEARCH. Send exactly one country or countries value.(max 2 chars)
├`countries`	`array`	Optional country filters. For GOOGLE_MAPS_SEARCH, send exactly one value.(max 10 items)
├`lat`	`number`	Latitude for GOOGLE_MAPS_SEARCH.
├`lng`	`number`	Longitude for GOOGLE_MAPS_SEARCH.
├`zoom`	`integer`	Map zoom for GOOGLE_MAPS_SEARCH.Default: `12`(1–21)
├`followerFilter`	`object`	Optional follower range for supported campaign types.
├`min`	`integer`	Minimum follower count.
├`max`	`integer`	Maximum follower count.
├`scrapeBusinessAccountsOnly`	`boolean`	Instagram-only filter for business profiles.Default: `false`
├`scrapePrivateAccounts`	`boolean`	Instagram-only private-profile setting.Default: `true`
`targetEmails`	`integer`	Requested lead goal. Required for lead-target campaigns and omitted for INSTAGRAM_PROFILE_LIST.
`maxCreditCap`	`number`	Optional positive hard cap for the campaign.
`enableEmailValidation`	`boolean`	Include campaign email validation in the preview.Default: `false`
`enrichIgPosts`	`boolean`	Instagram-only post enrichment flag.Default: `false`

Responses

200Public reserve preview

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Customer-safe reserve preview.
├`type`	`string`	Campaign type. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERSGOOGLE_MAPS_SEARCH`
├`targetMode`	`string`	Whether the campaign targets leads or items. `LEAD_TARGETITEM_LIMIT`
├`targetEmails`	`integer`nullable	Requested lead goal when applicable.
├`creditReserved`	`number`	Credits reserved on launch.
├`estimatedCredits`	`number`	Estimated credits.
├`recommendedMaxCreditCap`	`number`	Recommended cap for this request.
├`maxCreditCap`	`number`	Applied cap for this request.
├`budgetMode`	`string`	How the cap was selected. `RECOMMENDED_CAPUSER_LIMITEDUSER_CUSTOM_CAP`
├`estimatedReachableEmailsAtCap`	`integer`nullable	Estimated reachable lead count under the applied cap.
├`warnings`	`array`	Customer-facing warnings.
├`summary`	`object`	Budget summary for review UI.
├`maxCreditSpend`	`number`	Applied maximum credit spend.
├`recommendedMaxCreditSpend`	`number`	Recommended maximum credit spend.
├`budgetMode`	`string`	Budget mode label.
├`targetMode`	`string`	Targeting mode label.
├`targetEmails`	`integer`nullable	Requested lead goal when applicable.
├`scan`	`object`	Scan quantity summary.
├`count`	`integer`	Scan count.
├`unit`	`string`	Scan unit.
├`findHiddenEmails`	`object`	Hidden-email search summary.
├`enabled`	`boolean`	Whether hidden-email search is enabled.
├`profilesToCheck`	`integer`	Profiles to check.
├`estimatedCreditCost`	`number`	Estimated credits for this part of the preview.
├`publicEmailRate`	`object`nullable	Public email estimate range.
├`lower`	`number`	Lower bound.
├`upper`	`number`	Upper bound.
├`estimatedEmails`	`integer`	Estimated emails.
├`estimatedReachableEmailsAtCap`	`integer`nullable	Estimated reachable lead count under the cap.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X POST https://api.scravio.com/api/campaigns/reserve-preview \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
}'

curl -X POST https://api.scravio.com/api/campaigns/reserve-preview \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
}'

const res = await fetch('https://api.scravio.com/api/campaigns/reserve-preview', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
})
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/reserve-preview', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
})
});
const data = await res.json();

POST/campaigns

API keyBearer/JWT

Create campaign

Creates a new campaign and reserves credits for the configured request. Call /campaigns/reserve-preview first, then send the same top-level campaign settings to creation. Campaign input rules: - INSTAGRAM_HASHTAG accepts inputs.hashtag or inputs.hashtags (max 20). - Instagram user follower/following campaigns accept inputs.targetUser or inputs.targetUsers. Paid workspaces support up to 20 targets; free and Project Pass workspaces support up to 2. - Instagram post liker/commenter campaigns accept inputs.mediaUrl or inputs.mediaUrls. Paid workspaces support up to 20 targets; free and Project Pass workspaces support up to 2. - INSTAGRAM_PROFILE_LIST accepts inputs.profileTargets (max 10000) and does not use targetEmails. - Keyword search types, TIKTOK_SEARCH_USERS, and YOUTUBE_CHANNEL_SEARCH accept inputs.keyword or inputs.keywords (max 20, 2-200 characters each). - YOUTUBE_CHANNEL_SEARCH accepts inputs.youtubeDiscoverySource as channel or video; default is channel. - GOOGLE_MAPS_SEARCH requires inputs.query, one country or countries value, lat, lng, and optional zoom from 1 to 21. The backend controls lang, limit, and offset. - X_FOLLOWERS, X_FOLLOWING, TIKTOK_USER_FOLLOWERS, and TIKTOK_USER_FOLLOWING use inputs.targetUser. - X_RETWEETS, X_REPLIERS, and TIKTOK_POST_COMMENTERS use inputs.mediaUrl. - Optional inputs.countries applies to Instagram, X, YouTube channel search, and keyword search. - Optional inputs.followerFilter with min and max applies to supported profile, list, post, TikTok, X, and YouTube channel campaigns. - Optional Instagram filters scrapeBusinessAccountsOnly and scrapePrivateAccounts apply to non-keyword Instagram campaigns. - targetEmails is required for new lead-target campaigns except INSTAGRAM_PROFILE_LIST. - maxCreditCap is optional and must be positive when provided. - enableDeepEmailSearch is accepted for backward compatibility; unsupported email-only types ignore it. - enrichIgPosts is Instagram-only and defaults to false.

X-Workspace-Id supportedPermission: create_campaignWorkspace-scoped API keys supported

Request Bodyrequired

application/json

Field	Type	Description
`title`	`string`	Human-readable campaign name. Auto-generated if omitted.(max 100 chars)
`type`required	`string`	Campaign type. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERSGOOGLE_MAPS_SEARCH`
`inputs`required	`object`	Type-specific campaign inputs.
├`hashtag`	`string`	Single hashtag for INSTAGRAM_HASHTAG campaigns. Omit the # prefix.(max 100 chars)
├`hashtags`	`array`	Multiple hashtags for INSTAGRAM_HASHTAG campaigns.(max 20 items)
├`targetUser`	`string`	Single profile handle for user-based campaigns.(max 100 chars)
├`targetUsers`	`array`	Multiple profile handles for supported Instagram user campaigns.(max 20 items)
├`mediaUrl`	`string<uri>`	Single public post URL for post-based campaigns.(max 2048 chars)
├`mediaUrls`	`array`	Multiple public post URLs for supported Instagram post campaigns.(max 20 items)
├`profileTargets`	`array`	Profile handles or URLs for INSTAGRAM_PROFILE_LIST campaigns.(max 10000 items)
├`keyword`	`string`	Single search keyword for keyword campaigns.(max 200 chars)
├`keywords`	`array`	Multiple search keywords.(max 20 items)
├`youtubeDiscoverySource`	`string`	Discovery source for YOUTUBE_CHANNEL_SEARCH.Default: `channel` `channelvideo`
├`query`	`string`	Search query for GOOGLE_MAPS_SEARCH.(max 200 chars)
├`country`	`string`	Country code for GOOGLE_MAPS_SEARCH. Send exactly one country or countries value.(max 2 chars)
├`countries`	`array`	Optional country filters. For GOOGLE_MAPS_SEARCH, send exactly one value.(max 10 items)
├`lat`	`number`	Latitude for GOOGLE_MAPS_SEARCH.
├`lng`	`number`	Longitude for GOOGLE_MAPS_SEARCH.
├`zoom`	`integer`	Map zoom for GOOGLE_MAPS_SEARCH.Default: `12`(1–21)
├`followerFilter`	`object`	Optional follower range for supported campaign types.
├`min`	`integer`	Minimum follower count.
├`max`	`integer`	Maximum follower count.
├`scrapeBusinessAccountsOnly`	`boolean`	Instagram-only filter for business profiles.Default: `false`
├`scrapePrivateAccounts`	`boolean`	Instagram-only private-profile setting.Default: `true`
`targetEmails`	`integer`	Requested lead goal. Required for lead-target campaigns and omitted for INSTAGRAM_PROFILE_LIST.
`maxCreditCap`	`number`	Optional positive hard cap. If omitted, creation uses the reserved estimate.
`enableEmailValidation`	`boolean`	Validate emails during the campaign.Default: `false`
`enableDeepEmailSearch`	`boolean`	Backward-compatible flag for supported campaign types.
`enrichIgPosts`	`boolean`	Instagram-only post enrichment flag.Default: `false`

Responses

201Campaign created

Field	Type	Description
`campaign`	`object`	Customer-safe campaign summary.
├`id`	`string`	Campaign ID.
├`title`	`string`	Campaign title.
├`type`	`string`	Campaign type. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERSGOOGLE_MAPS_SEARCH`
├`status`	`string`	Current campaign status. `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
├`inputs`	`object`	Submitted campaign inputs.
├`targetEmails`	`integer`nullable	Requested lead goal for lead-target campaigns.
├`targetMode`	`string`	Campaign targeting mode. `LEAD_TARGETITEM_LIMIT`
├`maxCreditCap`	`number`nullable	Configured campaign credit cap.
├`progressPercentage`	`number`	Progress from 0 to 100.
├`emailCount`	`integer`	Emails found so far.
├`profileCount`	`integer`	Profiles or items processed so far.
├`enableEmailValidation`	`boolean`	Whether campaign email validation is enabled.
├`enableDeepEmailSearch`	`boolean`	Whether supported hidden-email search is enabled.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`updatedAt`	`string<date-time>`	Last update timestamp.
├`finishedAt`	`string<date-time>`nullable	Completion timestamp.

Example

curl -X POST https://api.scravio.com/api/campaigns \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "June partner prospecting",
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
}'

curl -X POST https://api.scravio.com/api/campaigns \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "June partner prospecting",
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
}'

const res = await fetch('https://api.scravio.com/api/campaigns', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "title": "June partner prospecting",
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
})
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "title": "June partner prospecting",
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "designsystems",
      "growthops"
    ]
  },
  "targetEmails": 500,
  "maxCreditCap": 2500,
  "enableEmailValidation": true
})
});
const data = await res.json();

GET/campaigns

API keyBearer/JWT

List campaigns

Returns a paginated list of campaigns visible to the effective account and workspace.

X-Workspace-Id supportedPermission: view_campaignWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page number.Default: `1`
`perPage`	query	`integer`	Items per page.Default: `10`
`status`	query	`string`	Filter by campaign status. `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
`type`	query	`string`	Filter by campaign type or platform shorthand.
`q`	query	`string`	Search campaign title or target input.
`sortBy`	query	`string`	Sort field.Default: `createdAt` `createdAtprogressstatus`
`order`	query	`string`	Sort direction.Default: `desc` `ascdesc`
`from`	query	`string`	Start date filter.
`to`	query	`string`	End date filter.

Responses

200Paginated campaign list

Field	Type	Description
`items`	`array`	Campaign summaries.
├`id`	`string`	Campaign ID.
├`title`	`string`	Campaign title.
├`type`	`string`	Campaign type. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERSGOOGLE_MAPS_SEARCH`
├`status`	`string`	Current campaign status. `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
├`inputs`	`object`	Submitted campaign inputs.
├`targetEmails`	`integer`nullable	Requested lead goal for lead-target campaigns.
├`targetMode`	`string`	Campaign targeting mode. `LEAD_TARGETITEM_LIMIT`
├`maxCreditCap`	`number`nullable	Configured campaign credit cap.
├`progressPercentage`	`number`	Progress from 0 to 100.
├`emailCount`	`integer`	Emails found so far.
├`profileCount`	`integer`	Profiles or items processed so far.
├`enableEmailValidation`	`boolean`	Whether campaign email validation is enabled.
├`enableDeepEmailSearch`	`boolean`	Whether supported hidden-email search is enabled.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`updatedAt`	`string<date-time>`	Last update timestamp.
├`finishedAt`	`string<date-time>`nullable	Completion timestamp.
`pagination`	`object`	Pagination details.
├`totalCount`	`integer`	Total matching records.
├`totalPages`	`integer`	Total pages available.
├`currentPage`	`integer`	Current page number.
├`perPage`	`integer`	Records returned per page.

Example

curl -X GET https://api.scravio.com/api/campaigns?page=1&perPage=10&status=fully_completed \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/campaigns?page=1&perPage=10&status=fully_completed \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/campaigns?page=1&perPage=10&status=fully_completed', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns?page=1&perPage=10&status=fully_completed', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

GET/campaigns/export-schemas

API keyBearer/JWT

Get export schemas

Returns static export schema details for supported campaign result formats. The response contains column keys and labels only.

X-Workspace-Id supportedPermission: create_campaignWorkspace-scoped API keys supported

Responses

200Export schemas

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Schema response.
├`schemas`	`array`	Available export schemas.
├`key`	`string`	Schema key.
├`label`	`string`	Display label.
├`columns`	`array`	Column definitions.
├`key`	`string`	Column key.
├`label`	`string`	Column label.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X GET https://api.scravio.com/api/campaigns/export-schemas \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/campaigns/export-schemas \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/campaigns/export-schemas', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/export-schemas', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

GET/campaigns/{id}

API keyBearer/JWT

Get campaign details

Returns the customer-safe detail view for a single campaign in the effective workspace.

X-Workspace-Id supportedPermission: view_campaignWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID.

Responses

200Campaign detail

Field	Type	Description
`campaign`	`object`	Customer-safe campaign detail.
├`id`	`string`	Campaign ID.
├`title`	`string`	Campaign title.
├`type`	`string`	Campaign type. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERSGOOGLE_MAPS_SEARCH`
├`status`	`string`	Current campaign status. `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
├`inputs`	`object`	Submitted campaign inputs.
├`targetEmails`	`integer`nullable	Requested lead goal for lead-target campaigns.
├`targetMode`	`string`	Campaign targeting mode. `LEAD_TARGETITEM_LIMIT`
├`maxCreditCap`	`number`nullable	Configured campaign credit cap.
├`progressPercentage`	`number`	Progress from 0 to 100.
├`emailCount`	`integer`	Emails found so far.
├`profileCount`	`integer`	Profiles or items processed so far.
├`enableEmailValidation`	`boolean`	Whether campaign email validation is enabled.
├`enableDeepEmailSearch`	`boolean`	Whether supported hidden-email search is enabled.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`updatedAt`	`string<date-time>`	Last update timestamp.
├`finishedAt`	`string<date-time>`nullable	Completion timestamp.
├`postValidation`	`object`nullable	Post-campaign validation summary when present.
├`status`	`string`	Validation status.
├`total`	`integer`	Emails selected for validation.
├`validated`	`integer`	Emails processed.
├`valid`	`integer`	Valid email count.
├`invalid`	`integer`	Invalid email count.

404Campaign not found.

Example

curl -X GET https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

GET/campaigns/{id}/leads

API keyBearer/JWT

List campaign leads

Returns a paginated list of leads for a campaign. Responses use synthetic examples in these docs; production responses contain customer-owned lead records and may mask emails based on account state.

X-Workspace-Id supportedPermission: view_campaignWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID.
`page`	query	`integer`	Page number.Default: `1`
`perPage`	query	`integer`	Items per page.Default: `10`
`hasEmail`	query	`boolean`	Filter leads with or without an email.
`validationStatus`	query	`string`	Filter by validation status. `validinvalidpending`
`platform`	query	`string`	Filter by source platform.
`sourceType`	query	`string`	Filter by lead source type.
`emailSource`	query	`string`	Filter by email source.
`sortBy`	query	`string`	Sort field.Default: `hasEmail` `hasEmailfollowerCountscrapedAt`
`order`	query	`string`	Sort direction.Default: `desc` `ascdesc`

Responses

200Paginated lead list

Field	Type	Description
`items`	`array`	Lead records.
├`id`	`string`	Lead ID.
├`campaignId`	`string`	Campaign ID.
├`platform`	`string`	Source platform. `instagramyoutubelinkedinfacebooktiktokxgoogle_maps`
├`sourceType`	`string`	Lead source type.
├`email`	`string<email>`nullable	Email address when available. The value may be masked for the current account.
├`emailMasked`	`boolean`	Whether email fields are masked in this response.
├`emailRevealed`	`boolean`	Whether this row has been individually revealed for the current account.
├`canRevealEmail`	`boolean`	Whether this row can be revealed in the dashboard.
├`emailSource`	`string`nullable	How Scravio found the email.
├`username`	`string`nullable	Profile username or handle.
├`fullName`	`string`nullable	Profile display name.
├`biography`	`string`nullable	Profile biography.
├`externalUrl`	`string`nullable	Website from the profile.
├`phoneNumber`	`string`nullable	Phone number when present.
├`followerCount`	`integer`nullable	Follower count.
├`followingCount`	`integer`nullable	Following count.
├`mediaCount`	`integer`nullable	Post or media count.
├`isPrivate`	`boolean`nullable	Whether the profile is private.
├`isVerified`	`boolean`nullable	Whether the profile is verified.
├`isBusiness`	`boolean`nullable	Whether the profile is a business account.
├`country`	`string`nullable	Country when available.
├`emailValidation`	`object`nullable	Customer-safe validation result when validation has run.
├`status`	`string`	Validation status.
├`isValid`	`boolean`	Whether the email is valid.
├`checkedAt`	`string<date-time>`	Validation timestamp.
├`scrapedAt`	`string<date-time>`	Lead discovery timestamp.
`pagination`	`object`	Pagination details.
├`totalCount`	`integer`	Total matching records.
├`totalPages`	`integer`	Total pages available.
├`currentPage`	`integer`	Current page number.
├`perPage`	`integer`	Records returned per page.

Example

curl -X GET https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/leads?hasEmail=true&page=1&perPage=20 \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/leads?hasEmail=true&page=1&perPage=20 \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/leads?hasEmail=true&page=1&perPage=20', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/leads?hasEmail=true&page=1&perPage=20', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

POST/campaigns/{id}/stop

API keyBearer/JWT

Stop a running campaign

Requests a graceful stop for a running campaign. The command is safe to call more than once.

X-Workspace-Id supportedPermission: create_campaignWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID.

Request Body

application/json

Field	Type	Description
`reason`	`string`	Optional stop reason.(max 500 chars)

Responses

200Campaign stop requested

Field	Type	Description
`campaignId`	`string`	Campaign ID.
`stopRequested`	`boolean`	Whether the stop was accepted.
`status`	`string`	Updated campaign status.
`stoppedReason`	`string`nullable	Stop reason when provided.

Example

curl -X POST https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/stop \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Reached the weekly outreach target"
}'

curl -X POST https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/stop \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Reached the weekly outreach target"
}'

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/stop', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "reason": "Reached the weekly outreach target"
})
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/stop', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "reason": "Reached the weekly outreach target"
})
});
const data = await res.json();

GET/campaigns/{id}/validate/preview

API keyBearer/JWT

Preview post-campaign validation

Returns a customer-safe eligibility and credit preview before starting post-campaign email validation.

X-Workspace-Id supportedPermission: create_campaignWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID.

Responses

200Validation preview

Field	Type	Description
`campaignId`	`string`	Campaign ID.
`emailsToValidate`	`integer`	Emails selected for validation.
`creditCost`	`number`	Credits required.
`currentBalance`	`number`	Current available credits.
`hasSufficientCredits`	`boolean`	Whether credits are sufficient.
`canValidate`	`boolean`	Whether validation can start.

Example

curl -X GET https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate/preview \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate/preview \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate/preview', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate/preview', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

POST/campaigns/{id}/validate

API keyBearer/JWT

Start post-campaign validation

Starts asynchronous email validation for leads in a completed or stopped campaign. Use the preview endpoint first to confirm eligibility and credits.

X-Workspace-Id supportedPermission: create_campaignWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID.

Responses

202Validation started

Field	Type	Description
`campaignId`	`string`	Campaign ID.
`jobId`	`string`	Validation job ID.
`emailsToValidate`	`integer`	Emails selected for validation.
`creditCost`	`number`	Credits reserved.
`status`	`string`	Validation status.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X POST https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X POST https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/campaigns/cmp_01J7SYNTHETIC/validate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

Validation

Submit pasted email lists and inspect standalone validation jobs.

POST/validation-jobs/text

API keyBearer/JWT

Submit emails for validation

Creates a standalone validation job from an email array. Submit 1 to 5000 unique emails. API-key requests must use an account-scoped key.

X-Workspace-Id supportedAccount-scoped API keys only

Bearer requests may use X-Workspace-Id. API-key requests must use an account-scoped key; workspace-scoped keys are rejected.

Request Bodyrequired

application/json

Field	Type	Description
`emails`required	`array`	Email addresses to validate. Duplicates are removed case-insensitively.(max 5000 items)

Responses

201Validation job created

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Validation job summary.
├`jobId`	`string`	Validation job ID.
├`status`	`string`	Validation job status. `pendingqueuedprocessingcompletedfailedcancelled`
├`totalEmails`	`integer`	Total unique emails submitted.
├`processedCount`	`integer`	Emails processed so far.
├`validCount`	`integer`	Valid email count.
├`invalidCount`	`integer`	Invalid email count.
├`downloadUrl`	`string`nullable	Opaque short-lived Scravio result URL when the job is completed.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`completedAt`	`string<date-time>`nullable	Completion timestamp.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X POST https://api.scravio.com/api/validation-jobs/text \
  -H "X-API-Key: sk_live_example_key" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}'

curl -X POST https://api.scravio.com/api/validation-jobs/text \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}'

const res = await fetch('https://api.scravio.com/api/validation-jobs/text', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
})
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/validation-jobs/text', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
})
});
const data = await res.json();

GET/validation-jobs

API keyBearer/JWT

List validation jobs

Returns a sanitized paginated list of standalone validation jobs. API-key requests must use an account-scoped key.

X-Workspace-Id supportedAccount-scoped API keys only

Bearer requests may use X-Workspace-Id. API-key requests must use an account-scoped key; workspace-scoped keys are rejected.

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page number.Default: `1`
`limit`	query	`integer`	Items per page.Default: `10`
`status`	query	`string`	Filter by job status. `pendingqueuedprocessingcompletedfailedcancelled`
`provider`	query	`string`	Filter by validation source where available.
`from`	query	`string`	Start date filter.
`to`	query	`string`	End date filter.
`sortBy`	query	`string`	Sort field.Default: `createdAt` `createdAtcompletedAt`
`order`	query	`string`	Sort direction.Default: `desc` `ascdesc`

Responses

200Paginated validation job list

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Validation jobs page.
├`jobs`	`array`	Validation jobs.
├`jobId`	`string`	Validation job ID.
├`status`	`string`	Validation job status. `pendingqueuedprocessingcompletedfailedcancelled`
├`totalEmails`	`integer`	Total unique emails submitted.
├`processedCount`	`integer`	Emails processed so far.
├`validCount`	`integer`	Valid email count.
├`invalidCount`	`integer`	Invalid email count.
├`downloadUrl`	`string`nullable	Opaque short-lived Scravio result URL when the job is completed.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`completedAt`	`string<date-time>`nullable	Completion timestamp.
├`total`	`integer`	Total job count.
├`page`	`integer`	Current page.
├`pages`	`integer`	Total pages.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X GET https://api.scravio.com/api/validation-jobs?page=1&limit=10&status=completed \
  -H "X-API-Key: sk_live_example_key"

curl -X GET https://api.scravio.com/api/validation-jobs?page=1&limit=10&status=completed \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch('https://api.scravio.com/api/validation-jobs?page=1&limit=10&status=completed', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/validation-jobs?page=1&limit=10&status=completed', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>'
  }
});
const data = await res.json();

GET/validation-jobs/{id}

API keyBearer/JWT

Get validation job details

Returns sanitized detail for a standalone validation job. API-key requests must use an account-scoped key.

X-Workspace-Id supportedAccount-scoped API keys only

Bearer requests may use X-Workspace-Id. API-key requests must use an account-scoped key; workspace-scoped keys are rejected.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Validation job ID.

Responses

200Validation job detail

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Validation job detail.
├`jobId`	`string`	Validation job ID.
├`status`	`string`	Validation job status. `pendingqueuedprocessingcompletedfailedcancelled`
├`totalEmails`	`integer`	Total unique emails submitted.
├`processedCount`	`integer`	Emails processed so far.
├`validCount`	`integer`	Valid email count.
├`invalidCount`	`integer`	Invalid email count.
├`downloadUrl`	`string`nullable	Opaque short-lived Scravio result URL when the job is completed.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`completedAt`	`string<date-time>`nullable	Completion timestamp.
`requestId`	`string`	Synthetic request identifier for support correlation.

404Validation job not found.

Example

curl -X GET https://api.scravio.com/api/validation-jobs/vjob_01J7SYNTHETIC \
  -H "X-API-Key: sk_live_example_key"

curl -X GET https://api.scravio.com/api/validation-jobs/vjob_01J7SYNTHETIC \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch('https://api.scravio.com/api/validation-jobs/vjob_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/validation-jobs/vjob_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>'
  }
});
const data = await res.json();

Exports

Create, list, inspect, and download campaign lead exports.

POST/list-exports

API keyBearer/JWT

Create a list export

Creates an asynchronous CSV or XLSX export from campaign leads. The webhook URL, when supplied, must be HTTPS and is treated as customer configuration.

X-Workspace-Id supportedPermission: export_resultsWorkspace-scoped API keys supported

Request Bodyrequired

application/json

Field	Type	Description
`campaignId`required	`string`	Campaign ID.
`fileFormat`	`string`	Export file format.Default: `csv` `csvxlsx`
`emailOnly`	`boolean`	Include only leads with an email.Default: `false`
`onlyValidEmails`	`boolean`	Include only validated emails.Default: `false`
`includeAIVerified`	`boolean`	Include AI-verified email data when available.Default: `false`
`dedupeByEmail`	`boolean`	Deduplicate exported rows by email.Default: `true`
`dateRange`	`object`	Optional lead discovery date range.
├`from`	`string`	Start date.
├`to`	`string`	End date.
`webhookUrl`	`string<uri>`	Optional HTTPS webhook endpoint for completion notification.

Responses

201Export created

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Export summary.
├`exportId`	`string`	Export ID.
├`campaignId`	`string`	Campaign ID.
├`status`	`string`	Export status. `pendingprocessingcompletedfailed`
├`progress`	`number`	Progress from 0 to 100.
├`fileFormat`	`string`	Export file format. `csvxlsx`
├`filename`	`string`nullable	Suggested filename when completed.
├`totalRecords`	`integer`nullable	Total records included when completed.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`completedAt`	`string<date-time>`nullable	Completion timestamp.
`requestId`	`string`	Synthetic request identifier for support correlation.

200Existing matching export returned.

Example

curl -X POST https://api.scravio.com/api/list-exports \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": "cmp_01J7SYNTHETIC",
  "fileFormat": "csv",
  "emailOnly": true,
  "onlyValidEmails": true,
  "dedupeByEmail": true,
  "webhookUrl": "https://hooks.example.com/scravio/export-ready"
}'

curl -X POST https://api.scravio.com/api/list-exports \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": "cmp_01J7SYNTHETIC",
  "fileFormat": "csv",
  "emailOnly": true,
  "onlyValidEmails": true,
  "dedupeByEmail": true,
  "webhookUrl": "https://hooks.example.com/scravio/export-ready"
}'

const res = await fetch('https://api.scravio.com/api/list-exports', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "campaignId": "cmp_01J7SYNTHETIC",
  "fileFormat": "csv",
  "emailOnly": true,
  "onlyValidEmails": true,
  "dedupeByEmail": true,
  "webhookUrl": "https://hooks.example.com/scravio/export-ready"
})
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/list-exports', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "campaignId": "cmp_01J7SYNTHETIC",
  "fileFormat": "csv",
  "emailOnly": true,
  "onlyValidEmails": true,
  "dedupeByEmail": true,
  "webhookUrl": "https://hooks.example.com/scravio/export-ready"
})
});
const data = await res.json();

GET/list-exports

API keyBearer/JWT

List exports

Returns a sanitized paginated list of export jobs in the effective workspace.

X-Workspace-Id supportedPermission: export_resultsWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page number.Default: `1`
`perPage`	query	`integer`	Items per page.Default: `10`
`campaignId`	query	`string`	Filter by campaign ID.
`status`	query	`string`	Filter by export status. `pendingprocessingcompletedfailed`
`sortBy`	query	`string`	Sort field.Default: `createdAt` `createdAtcompletedAtstatus`
`order`	query	`string`	Sort direction.Default: `desc` `ascdesc`

Responses

200Paginated export list

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Exports page.
├`exports`	`array`	Export summaries.
├`exportId`	`string`	Export ID.
├`campaignId`	`string`	Campaign ID.
├`status`	`string`	Export status. `pendingprocessingcompletedfailed`
├`progress`	`number`	Progress from 0 to 100.
├`fileFormat`	`string`	Export file format. `csvxlsx`
├`filename`	`string`nullable	Suggested filename when completed.
├`totalRecords`	`integer`nullable	Total records included when completed.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`completedAt`	`string<date-time>`nullable	Completion timestamp.
├`pagination`	`object`	Pagination details.
├`totalCount`	`integer`	Total matching records.
├`totalPages`	`integer`	Total pages available.
├`currentPage`	`integer`	Current page number.
├`perPage`	`integer`	Records returned per page.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X GET https://api.scravio.com/api/list-exports?page=1&perPage=10 \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/list-exports?page=1&perPage=10 \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/list-exports?page=1&perPage=10', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/list-exports?page=1&perPage=10', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

GET/list-exports/{id}

API keyBearer/JWT

Get export details

Returns sanitized export details. The direct file location is not exposed in this response.

X-Workspace-Id supportedPermission: export_resultsWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Export ID.

Responses

200Export detail

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Export details.
├`exportId`	`string`	Export ID.
├`campaignId`	`string`	Campaign ID.
├`status`	`string`	Export status. `pendingprocessingcompletedfailed`
├`progress`	`number`	Progress from 0 to 100.
├`fileFormat`	`string`	Export file format. `csvxlsx`
├`filename`	`string`nullable	Suggested filename when completed.
├`totalRecords`	`integer`nullable	Total records included when completed.
├`createdAt`	`string<date-time>`	Creation timestamp.
├`completedAt`	`string<date-time>`nullable	Completion timestamp.
`requestId`	`string`	Synthetic request identifier for support correlation.

404Export not found.

Example

curl -X GET https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

GET/list-exports/{id}/download

API keyBearer/JWT

Get export download URL

Returns an opaque Scravio download URL for a completed export. Do not parse or persist the returned URL.

X-Workspace-Id supportedPermission: export_resultsWorkspace-scoped API keys supported

Parameters

Name	In	Type	Description
`id`required	path	`string`	Export ID.

Responses

200Export download URL

Field	Type	Description
`success`	`boolean`	Request success status.
`data`	`object`	Opaque download response.
├`downloadUrl`	`string<uri>`	Opaque Scravio download URL.
├`filename`	`string`	Suggested filename.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X GET https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC/download \
  -H "X-API-Key: sk_live_example_key" \
  -H "X-Workspace-Id: ws_example_team"

curl -X GET https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC/download \
  -H "Authorization: Bearer <accessToken>" \
  -H "X-Workspace-Id: ws_example_team"

const res = await fetch('https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC/download', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/list-exports/exp_01J7SYNTHETIC/download', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>',
    'X-Workspace-Id': 'ws_example_team'
  }
});
const data = await res.json();

GET/list-exports/download/{downloadId}

PublicBearer/JWT

Follow export download redirect

Public redirect endpoint returned by the authenticated download request. Do not send X-API-Key to this route. Optional auth, when used, must be Bearer/JWT.

Parameters

Name	In	Type	Description
`downloadId`required	path	`string`	Opaque download ID from downloadUrl.

Responses

302Redirects to the export file.

304Not modified when cache validators match.

404Download link not found or expired.

Example

curl -L -X GET https://api.scravio.com/api/list-exports/download/dl_01J7SYNTHETIC

curl -L -X GET https://api.scravio.com/api/list-exports/download/dl_01J7SYNTHETIC \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch('https://api.scravio.com/api/list-exports/download/dl_01J7SYNTHETIC', {
  method: 'GET',
  redirect: 'follow'
});
const file = await res.blob();

const res = await fetch('https://api.scravio.com/api/list-exports/download/dl_01J7SYNTHETIC', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>'
  },
  redirect: 'follow'
});
const file = await res.blob();

Credits

Read the customer-safe credit transaction ledger.

GET/credit-transactions

API keyBearer/JWT

List credit transactions

Returns a paginated ledger of customer-visible credit balance changes. API-key requests must use an account-scoped key.

Account-scopedAccount-scoped API keys only

This endpoint is account-scoped. Do not send X-Workspace-Id.

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page number.Default: `1`
`perPage`	query	`integer`	Items per page.Default: `10`
`type`	query	`string`	Filter by transaction type.
`campaignId`	query	`string`	Filter by campaign ID.
`from`	query	`string`	Start date filter.
`to`	query	`string`	End date filter.
`sortBy`	query	`string`	Sort field.Default: `timestamp` `timestampamount`
`order`	query	`string`	Sort direction.Default: `desc` `ascdesc`

Responses

200Paginated transaction list

Field	Type	Description
`transactions`	`array`	Credit transactions.
├`id`	`string`	Transaction ID.
├`timestamp`	`string<date-time>`	Transaction timestamp.
├`balanceBefore`	`number`	Balance before the transaction.
├`amount`	`number`	Signed credit amount.
├`balanceAfter`	`number`	Balance after the transaction.
├`type`	`string`	Transaction type.
├`description`	`string`	Customer-visible description.
├`campaignId`	`string`nullable	Related campaign ID when applicable.
├`details`	`object`nullable	Whitelisted receipt fields when applicable.
├`kind`	`string`nullable	Receipt kind.
├`reservedCredits`	`number`nullable	Credits reserved for a campaign.
├`usedCredits`	`number`nullable	Credits used by a campaign.
├`returnedCredits`	`number`nullable	Unused credits returned.
├`amountPaid`	`number`nullable	Amount paid for a purchase.
├`method`	`string`nullable	Payment method family. `cardcrypto`
├`createdAt`	`string<date-time>`	Creation timestamp.
`pagination`	`object`	Pagination details.
├`totalCount`	`integer`	Total matching records.
├`totalPages`	`integer`	Total pages available.
├`currentPage`	`integer`	Current page number.
├`perPage`	`integer`	Records returned per page.
`requestId`	`string`	Synthetic request identifier for support correlation.

Example

curl -X GET https://api.scravio.com/api/credit-transactions?page=1&perPage=10&sortBy=timestamp&order=desc \
  -H "X-API-Key: sk_live_example_key"

curl -X GET https://api.scravio.com/api/credit-transactions?page=1&perPage=10&sortBy=timestamp&order=desc \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch('https://api.scravio.com/api/credit-transactions?page=1&perPage=10&sortBy=timestamp&order=desc', {
  method: 'GET',
  headers: {
    'X-API-Key': 'sk_live_example_key'
  }
});
const data = await res.json();

const res = await fetch('https://api.scravio.com/api/credit-transactions?page=1&perPage=10&sortBy=timestamp&order=desc', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <accessToken>'
  }
});
const data = await res.json();

TOC