Integrations & Data Management

CSV & XLSX imports

AwareCX includes a guided Import Wizard for bulk-loading contacts and accounts from spreadsheet files.

Supported file formats

• CSV (.csv)
• Excel (.xlsx)

Import Wizard steps

1. Upload

Drag and drop your file or select it from your device. AwareCX reads the headers and automatically previews the first rows.

2. Map columns

Each column in your file is matched to an AwareCX field. The system auto-detects common column names such as Email, Full Name, and Phone. You can also map columns to custom fields or skip them entirely.

3. Validation summary

AwareCX validates every row before import. You will see counts for valid rows, rows with warnings, and rows with errors. Examples:

• Warning: missing optional fields
• Error: missing or invalid email address

Only valid rows proceed to import.

4. Import results

After the import completes, AwareCX displays a summary showing contacts created, contacts updated, contacts skipped, and accounts created.

Standard import fields

• Email (required). Contact's email address. Primary identifier.
• Contact Name. Display name for the contact.
• Phone Number. Used for SMS survey delivery.
• Account Name. Associates the contact with an account. The account is created automatically if it does not already exist.
• Account External ID. Your CRM's account identifier, used for matching.
• Contact External ID. Your CRM's contact identifier, used for matching.

Any columns not mapped to standard fields can be mapped as custom fields. Custom fields are stored per contact and can later be used to filter survey recipients.

Ingest API (survey & assessment triggers)

The Ingest API allows you to trigger surveys and assessments automatically from external systems such as your CRM, helpdesk, or service platform. This removes the need for manual sending.

How it works

• Generate an API key in Settings → API Keys. Each key can be labeled and revoked independently.
• Send a POST request to the Ingest endpoint. Pass your key in the Authorization: Bearer header.
• AwareCX automatically creates or updates the contact, creates or updates the account, applies cooldown and suppression rules, and optionally sends the survey or assessment immediately.

Endpoint

Your organization's Ingest API base URL is shown in Settings → API Keys when you generate a key. Use that URL as INGEST_URL in the examples below.

HTTP
POST {INGEST_URL}/ingest-survey-trigger

Authentication

HTTP
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Targeting a survey or assessment

Use one of the following options:

• survey_type: "nps", "csat", or "ces". Automatically resolves to your latest active transactional survey of that type.
• survey_id: targets a specific survey by UUID.
• assessment_id: targets a specific assessment by UUID.

Minimal payload example (survey)

JSON
{
  "contact_email": "jane@hotel.com",
  "survey_type": "nps"
}

Full payload example (survey)

JSON
{
  "contact_email": "jane@hotel.com",
  "contact_name": "Jane Smith",
  "account_name": "Grand Hotel",
  "account_external_id": "acct_12345",
  "survey_type": "nps",
  "send_immediately": true,
  "external_id": "usr_67890"
}

Assessment payload example

JSON
{
  "contact_email": "jane@hotel.com",
  "contact_name": "Jane Smith",
  "account_name": "Grand Hotel",
  "assessment_id": "your-assessment-uuid",
  "send_immediately": true
}

Payload field reference

• contact_email (string, required). Recipient's email address.
• contact_name (string). Recipient's display name.
• contact_phone (string). Recipient's phone number. Required for SMS sends. Normalized to E.164 automatically.
• account_name (string). Property or account name. Created if new.
• account_external_id (string). Your system's ID for the account, used for matching.
• survey_id (string, conditional). Target a specific survey by UUID.
• survey_type (string, conditional). Auto-resolve by type: "nps", "csat", or "ces".
• assessment_id (string, conditional). Target a specific assessment by UUID.
• send_immediately (boolean). Default is true. Set to false to queue without sending.
• external_id (string). Your system's ID for the contact.
• custom_fields (object). Free-form { field_name: value } map. Fields are created on the organization automatically the first time they appear.
• custom_field_filters (array). Filter contacts by custom field values before adding.

