Build or extend a segment from saved integration matches

POST

/v1/integration-match-collections/{collectionId}/materializations

const url = 'https://api.infiniteaudience.ai/v1/integration-match-collections/example/materializations';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"mode":"new_segment","segment_name":"example","target_segment_id":"example","filters":{"providers":["example"],"connection_ids":["example"],"integration_run_ids":["example"],"source_kinds":["recurring"],"boundary_at_from":"2026-04-15T12:00:00Z","boundary_at_to":"2026-04-15T12:00:00Z"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.infiniteaudience.ai/v1/integration-match-collections/example/materializations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "mode": "new_segment", "segment_name": "example", "target_segment_id": "example", "filters": { "providers": [ "example" ], "connection_ids": [ "example" ], "integration_run_ids": [ "example" ], "source_kinds": [ "recurring" ], "boundary_at_from": "2026-04-15T12:00:00Z", "boundary_at_to": "2026-04-15T12:00:00Z" } }'

Idempotently creates a matched segment or extends a compatible standalone matched segment without rerunning matching, creating an audience, or recording usage. Requires ‘purchase’ scope.

Authorizations

bearerAuth

Parameters

Path Parameters

collectionId

required

string

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 240 characters

Request Body^required

application/json

object

mode

required

string

Allowed values: new_segment add_to_segment

segment_name

string

>= 1 characters <= 120 characters

target_segment_id

string

filters

object

providers

Array<string>

<= 20 items

connection_ids

Array<string>

<= 100 items

integration_run_ids

Array<string>

<= 100 items

source_kinds

Array<string>

<= 3 items

Allowed values: recurring batch file

boundary_at_from

string format: date-time

boundary_at_to

string format: date-time

Responses

200

Existing idempotent materialization

application/json

object

materialization_id

required

string

collection_id

required

string

mode

required

string

Allowed values: new_segment add_to_segment

status

required

string

Allowed values: created processing completed failed

filters

required

object

providers

Array<string>

<= 20 items

connection_ids

Array<string>

<= 100 items

integration_run_ids

Array<string>

<= 100 items

source_kinds

Array<string>

<= 3 items

Allowed values: recurring batch file

boundary_at_from

string format: date-time

boundary_at_to

string format: date-time

source_cutoff_at

required

string format: date-time

target_segment_id

required

string

target_segment_name

required

string | null

target_segment_version

required

integer | null

>= 1

preview

required

One of:

object
null

object

source_observations

required

integer

unique_identities

required

integer

duplicate_observations

required

integer

expired_identities

required

integer

suppressed_identities

required

integer

already_present

required

integer

net_additions

required

integer

identity_count

required

integer | null

match_levels

required

Array<string>

Allowed values: I H D S A

failure_code

required

string | null

failure_message

required

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

completed_at

required

string | null format: date-time

Example

{
  "mode": "new_segment",
  "status": "created",
  "filters": {
    "source_kinds": [
      "recurring"
    ]
  },
  "match_levels": [
    "I"
  ]
}

201

Materialization completed and the segment is available

application/json

object

materialization_id

required

string

collection_id

required

string

mode

required

string

Allowed values: new_segment add_to_segment

status

required

string

Allowed values: created processing completed failed

filters

required

object

providers

Array<string>

<= 20 items

connection_ids

Array<string>

<= 100 items

integration_run_ids

Array<string>

<= 100 items

source_kinds

Array<string>

<= 3 items

Allowed values: recurring batch file

boundary_at_from

string format: date-time

boundary_at_to

string format: date-time

source_cutoff_at

required

string format: date-time

target_segment_id

required

string

target_segment_name

required

string | null

target_segment_version

required

integer | null

>= 1

preview

required

One of:

object
null

object

source_observations

required

integer

unique_identities

required

integer

duplicate_observations

required

integer

expired_identities

required

integer

suppressed_identities

required

integer

already_present

required

integer

net_additions

required

integer

identity_count

required

integer | null

match_levels

required

Array<string>

Allowed values: I H D S A

failure_code

required

string | null

failure_message

required

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

completed_at

required

string | null format: date-time

Example

{
  "mode": "new_segment",
  "status": "created",
  "filters": {
    "source_kinds": [
      "recurring"
    ]
  },
  "match_levels": [
    "I"
  ]
}

202

Materialization intent is durable and queued for processing

application/json

object

materialization_id

required

string

collection_id

required

string

mode

required

string

Allowed values: new_segment add_to_segment

status

required

string

Allowed values: created processing completed failed

filters

required

object

providers

Array<string>

<= 20 items

connection_ids

Array<string>

<= 100 items

integration_run_ids

Array<string>

<= 100 items

source_kinds

Array<string>

<= 3 items

Allowed values: recurring batch file

boundary_at_from

string format: date-time

boundary_at_to

string format: date-time

source_cutoff_at

required

string format: date-time

target_segment_id

required

string

target_segment_name

required

string | null

target_segment_version

required

integer | null

>= 1

preview

required

One of:

object
null

object

source_observations

required

integer

unique_identities

required

integer

duplicate_observations

required

integer

expired_identities

required

integer

suppressed_identities

required

integer

already_present

required

integer

net_additions

required

integer

identity_count

required

integer | null

match_levels

required

Array<string>

Allowed values: I H D S A

failure_code

required

string | null

failure_message

required

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

completed_at

required

string | null format: date-time

Example

{
  "mode": "new_segment",
  "status": "created",
  "filters": {
    "source_kinds": [
      "recurring"
    ]
  },
  "match_levels": [
    "I"
  ]
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

application/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

key

additional properties

any

Examples

validation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

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).

application/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

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

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

application/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

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

404

Resource not found or not accessible to the calling org.

application/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

key

additional properties

any

Examples

not_found

{
  "error": "Audience not found"
}

409

Resource state conflicts with the request. For upload analysis this includes FILE_NOT_YET_UPLOADED.

application/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

key

additional properties

any

Example^generated

{
  "error": "example",
  "message": "example",
  "code": "example",
  "request_id": "example"
}

Build or extend a segment from saved integration matches

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

201

Example

202

Example

400

Examples

401

Examples

403

Examples

404

Examples

409

Examplegenerated

Request Body^required

Example^generated