Delete a synchronized contact through the IllyVoIP API

Use the Contacts API delete endpoint when your application deliberately removes a contact from its IllyVoIP workspace. Identify one owned contact, check the effect on connected workflows, submit the delete and confirm the result before removing your local reference.

This guide is for account-owner-authorized backend integrations. It complements the contact synchronization guide. Deleting a contact in IllyVoIP does not automatically delete its source CRM record, erase all historic activity or archive its company. The current implementation uses a deletion marker rather than a promise of permanent data erasure.

1. Decide which system owns the deletion

For a mirrored CRM contact, define whether a deletion in the source should remove the IllyVoIP copy, stop synchronization, or require manual review. Do this before adding an automated delete job. Otherwise, the next full sync may recreate a contact that a user intentionally removed.

Pause or coordinate pending updates for the same contact. Check assigned campaigns, appointments and other work before deleting. An actively used campaign contact may be rejected by the service. Do not keep retrying that conflict or work around it with another identity. Resolve the workload through the supported Portal process.

2. Resolve exactly one owned contact

Use the contact UUID returned by your account, or the complete external_source and external_id pair that your integration previously stored. A name or telephone number is not a reliable deletion selector. Two people can share a number, and a contact can have several numbers.

Prefer one selector form. If you provide multiple identifiers, they must identify the same contact; conflicting selectors are rejected. Validate the selected contact against your saved mapping and the intended source record. Do not search more broadly and delete the first match when the original identifier is missing.

3. Prepare the request without exposing account data

The shell example uses cURL and jq. Set CONTACT_UUID privately to the exact returned UUID; the API key stays on the server. Review the resolved contact in your application before enabling a destructive action.

jq -n --arg uuid "${CONTACT_UUID:?Set the exact owned contact UUID}"   '{uuid:$uuid}' > delete-contact-request.json
curl --silent --show-error --fail-with-body \
  'https://api.illyvoip.com/api/v1/contacts/delete' \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set the server-side key}" \
  -H 'Content-Type: application/json' \
  --data-binary @delete-contact-request.json > delete-contact-response.json

For an external-reference request, replace the body with the complete pair below, using the values already assigned to that contact. Do not send literal placeholders.

{
  "external_source": "YOUR_EXISTING_SOURCE",
  "external_id": "YOUR_EXISTING_CONTACT_ID"
}

4. Confirm the deletion before changing your local mapping

Inspect the HTTP response and JSON status, deleted flag and returned contact identity. Mark the local operation complete only after you confirm it concerns the intended contact. Retain the minimum audit information your integration needs: selector, operation time and outcome, not an unnecessary copy of the contact’s personal details.

Keep a local deletion or synchronization-exclusion record as appropriate. Immediately removing every mapping can make a later retry or source sync unable to distinguish a previously deleted contact from a new one. Define retention according to your own workflow and privacy obligations.

5. Reconcile an uncertain response

A timeout can occur after the deletion was accepted. Keep the original selector and operation record. Use the Contacts listing with the documented include_deleted and incremental-sync options to look for the same contact’s deletion marker; finish all relevant pages before concluding the record is absent.

A repeated delete can return not found because the contact is already marked deleted. That response alone does not prove whether your earlier request succeeded, the selector was wrong, or the record was never available to the account. Reconcile against the saved identity and current read result. Never change to a different identifier merely to obtain a successful response.

If the outcome remains uncertain, retain the mapping in a review state and escalate with sanitized evidence. Do not create a replacement contact automatically.

6. Verify the next synchronization cycle

Test with a local fixture representing a source deletion, a delayed update and a retried deletion. Confirm that updates queued before the delete cannot recreate the record unexpectedly and that a full import respects your exclusion or tombstone policy.

Separate contact deletion from company archiving. The Companies API has its own lifecycle, and removing a contact is not evidence that its company should be archived. An account-specific live acceptance test requires an intentionally disposable contact and explicit authority; this guide’s examples are not records of a production deletion.

Troubleshooting

403: verify owner-authorized API access and account verification. 409: inspect selector agreement or active-work conflicts. 404: verify ownership and the existing mapping, then investigate a possible prior deletion. Contact returns after sync: inspect the source-of-truth policy and queued updates rather than repeatedly deleting it.

Related guides and reference

• Sync CRM contacts into IllyVoIP with the Contacts API
• Organize your contacts
• Create, update and archive CRM companies through the IllyVoIP API
• Contacts API reference

Reviewed 10 October 2026 against the current IllyVoIP reference and implementation. SDK examples target version 1.4.2 where applicable. Local example checks do not certify a completed live call, routing change or third-party integration.