> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.

# Erase Contacts by Identifier

> Deletes or anonymizes the contacts in the API key's company that an external id, phone number or e-mail address names. Each contact is deleted as `DELETE /contacts/{id}` deletes it, including its call recordings and the calls held by the voice provider. When more than one contact matches, the request is refused with 409 unless `allowMultiple` is true. Nothing matching is a 200 with an empty `contactIds`, so a retried request is safe.

Deletes or anonymizes the contacts that one of **your** identifiers names: your own id for the
person, their phone number, or their e-mail address. Use it to act on an erasure request when
you do not hold our contact id. **This action cannot be undone.**

## Request

```json theme={null}
{
  "identifierType": "externalId",
  "value": "CAND-12345",
  "mode": "delete"
}
```

| Field | Required | Meaning |
| - | - | - |
| `identifierType` | yes | `externalId`, `phoneNumber` or `email` |
| `value` | yes | The identifier itself, at most 512 characters |
| `mode` | no | `delete` (the default) or `anonymize` |
| `allowMultiple` | no | `true` to erase every contact the identifier matches. Off by default, see below |

The API key needs the `delete:contacts` scope, the same as [Delete Contact](https://docs.instaview.sk/api-reference/contacts/delete-contact.md).

## How an identifier matches

* **`externalId`** matches the `externalId` you stored in the contact's `metadata`, and the id
  a connected ATS or CRM synced the contact under.
* **`phoneNumber`** matches ignoring spaces, dashes and brackets, so `+421 915-123 456` finds a
  contact stored as `+421915123456`. The country prefix is not guessed: `0915123456` does not.
* **`email`** matches case-insensitively.

Only contacts of your API key's company are searched, and only live ones. A contact you already
deleted is on its way out with its recordings, so it is not matched again.

## When more than one contact matches

Two records that share an e-mail address or an external id are not necessarily one person: a
shared family mailbox, an id reused across two systems. So by default **the request is refused
with `409 Conflict` and nothing is erased.** The error message lists the matching contact ids.
Check them, then either send the same request with `"allowMultiple": true` to erase all of them,
or delete the right one with [Delete Contact](https://docs.instaview.sk/api-reference/contacts/delete-contact.md).

One request erases at most 50 contacts. An identifier that matches more is refused with
`422 Unprocessable Entity`, even with `allowMultiple`.

## Delete or anonymize

> [tab] delete
>
> The contact is deleted exactly as [Delete Contact](https://docs.instaview.sk/api-reference/contacts/delete-contact.md)
> deletes it, with every conversation it had: transcripts, analyses, documents, job
> assignments, field values. Afterwards `GET /contacts/{id}` answers 404.

> [tab] anonymize
>
> Everything is removed the same way, and a record is left under the **same id** with the
> contact's status, source, creation date and retention date, and no personal data: the name
> is `Anonymized`, and the surname, e-mail, phone number, `metadata` and `fields` are empty.
> Use it when your own system keeps the id and needs it to keep resolving, or when reports
> should go on counting the contact.
>
> The conversations are not kept. A transcript, a recording or an analysis of a call is
> personal data, so anonymizing a contact cannot leave them behind.

In both modes the contact's ATS and CRM links are removed, so the next sync cannot write the
person's data back.

## Recordings and calls at the voice provider

Call recordings and the call records held by our voice provider are queued for deletion in the
same transaction that deletes the contact, and deleted right after it. A deletion the provider
does not confirm is retried automatically for several days. Nothing you need to do, and nothing
lost if a provider is briefly down.

## Response

```json theme={null}
{
  "mode": "delete",
  "identifierType": "externalId",
  "contactIds": ["550e8400-e29b-41d4-a716-446655440000"]
}
```

**Nothing matching is not an error**: the answer is a `200` with an empty `contactIds`. That
makes a retried request safe, since the second attempt finds nothing left to erase.

## Error Scenarios

* **400 Bad Request**: an unknown `identifierType` or `mode`, or an empty `value`
* **409 Conflict**: more than one contact matches and `allowMultiple` is not `true`. Nothing was erased
* **422 Unprocessable Entity**: more than 50 contacts match. Nothing was erased

> [!NOTE]
>
> As with [Delete Contact](https://docs.instaview.sk/api-reference/contacts/delete-contact.md), a snapshot of the deleted
> contact record is kept in an internal archive for the configured retention period (30 days by
> default) and then removed. It is not
> reachable through the API.

## Related Resources

> [card] [Delete Contact](https://docs.instaview.sk/api-reference/contacts/delete-contact.md)
>
> Delete one contact by its id

> [card] [Contacts Resource Guide](https://docs.instaview.sk/guides/resources/contacts.md)
>
> Learn about managing contacts


## OpenAPI

````yaml POST /contacts/erasures
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /contacts/erasures:
    post:
      tags:
        - Contacts
      summary: Erase contacts by identifier
      description: >-
        Deletes or anonymizes the contacts in the API key's company that an
        external id, phone number or e-mail address names. Each contact is
        deleted as `DELETE /contacts/{id}` deletes it, including its call
        recordings and the calls held by the voice provider. When more than one
        contact matches, the request is refused with 409 unless `allowMultiple`
        is true. Nothing matching is a 200 with an empty `contactIds`, so a
        retried request is safe.
      operationId: PublicContactErasureController_eraseContacts_v1
      parameters:
        - name: companyId
          required: false
          in: query
          description: >-
            Required for ATS API keys to specify which company to access.
            Ignored for standard company API keys.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicEraseContactDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContactErasureResponseDto'
      security:
        - bearer: []
components:
  schemas:
    PublicEraseContactDto:
      type: object
      properties:
        identifierType:
          type: string
          enum:
            - externalId
            - phoneNumber
            - email
          example: externalId
          description: >-
            Which identifier `value` is. `externalId` matches the contact's
            `metadata.externalId` and the id an ATS or CRM integration synced
            the contact under; `phoneNumber` matches ignoring spaces, dashes and
            brackets; `email` matches case-insensitively.
        value:
          type: string
          maxLength: 512
          example: CAND-12345
          description: The identifier itself.
        mode:
          type: string
          enum:
            - delete
            - anonymize
          default: delete
          example: delete
          description: >-
            `delete` removes the contact as `DELETE /contacts/{id}` does.
            `anonymize` removes everything the same way but leaves a record with
            the same id, status, source and dates and no personal data, so the
            id keeps resolving.
        allowMultiple:
          type: boolean
          default: false
          example: false
          description: >-
            Erase every contact the identifier matches. Off by default: when
            more than one contact matches, the request is refused with 409 and
            erases nothing, because two records sharing an e-mail address are
            not necessarily one person. At most 50 contacts are erased per
            request.
      required:
        - identifierType
        - value
    PublicContactErasureResponseDto:
      type: object
      properties:
        mode:
          type: string
          enum:
            - delete
            - anonymize
          example: delete
          description: What was done to the matched contacts.
        identifierType:
          type: string
          enum:
            - externalId
            - phoneNumber
            - email
          example: externalId
          description: The identifier type the request matched on.
        contactIds:
          type: array
          items:
            type: string
            format: uuid
          example:
            - 550e8400-e29b-41d4-a716-446655440000
          description: >-
            Ids of the contacts erased. Empty when nothing matched. With
            `anonymize` these ids still resolve, to records with no personal
            data.
      required:
        - mode
        - identifierType
        - contactIds
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.