Batch requests

The Ingest API supports batch processing for up to 200 contacts per request. Wrap contacts in a contacts array and place shared configuration at the top level.

Batch payload example

JSON
{
  "contacts": [
    {
      "contact_email": "jane@hotel.com",
      "contact_name": "Jane Smith",
      "account_name": "Grand Hotel"
    },
    {
      "contact_email": "bob@resort.com",
      "contact_name": "Bob Lee",
      "account_name": "Beach Resort"
    }
  ],
  "survey_type": "nps",
  "send_immediately": true
}

Batch response example

JSON
{
  "status": "completed",
  "total": 2,
  "summary": {
    "added": 1,
    "suppressed": 1,
    "filtered": 0,
    "skipped": 0,
    "error": 0
  },
  "results": [
    {
      "contact_email": "jane@hotel.com",
      "status": "added",
      "recipient_id": "...",
      "email_sent": true
    },
    {
      "contact_email": "bob@resort.com",
      "status": "suppressed",
      "suppressed_reason": "Last surveyed 5 days ago (cooldown: 30 days)"
    }
  ]
}

Each contact is processed independently. One failure does not block the rest of the batch.

API field mappings

Many CRM and helpdesk systems use field names that don't match AwareCX's standard fields. The Field Mappings panel (Settings → Field Mappings) translates inbound field names so you don't have to rewrite your webhook payloads.

How it works

• Define one or more mappings: source field (what your system sends) → target field (a standard AwareCX field or a custom field).
• Mappings apply to every Ingest API call for your organization.
• If both the mapped name and the standard name are present, the mapping wins.

Example

Map FreshDesk's company_PID to account_external_id so the following payload works without modification:

JSON
{
  "contact_email": "jane@hotel.com",
  "company_PID": "acct_12345",
  "survey_type": "nps"
}

Custom field filters (API)

When triggering surveys or assessments through the API, you can filter contacts based on their custom field values before they are added as recipients. This is useful for routing specific customer segments to specific surveys.

Filter format

JSON
{
  "custom_field_filters": [
    {
      "field_name": "region",
      "mode": "exclude",
      "values": ["EMEA"]
    },
    {
      "field_name": "property",
      "mode": "include",
      "values": ["Grand Hotel", "Park Inn"]
    }
  ]
}

Filter modes

• include. The contact must have a matching value to proceed.
• exclude. The contact is filtered out if they have a matching value.

Filters are evaluated after the contact is created or updated, but before cooldown and recipient checks. If a contact is filtered, the response returns status: "filtered" with a reason included.

API response statuses

Every API call returns a status explaining what happened.

Status meanings

• added. The contact was added as a recipient and, if send_immediately is true, the email was sent.
• suppressed. The contact is within the cooldown window and was not added. The response includes the suppression reason.
• filtered. The contact was excluded by custom field filters.
• skipped. The contact is already a recipient for the survey or assessment.
• error. Something went wrong. The error message explains the issue.

HTTP error codes

• 400. Bad request. Missing or invalid fields.
• 401. Unauthorized. Missing or invalid API key.
• 403. Forbidden. The feature is not available on your plan.
• 404. Not found. No active survey matches the provided type or ID.
• 429. Usage limit reached for the current month. Upgrade your plan or wait for the cycle to reset.
• 500. Server error.

Outbound webhooks

Outbound webhooks let AwareCX push survey and ResolveCX events to your systems in real time. Configure endpoints in Settings → Webhooks.

Event types

• response.received — fired for every survey or assessment response.
• response.detractor — NPS 0–6, CSAT 1–2, or CES 1–3.
• response.promoter — NPS 9–10, CSAT 4–5, or CES 5–7.
• ticket.created — a ResolveCX ticket was opened (manually or auto-created).
• ticket.assigned — a ticket's assignee changed.
• ticket.note_added — an internal note was added to a ticket.
• ticket.reopened — a previously resolved ticket was reopened.
• ticket.resolved — a ticket was marked Resolved or Dismissed.
• test.ping — sent from the Webhooks UI when you click Test.

