API Reference

Ava Data API Reference

Skip trace one record or a hundred thousand, over REST. Credits are charged only when a search returns a match, so a miss costs nothing. This page is generated from the OpenAPI spec — it is the same document the API is built against.

Base URL and authentication

All endpoints are relative to https://app.avadata.ai/api/v1. Authenticate with a bearer token in the Authorization header:

HEADER

Authorization: Bearer sk_live_your_api_key_here

Include your API key in the Authorization header using the Bearer scheme: `Authorization: Bearer sk_live_your_api_key_here`. Keys are generated from Settings → API Access once an administrator enables API access for your account. Rate limited to 60 requests per minute per key.

Verify a key with the cheapest call in the API — reading your credit balance costs nothing:

GET /credits

curl -X GET https://app.avadata.ai/api/v1/credits \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Every request and response example below is generated from the spec. Where the spec supplies an example value, that value is shown; where it does not, the field shows its type, and a nullable field with no example shows null. Optional and conditional fields are printed at their full shape — the tables say when each one is actually returned.

API access is enabled per account. If your key returns 401, email support@avadata.ai to have it switched on, then generate the key from Settings → API Access in the dashboard.

What a call costs

Billing is per match, not per request. A search that returns nothing charges zero credits, and on a server error any charged credits are refunded for search endpoints.

Call	Credits	Cost
Standard Search — phone only	1	2¢
Standard Search — phone + email	2	4¢
Deep Search — adds related persons	10	20¢

Bulk jobs reserve credits at upload and reconcile to actual matches when the job finishes, so unmatched rows are released rather than billed.

Search

Single-record skip trace searches.

POST /deep-search

Deep Search

Comprehensive skip trace returning phone numbers, email addresses, and related persons/family members. Costs 10 credits per match. Credits are only charged when a match is found.

Example request

POST /deep-search

curl -X POST https://app.avadata.ai/api/v1/deep-search \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  }'

Example response

200 application/json

{
  "success": true,
  "data": {
    "matchFound": true,
    "creditsCharged": 10,
    "subject": {
      "firstName": "John",
      "lastName": "Smith",
      "aliases": [
        "string"
      ],
      "age": null,
      "dob": null,
      "deceased": null,
      "phones": [
        {
          "number": "5125551234",
          "type": "mobile"
        }
      ],
      "emails": [
        {
          "address": "john.smith@example.com"
        }
      ],
      "addresses": [
        {
          "street": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701"
        }
      ],
      "bankruptcy": null
    },
    "relatedPeople": [
      {
        "firstName": null,
        "lastName": null,
        "age": null,
        "deceased": null,
        "relationship": "Spouse",
        "phones": [
          {
            "number": "5125551234",
            "type": "mobile"
          }
        ],
        "emails": [
          {
            "address": "john.smith@example.com"
          }
        ],
        "addresses": [
          {
            "street": "123 Main St",
            "city": "Austin",
            "state": "TX",
            "zip": "78701"
          }
        ],
        "bankruptcy": null
      }
    ]
  }
}

Request body — application/json

Field	Type	Required	Notes
`firstName`	string	no	Optional. Improves match accuracy. Example: "John"
`lastName`	string	yes	Required. Example: "Smith"
`address`	string	no	Example: "123 Main St"
`city`	string	no	Example: "Austin"
`state`	string	no	Example: "TX"
`zip`	string	no	Example: "78701"

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`matchFound`	boolean
`creditsCharged`	integer	10 when a match is found, otherwise 0. Example: 10
`subject`	object
`relatedPeople`	array of object

Error responses: 400, 401, 402, 403, 429, 500. See error codes below.

POST /standard-search

Standard Search

Flexible search that returns phone data, email data, or both via the dataTypes parameter. Charged 1 credit per data type per match (max 2). Credits are only charged when a match is found.

Example request

POST /standard-search

curl -X POST https://app.avadata.ai/api/v1/standard-search \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "dataTypes": [
      "phone",
      "email"
    ]
  }'

Example response

200 application/json

