Contacts List API
Preserve contact identity, keep field provenance, and treat merging and exporting as deliberate decisions.
Start with the record.
Keep what matters.
A contacts list API connects records about people, but a contact record is not the person themselves. Names change, addresses can be shared, and the same person may appear in several accounts with different context. A trustworthy integration preserves that context instead of trying to force every record into one supposedly perfect entry.
A simple field model
These illustrative fields are a starting point for your own design. They are not a live ListAPI.com API contract and should not be substituted for a provider’s documented request format.
| Illustrative field | What it should tell you |
|---|---|
contact_id | A durable reference within the source account. |
display_name | A presentation field, never a unique key. |
email_addresses | A collection with labels and source information. |
updated_at | A change marker with a defined meaning. |
A useful starting point
Use the provider's contact identifier together with the source account as the stable reference for an imported record. If your application also has an internal person identity, store the mapping explicitly. Do not assume that an email address, phone number, or display name is a permanent global identifier. Each can change, be shared, or be represented differently across sources.
This distinction helps when two source records appear to describe the same person. You can link them to a proposed internal identity without deleting either source record. It also supports reversibility: a mistaken match can be undone without reconstructing the original data from memory. Keep the evidence for the match rather than treating deduplication as an invisible cleanup step.
Before you connect the list
Identify the source of truth and the intended audience. Start with a small read-only view so you can compare the result with the source. Record the retrieval scope and keep incomplete imports visible instead of treating a partial result as the whole collection.
Choose how to handle a renamed record, a repeated request, a removed item, and lost access. Make field ownership explicit before adding two-way edits. The full guide explores the decisions specific to this list type and links to an official reference.