Payload

Every payload is JSON and includes the following top-level fields (schema version 2):

JSON
{
  "schema_version": 2,
  "event": "response.detractor",
  "source_type": "survey",
  "channel": "email",
  "response_id": "…",
  "score": 3,
  "scale_type": "nps",
  "feedback": "Long wait time on check-in.",
  "survey_name": "Post-Stay NPS",
  "submitted_at": "2026-06-06T18:42:11Z",
  "contact": { "id": "…", "name": "Jane Smith", "email": "jane@hotel.com", "phone": "+15551234567", "external_id": "usr_67890" },
  "account": { "id": "…", "name": "Grand Hotel", "external_id": "acct_12345" },
  "followup_answers": [{ "question": "What could we do better?", "answer": "Faster front desk." }],
  "resolve_ticket": { "id": "…", "status": "open", "priority": "high" },
  "custom_fields": [{ "name": "region", "value": "NA-East" }]
}

Signing

Each endpoint has its own signing secret, shown once at creation. Every request includes an X-AwareCX-Signature header containing the HMAC-SHA256 of the raw JSON body using that secret. Verify the signature on your side before processing the payload.

Custom field filtering per endpoint

By default, payloads include all custom fields on the contact. Each endpoint can restrict the custom_fields array to a specific subset so downstream systems only receive the data they need.

Failures and auto-disable

• Each delivery is a single HTTP POST attempt. There is no automatic retry today.
• A non-2xx response increments the endpoint's failure counter.
• After 10 consecutive failures, the endpoint is automatically disabled to protect downstream systems. Re-enable it once you've fixed the destination.
• A successful delivery resets the counter to zero.
• The last 20 deliveries (request and response) are visible per endpoint for debugging.

Backfill

After enabling or fixing an endpoint, an admin can trigger a backfill to replay historical events from a chosen time window.

Inbound delivery events

AwareCX automatically tracks email and SMS delivery events through inbound webhooks from its delivery providers. You do not need to configure these webhooks yourself.

Email delivery events tracked

• Delivered. The email was successfully delivered to the recipient's inbox.
• Bounced. The email could not be delivered. Examples include an invalid address or a full inbox.
• Complained. The recipient marked the email as spam.

SMS delivery events tracked

• Sent, Delivered, Failed, Bounced
• Opt-out (STOP and equivalents) — adds the phone to your organization's SMS opt-out list
• Opt-in — removes the phone from the opt-out list
• Inbound replies — captured for the reply-based survey flow (score and follow-up feedback)

These events are stored in AwareCX and displayed in the send detail view so you can monitor deliverability for each campaign.

API key management

API keys are managed in Settings → API Keys.

Key features

• Labeled keys. Give each key a descriptive name, such as "Zendesk Production" or "Zapier Integration". This helps track usage by system or workflow.
• Prefix visibility. After creation, only the key prefix is shown. The full key is displayed once, at creation time, so copy it immediately.
• Revocation. Keys can be revoked at any time. Revocation is immediate and permanent. Any external system using that key will stop authenticating.
• Last used tracking. Each key shows when it was last used. This helps identify unused keys for cleanup.

Data structure overview

AwareCX organizes data in a clear hierarchy.

Structure

Organization
  +-- Accounts
  |     +-- Contacts (linked by account)
  +-- Contacts (identified by email within organization)
        +-- Custom Fields
        +-- External IDs

Key relationships

• Every record belongs to an Organization. This provides complete data isolation between tenants.
• Contacts are identified by email address within an organization. This is the primary matching method for contact records.
• Accounts are optional but recommended. They enable account-level analytics and risk scoring.
• External IDs on contacts and accounts. These allow you to maintain references to your CRM or service management platform.
• Custom fields are defined per organization. They can store any text value per contact, enabling flexible segmentation.