{
  "success": true,
  "data": {
    "matchFound": true,
    "creditsCharged": 2,
    "phones": [
      {
        "number": "5125551234",
        "type": "mobile"
      }
    ],
    "emails": [
      {
        "address": "john.smith@example.com"
      }
    ],
    "name": null,
    "addresses": [
      {
        "street": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701"
      }
    ],
    "matchType": null
  }
}

Request body — application/json

Field	Type	Required	Notes
`firstName`	string	no	Example: "John"
`lastName`	string	yes	Example: "Smith"
`address`	string	no	Example: "123 Main St"
`city`	string	no	Example: "Austin"
`state`	string	no	Example: "TX"
`zip`	string	no	Example: "78701"
`dataTypes`	array of "phone" \| "email"	yes	Which contact data to return and how credits are charged. ["phone"] = 1 credit, ["email"] = 1 credit, ["phone","email"] = 2 credits. Example: ["phone","email"]

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`matchFound`	boolean
`creditsCharged`	integer	Number of data types charged when a match is found, otherwise 0. Example: 2
`phones`	array of object	Present only when "phone" was requested and a match was found.
`emails`	array of object	Present only when "email" was requested and a match was found.
`name`	string
`addresses`	array of object
`matchType`	string

Error responses: 400, 401, 402, 403, 429, 500. See error codes below.

Bulk

High-volume CSV processing with async jobs.

POST /bulk/upload

Upload CSV for bulk processing

Upload a CSV file for high-volume Standard Search processing. The CSV must contain at minimum an 'address' column; firstName, lastName, city, state, and zip columns improve match rates. Credits are reserved upfront and adjusted to actual matches after processing completes (1 credit per data type per match). Returns a jobId to poll for status and download results.

Example request

POST /bulk/upload

curl -X POST https://app.avadata.ai/api/v1/bulk/upload \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F 'file=@contacts.csv' \
  -F 'dataTypes=["phone","email"]'

Example response

200 application/json

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "lookupId": "xyz789",
    "recordCount": 0,
    "dataTypes": [
      "phone",
      "email"
    ],
    "creditsPerMatch": 2,
    "status": "processing",
    "message": "string",
    "staffCapApplied": false
  }
}

Request body — multipart/form-data

Field	Type	Required	Notes
`file`	string	yes	CSV file (.csv). Must include a header row and at least one data row.
`dataTypes`	string	yes	JSON array string of data types to append, e.g. ["phone"], ["email"], or ["phone","email"]. Example: "[\"phone\",\"email\"]"

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`jobId`	string	Example: "abc123-def456"
`lookupId`	string	Example: "xyz789"
`recordCount`	integer
`dataTypes`	array of "phone" \| "email"
`creditsPerMatch`	integer	Example: 2
`status`	string	Example: "processing"
`message`	string
`staffCapApplied`	boolean	Present only when a staff account's per-user processing cap truncated the upload.
`originalRecordCount`	integer	Present only when staffCapApplied is true: the number of records in the original file.
`bulkProcessingCap`	integer	Present only when staffCapApplied is true: the maximum records this account may process.

Error responses: 400, 401, 402, 403, 429, 500. See error codes below.

GET /bulk/{jobId}/status

Check bulk job status

Poll the progress of a bulk processing job.

Example request

GET /bulk/{jobId}/status

curl -X GET https://app.avadata.ai/api/v1/bulk/abc123-def456/status \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

200 application/json

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "status": "processing",
    "progress": 65,
    "estimatedSecondsRemaining": 120,
    "numRecords": 0,
    "numMatches": null,
    "errorMessage": null
  }
}

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	yes	The job ID returned by the bulk upload endpoint.

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`jobId`	string	Example: "abc123-def456"
`status`	"uploading" \| "queued" \| "processing" \| "completed" \| "failed"	Job lifecycle status. Example: "processing"
`progress`	integer	Percent complete (0-100). Example: 65
`estimatedSecondsRemaining`	integer	Example: 120
`numRecords`	integer
`numMatches`	integer
`errorMessage`	string

Error responses: 401, 403, 404, 429, 500. See error codes below.

GET /bulk/{jobId}/download

Download bulk job results

Download the results of a completed bulk job as JSON (default) or CSV. The job must be in the 'completed' status.

Example request

