Use the Delete Contacts API to delete specific contacts, remove contacts from audiences, delete contacts in bulk using a file, or dynamically select contacts using filtering criteria.

Delete a Single Identified Contact

When to use: Use this when you want to delete one identified contact.

What changes: Set contact_type to identified, delete_type to soft, and provide the contact's identity.

Best for: Deleting an individual contact when you know their primary identity.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "soft",
    "contacts": [
      {
        "identity": "[email protected]"
      }
    ]
  }
}

Good to know: identity must match the primary identity configured for your account.

Delete a Contact Using contact_id

When to use: Use this when you know the Netcore contact_id of the contact.

What changes: Provide contact_id instead of the contact's identity.

Best for: Applications that store the Netcore contact ID.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "soft",
    "contacts": [
      {
        "contact_id": 101
      }
    ]
  }
}

Delete Multiple Contacts

When to use: Use this when you want to delete multiple known contacts in one request.

What changes: Add multiple contact objects inside contacts.

Best for: Bulk deletion when you already have the contact identifiers.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "soft",
    "contacts": [
      {
        "identity": "[email protected]"
      },
      {
        "identity": "[email protected]"
      },
      {
        "identity": "[email protected]"
      }
    ]
  }
}

Delete an Anonymous Contact

When to use: Use this when you want to delete an anonymous contact.

What changes: Set contact_type to anonymous and provide a supported identifier.

Best for: Removing anonymous contacts when their Netcore contact_id or other supported identifier is available.

Sample request

{
  "data": {
    "contact_type": "anonymous",
    "delete_type": "soft",
    "contacts": [
      {
        "contact_id": 101
      }
    ]
  }
}

Remove a Contact from an Audience

When to use: Use this when you want to remove a contact from an audience without deleting the contact from Netcore.

What changes: Set delete_type to audience and specify the audience in audience_details.

Best for: Removing a customer from a campaign/list while keeping their contact record.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "audience",
    "contacts": [
      {
        "identity": "[email protected]"
      }
    ],
    "audience_details": [
      {
        "audience_id": [101],
        "audience_type": "list"
      }
    ]
  }
}

Good to know: delete_type: "audience" removes the contact from the specified audience(s); it does not perform a system-level contact deletion.

Remove Multiple Contacts from the Same Audience

When to use: Use this when multiple contacts need to be removed from the same audience.

What changes: Specify the contacts in contacts and the audience at the data level.

Best for: Removing a group of contacts from a list.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "audience",
    "contacts": [
      {
        "identity": "[email protected]"
      },
      {
        "identity": "[email protected]"
      }
    ],
    "audience_details": [
      {
        "audience_id": [101],
        "audience_type": "list"
      }
    ]
  }
}

Remove Different Contacts from Different Audiences

When to use: Use this when each contact needs to be removed from a different audience.

What changes: Add audience_details inside each contact object.

Best for: Applying different audience-level deletions to different contacts in the same request.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "audience",
    "contacts": [
      {
        "identity": "[email protected]",
        "audience_details": [
          {
            "audience_id": [101],
            "audience_type": "list"
          }
        ]
      },
      {
        "identity": "[email protected]",
        "audience_details": [
          {
            "audience_id": [102],
            "audience_type": "list"
          }
        ]
      }
    ]
  }
}

Delete Contacts Using a File

When to use: Use this when you need to delete a large number of contacts and have their identifiers in a file.

What changes: Provide file_url instead of contacts.

Best for: Large-scale contact deletion.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "soft",
    "file_url": "https://contactdelete.s3.us-east-1.amazonaws.com/contactdelete.csv"
  }
}

Good to know:

• Do not provide contacts and file_url together.
• Bulk deletion using file_url is not applicable to anonymous contacts.
• The current specification does not define the supported file size, maximum number of records, or complete file format requirements.

Delete Contacts Using Filtering Criteria

When to use: Use this when you want Netcore to dynamically select contacts based on conditions instead of specifying individual contacts.

What changes: Provide filtering_criteria and define the conditions that contacts must match.

Best for: Deleting contacts based on attributes, contact information, or audience-related criteria.

Sample request

{
  "filtering_criteria_operator": "and",
  "filtering_criteria": [
    {
      "condition_operator": "and",
      "condition_details": [
        {
          "field": "contact_type",
          "field_category": "config",
          "operation": "equals",
          "value": [
            "identified"
          ]
        },
        {
          "field": "identity",
          "field_category": "config",
          "operation": "ends_with",
          "value": [
            "@example.com"
          ]
        }
      ]
    }
  ]
}

Good to know: Filtering-based deletion can select multiple contacts dynamically. Carefully review your conditions before submitting the request.

Remove a Contact from Multiple Audiences

When to use: Use this when a contact needs to be removed from multiple audiences in the same request.

What changes: Provide multiple audience IDs in audience_id.

Best for: Cleaning up audience memberships without deleting the contact itself.

Sample request

{
  "data": {
    "contact_type": "identified",
    "delete_type": "audience",
    "contacts": [
      {
        "identity": "[email protected]"
      }
    ],
    "audience_details": [
      {
        "audience_id": [101, 102, 103],
        "audience_type": "list"
      }
    ]
  }
}

Good to know: Use either audience_id or audience_name to identify the audience. Providing both in the same audience_details object results in a validation error.

Important Things to Know

• 200 does not mean deletion is complete. It means the asynchronous request was accepted.
• Do not use contacts and file_url together. Use one method to specify the contacts to delete.
• When data is present, filtering criteria is ignored. For clarity, use either data or filtering_criteria in a request.
• delete_type is required when data is used and supports soft and audience.
• soft and audience have different purposes: soft performs system-level contact deletion, while audience removes contacts from specified audiences.
• Use either audience_id or audience_name, not both in the same audience_details` object.
• Audience scope matters: data.audience_details applies to all contacts, while contact-level audience_details applies only to that contact.
• Bulk deletion using file_url is not supported for anonymous contacts.
• Filtering-based deletion can affect multiple contacts, so review your filtering conditions carefully before submitting the request.