Skip to main content
POST
Find ad audiences
Use Find ad audiences to resolve a contact into audience identifiers and rows formatted for an advertising network. A successful result costs 5 Airscale credits per profile, regardless of the number of identifiers returned. No result costs 0 credits. Audience matching by the advertising network is not guaranteed. Authenticate using Authorization: Bearer <AIRSCALE_API_KEY> and send JSON with Content-Type: application/json.
Example request body:
Provide at least one of linkedin_url or work_email. The supported target_network values are meta, google, x, reddit, tiktok, linkedin, snapchat, pinterest, amazon, and universal. Omission or null selects universal. Other fields are rejected.

Successful response

HTTP 200 returns: person_identifiers can contain:
  • emails: pairs of original_hash and normalized_hash, with rank_order when supplied.
  • phones: digits_hash and e164_hash pairs.
  • maids: maid with device_type equal to IDFA or AAID, when known. Preserve device identifiers as returned; do not hash them again.
  • Additional SHA-256 demographic fields: fn_hash, ln_hash, ct_hash, st_hash, zp_hash, country_hash, gen_hash, doby_hash, dob_hash.
Email, phone and demographic hashes are SHA-256. A profile may match without an email, for example through a phone or a mobile advertising identifier. Use formatted_rows for the selected network; universal is network-independent data that you must map before upload. This endpoint does not create or upload an audience to an advertising account.

No result and errors

HTTP 404 for a valid lookup returns status: "not_found", the normalized inputs and selected network, person_identifiers: null, formatted_rows: [], and credits_used: 0. The public workspace limiter permits up to 60 requests per rolling second. Upstream capacity can produce additional 429 responses. There is no client-supplied idempotency key: a new HTTP request is a new lookup. After a timeout, check your balance before retrying. A new request can be charged independently.

Find hashed emails or ad audiences

Use Find hashed emails when you only need email hashes. Use this endpoint when you also need phone hashes, mobile advertising identifiers, or network-specific rows. Each operation costs 5 credits per found profile; you do not need to call both to get email hashes.

In the Airscale app

The same lookup is available as Find ad audiences in your tables. Select the target network, inspect the available identifiers in the cell details, and export a profile or the column as audience CSV when formatted rows are available. Review Authentication and rate limits before sending lookups in bulk.

Authorizations

Authorization
string
header
required

Use an Airscale workspace API key. Never expose the key in client-side code.

Body

application/json

Provide linkedin_url, work_email, or both. Other fields are rejected.

linkedin_url
string | null

LinkedIn profile URL (linkedin.com/in/...). Company pages are rejected.

Maximum string length: 512
work_email
string | null

Work email address of the person.

Maximum string length: 254
target_network
enum<string> | null
default:universal
Available options:
meta,
google,
x,
reddit,
tiktok,
linkedin,
snapchat,
pinterest,
amazon,
universal,
null

Response

Usable identifiers or formatted rows found. Costs 5 credits.

status
string
required
Allowed value: "success"
target_network
enum<string>
required
Available options:
meta,
google,
x,
reddit,
tiktok,
linkedin,
snapchat,
pinterest,
amazon,
universal
person_identifiers
object | null
required
formatted_rows
object[]
required
credits_used
number
required
credits_remaining
number | null
required
linkedin_url
string
work_email
string