GET /bulk/{jobId}/download

curl -X GET https://app.avadata.ai/api/v1/bulk/abc123-def456/download \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

200 application/json

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "numRecords": 0,
    "numMatches": 0,
    "creditsCharged": 624,
    "results": [
      {}
    ]
  }
}

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	yes	The job ID returned by the bulk upload endpoint.
`format`	query	"json" \| "csv"	no	Response format. Defaults to JSON. Use 'csv' to download a CSV file.

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`jobId`	string	Example: "abc123-def456"
`numRecords`	integer
`numMatches`	integer
`creditsCharged`	integer	Example: 624
`results`	array of object	Enriched per-record results. Shape mirrors your uploaded columns plus appended data.

Error responses: 400, 401, 403, 404, 429, 500. See error codes below.

Digital Matching

Turn a contact CSV into ready-to-upload Custom Audience files for major ad platforms. Securely hashed identifiers, formatted per platform.

POST /audience/upload

Upload CSV to build ad audiences

Upload a contact CSV and receive ready-to-upload Custom Audience files for the selected ad platforms. Each contact is matched against Ava Data's identity graph and every match is appended with securely hashed identifiers (the format ad platforms require) — often several verified emails and phone numbers per person, which is what lifts your matched-audience size. The CSV needs an email or phone column, or a name plus address/city/state/zip columns. Credits are reserved upfront and only matched contacts are charged (flat rate per matched contact — every selected platform included). By uploading you confirm you have the right to use the list for advertising and will follow each ad platform's customer-list policies.

Example request

POST /audience/upload

curl -X POST https://app.avadata.ai/api/v1/audience/upload \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F 'file=@contacts.csv' \
  -F 'platforms=["facebook","google"]'

Example response

200 application/json

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "lookupId": "xyz789",
    "recordCount": 0,
    "platforms": [
      "facebook",
      "google"
    ],
    "creditsPerMatch": 2,
    "status": "processing",
    "message": "string"
  }
}

Request body — multipart/form-data

Field	Type	Required	Notes
`file`	string	yes	CSV file (.csv). Must include a header row and at least one data row.
`platforms`	string	yes	JSON array string of target platforms: "facebook", "google", "linkedin", "tiktok", "generic". Example: "[\"facebook\",\"google\"]"

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`jobId`	string	Example: "abc123-def456"
`lookupId`	string	Example: "xyz789"
`recordCount`	integer
`platforms`	array of string	Example: ["facebook","google"]
`creditsPerMatch`	integer	Example: 2
`status`	string	Example: "processing"
`message`	string

Error responses: 400, 401, 402, 403, 429, 500. See error codes below.

GET /audience/{jobId}/status

Check Digital Matching job status

Poll the progress of a Digital Matching job.

Example request

GET /audience/{jobId}/status

curl -X GET https://app.avadata.ai/api/v1/audience/abc123-def456/status \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

200 application/json

{
  "success": true,
  "data": {
    "jobId": "abc123-def456",
    "status": "processing",
    "progress": 65,
    "numRecords": 0,
    "numMatches": null,
    "creditsCharged": 624,
    "platforms": [
      "facebook",
      "google"
    ],
    "platformCounts": null,
    "errorMessage": null
  }
}

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	yes	The job ID returned by the audience upload endpoint.

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`jobId`	string	Example: "abc123-def456"
`status`	"uploading" \| "queued" \| "processing" \| "completed" \| "failed"	Job lifecycle status. Example: "processing"
`progress`	integer	Percent complete (0-100). Example: 65
`numRecords`	integer
`numMatches`	integer	Matched contacts (each charged the flat per-match rate).
`creditsCharged`	integer	Example: 624
`platforms`	array of string	Example: ["facebook","google"]
`platformCounts`	object	Matched contacts per platform, populated when the job completes.
`errorMessage`	string

Error responses: 401, 403, 404, 429, 500. See error codes below.

GET /audience/{jobId}/download

Download audience files

Download the completed job's audience files. Default is a ZIP containing one ready-to-upload CSV per selected platform, a master data file, and upload instructions. Pass ?platform= to download a single platform's CSV instead. The job must be in the 'completed' status.

