Skip to content

Push ingest API

Connectors are not finished yet

Connectors work end to end, but the configuration vocabulary is still developer-facing and the dry-run flow is being revised. Showcase marks Integrations as coming soon in the editor for that reason. The rest of Audience Integrations is generally available.

Endpoint

POST /api/integrations/:connector/ingest
Authorization: Bearer <named-connector-credential>
Content-Type: application/json | text/csv | application/xml

The connector slug selects parser, mapping, target, deletion policy, and limits. Authentication uses a named credential created for this connector, not an editor access token. The administrator sees the secret only once; store it in the sending system's secret manager.

CSV example

curl --fail-with-body 'https://showcase.example/api/integrations/visitor-directory/ingest' \
  -H 'Authorization: Bearer <named-connector-credential>' \
  -H 'Content-Type: text/csv' \
  --data-binary @people.csv

person_id,display_name,email,tier
P-001,Ada Example,ada@example.invalid,gold
P-002,Lin Example,lin@example.invalid,silver

JSON example

curl --fail-with-body 'https://showcase.example/api/integrations/catalog/ingest' \
  -H 'Authorization: Bearer <named-connector-credential>' \
  -H 'Content-Type: application/json' \
  --data-binary @catalog.json

{
  "items": [
    { "id": "ITEM-1", "title": "Example item", "description": "Fixture data" }
  ]
}

A successful response includes run ID, status, counts, and any record-level errors. A second payload with the same external ID updates the mapped record rather than creating a duplicate.

Errors

Status Meaning Action
400 Payload, parser, mapping, or target is invalid Read response and run history; correct with dry-run
401 Connector credential missing, invalid, or revoked Create a replacement credential, update the sender, then revoke the old one
404 Connector does not exist or is unavailable Check the slug and connector state; involve support if an engineering kill switch is active
413 Request exceeds body-size cap Split or reduce the payload
429 Connector rate limit exceeded Wait for the window; do not retry in a tight loop
500 Unexpected server failure Preserve run ID, response, timestamp, and service log

Do not automatically retry ambiguous 400/500 responses without checking run history: valid records may already have been applied in a partial run. Use external IDs to make deliberate retries idempotent.