Skip to content

Validate matching inputs

POST
/v1/match/validate
curl --request POST \
--url https://api.infiniteaudience.ai/v1/match/validate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "records": [ {} ], "field_list": [ "example" ], "template_id": "example", "match_level": [ "I" ], "spatial_mode": "residential", "create_scratch_segment": true }'

Requires ‘discovery’ scope. Checks the same request shape and effective row-ID uniqueness as POST /v1/match, without executing matching, querying BigQuery, writing durable state or reserving capacity. Authentication/session security bookkeeping and in-memory rate limits still apply. Does not check identity existence, live output fields/templates, execution eligibility or cost. Invalid input returns paths and codes without echoing submitted identity data. This is not a matching simulation or a delivery quote.

Media typeapplication/json
object
records
required
Array<object>
>= 1 items <= 100 items
object
key
additional properties
any
field_list
Array<string>
template_id
string
match_level
Array<string>
Allowed values: I H D S A
spatial_mode
string
default: residential
Allowed values: residential work auto
create_scratch_segment
boolean

Input shape and row IDs passed; execution is not guaranteed.

Media typeapplication/json
object
valid
required
boolean
record_count
required
integer
>= 1 <= 100
billable
required
boolean
checks
required
Array<string>
not_checked
required
Array<string>
Example
{
"valid": true,
"billable": false
}

Request shape or effective row IDs are invalid. No matching or billing was performed.

Media typeapplication/json
object
error
required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string
message
required

Human-readable explanation of the error.

string
code
required

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string
request_id

Opaque support/debug identifier when available.

string
next_step

Public action for correcting the request or retrying later.

string
issues
required
Array<object>
object
path
required

JSON path to the invalid filter field or value.

string
code
required
string
Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE
message
required
string
suggestions
Array<string>
issues
required
Array<object>
object
path
required
string
code
required
string
Example
{
"issues": [
{
"code": "INVALID_FILTER_SHAPE"
}
]
}

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

Media typeapplication/json
object
error
required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string
message

Human-readable explanation of the error.

string
code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string
request_id

Opaque support/debug identifier when available.

string
next_step

Public action for correcting the request or retrying later.

string
issues
Array<object>
object
path
required

JSON path to the invalid filter field or value.

string
code
required
string
Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE
message
required
string
suggestions
Array<string>
key
additional properties
any
Examples
{
"error": "Unauthorized: Missing or invalid Authorization header"
}

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json
object
error
required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string
message

Human-readable explanation of the error.

string
code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string
request_id

Opaque support/debug identifier when available.

string
next_step

Public action for correcting the request or retrying later.

string
issues
Array<object>
object
path
required

JSON path to the invalid filter field or value.

string
code
required
string
Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE
message
required
string
suggestions
Array<string>
key
additional properties
any
Examples
Examplemissing_scope
{
"error": "SCOPE_REQUIRED",
"message": "This endpoint requires the creator scope."
}

Request throttled. Two distinct conditions return 429: Rate limit — too many requests per minute for your tier (error: rate_limit_exceeded); retry after retry_after_seconds. Compute ceiling — org-level query-scan budget exhausted (error: compute_limit_exceeded); resets hourly or on plan upgrade.

Media typeapplication/json
object
error
required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string
message

Human-readable explanation of the error.

string
code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string
request_id

Opaque support/debug identifier when available.

string
next_step

Public action for correcting the request or retrying later.

string
issues
Array<object>
object
path
required

JSON path to the invalid filter field or value.

string
code
required
string
Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE
message
required
string
suggestions
Array<string>
key
additional properties
any
Examples
{
"error": "rate_limit_exceeded",
"message": "Rate limit of 100 requests/minute exceeded for tier 'pilot'.",
"retry_after_seconds": 45
}