Example request

GET /audience/{jobId}/download

curl -X GET https://app.avadata.ai/api/v1/audience/abc123-def456/download \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -o audienceDownload.zip

Example response

By default a successful call returns application/zip — a file rather than a JSON body — so the request above writes it straight to disk with -o.

Parameters

Name	In	Type	Required	Description
`jobId`	path	string	yes	The job ID returned by the audience upload endpoint.
`platform`	query	"facebook" \| "google" \| "linkedin" \| "tiktok" \| "generic"	no	Download a single platform's CSV instead of the full ZIP.

Error responses: 400, 401, 403, 404, 429, 500. See error codes below.

Account

Credit balance and API usage.

GET /credits

Check credit balance

Returns your current credit balance, including subscription credits and wallet balance.

Example request

GET /credits

curl -X GET https://app.avadata.ai/api/v1/credits \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

200 application/json

{
  "success": true,
  "data": {
    "subscriptionCredits": 3000,
    "walletCredits": 1500,
    "reservedCredits": 0,
    "totalCredits": 4500,
    "availableCredits": 4500,
    "subscriptionStatus": "active"
  }
}

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`subscriptionCredits`	integer	Example: 3000
`walletCredits`	integer	Example: 1500
`reservedCredits`	integer	Example: 0
`totalCredits`	integer	Example: 4500
`availableCredits`	integer	Example: 4500
`subscriptionStatus`	string	Example: "active"

Error responses: 401, 404, 429, 500. See error codes below.

GET /usage

Get API usage

Returns aggregate API usage statistics plus a paginated list of recent requests.

Example request

GET /usage

curl -X GET https://app.avadata.ai/api/v1/usage \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example response

200 application/json

{
  "success": true,
  "data": {
    "stats": {
      "totalRequests": 1250,
      "totalCreditsUsed": 8400,
      "requestsToday": 45,
      "requestsThisMonth": 890
    },
    "recentActivity": [
      {
        "id": "string",
        "endpoint": "/api/v1/deep-search",
        "method": "POST",
        "statusCode": 200,
        "creditsUsed": 10,
        "timestamp": "2026-01-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "hasMore": false
    }
  }
}

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	no	Number of recent activity records to return (max 100).
`offset`	query	integer	no	Number of records to skip for pagination.

Response — every response is wrapped as { "success": true, "data": { … } }. The fields below are what data contains.

Field	Type	Notes
`stats`	object
`recentActivity`	array of object
`pagination`	object

Error responses: 401, 429, 500. See error codes below.

Error codes

Errors return { "success": false, "error": "…" } with a descriptive message. The status code tells you whether to retry, fix the request, or top up credits.

Status	Meaning
`400`	Invalid or missing request parameters.
`401`	Missing, invalid, or inactive API key, or API access not enabled.
`402`	Insufficient credits for the requested operation.
`403`	Account suspended or access denied to the requested resource.
`404`	The requested resource does not exist.
`429`	Too many requests — exceeds 60 requests per minute per API key.
`500`	Internal server error. Any charged credits are refunded for search endpoints.

429 is the one worth designing for: the limit is 60 requests per minute per key, so a bulk backfill should either use the bulk endpoints or pace itself. Retry with backoff rather than immediately.

Which endpoint should you use?

One record, need a phone or email. Standard Search. Send dataTypes with the data you want; you are charged one credit per data type, and only on a match. This is the pattern behind phone number lookup and contact enrichment.
One record, the subject is unreachable. Deep Search. It returns the related-persons graph — spouses, relatives, associates — which is the path forward when the owner's own number is dead. See relational mapping.
A whole list. Upload the CSV to the bulk endpoint, poll status, download results. Full workflow on batch skip tracing.
Turning a list into ad audiences. Digital Matching returns ready-to-upload Custom Audience files per platform. Ava Data prepares the files; you upload them to the ad platform yourself.

New to the underlying concept? Start with what skip tracing is, or read the skip tracing API overview for the commercial picture rather than the reference.

Download the spec

The machine-readable OpenAPI 3.0 document is at /openapi.json. Point your client generator at it to produce a typed SDK rather than hand-writing request code.