Contact details are the email addresses, phone numbers, and postal addresses associated with a customer. These details are used across the platform for communication, verification, delivery, and historical searches.

Each contact detail includes the following fields:

Value — The actual contact info. this is usually a string, such as:
- an email address
- an E.164-formatted phone, mobile, or fax number
- a URL
- or an object with structured fields (for postal addresses)
Usage — Describes what the detail is used for (e.g. work email, delivery address, temporary phone number).
Status — Indicates the current state of the contact detail (e.g. unverified, verified, undeliverable, or deleted).
Primary — A optional boolean flag (true or false) showing whether this is the preferred contact detail of its type. For example, a customer may have multiple phone numbers, but one marked as primary.

Understanding how to set and interpret these values helps ensure we’re communicating with customers using the right method, in the right context, at the right time.

This guide explains the available options for both fields, and how they should be used across API calls, internal tooling, and integrations.

🧭 Usage Options

The usage field describes what the contact detail is intended for — giving context to help systems and humans decide when and how to use it. A customer might have multiple contact details with different purposes, and usage helps you pick the right one for the task.

Available usage values:

Value	Description
permanent	A long-term, personal contact detail for the customer. This is often their main phone number, personal email, or home address. Use this when the contact detail is stable and expected to remain valid indefinitely.
work	A contact method related to the customer's employment or business. This could be a work email address or their office phone number. Use this for professional or B2B communications.
supply_address	An address used for billing, invoicing, or as the registered source of goods/services. This is commonly used in contracts or for legal paperwork.
delivery_address	An address where items or documents should be sent. Think packages, post, or couriered documents. If you need to physically deliver something to the customer, use this.
temporary	A short-term or fallback contact detail. This might be a burner phone while the customer is travelling, a temporary address during a move, or a short-lived email. These details are typically valid for a limited time.

📝 A single customer may have multiple contact details with the same usage — e.g. two delivery_address entries — in which case the primary flag helps indicate which to prefer.

🟡 Status Options

The status field describes the current condition of the contact detail — is it valid and working, or has it been flagged due to delivery issues?

This status helps systems decide whether to use, skip, or flag the contact detail during communication.

Available status values:

Value	Description
unverified	The default status for any new contact detail. It hasn't yet been tested or confirmed. For example, an email that hasn't been sent to yet, or a phone number that hasn't received a message.
verified	The contact detail has been confirmed as working. This might mean an email was successfully delivered, a phone number responded, or a letter reached its destination. Use this to mark a trusted, active contact method.
undeliverable	This contact method failed when used. For example, the email bounced, the letter was returned to sender, or the phone line is disconnected. Systems should generally avoid using contact details with this status.
deleted	The contact detail is no longer intended for use — either it was replaced, outdated, or removed by the customer. However, it is retained for historical and search purposes. For example, you can still search for a customer by a previously used email address.

📌 Even when a contact detail is marked as deleted, it’s not removed from the system — it just shouldn’t be used for current communication.

🧾 Example Contact Detail Setup

Here’s how a customer might have multiple contact details configured:

Value	Usage	Status	Primary
jane.doe@example.com	work	verified	true
jane.alt@example.com	work	unverified	false
+447700900123	permanent	verified	true
+447700900999	temporary	unverified	false
`{"line1": "123 Fake St", "city": "Sometown", "postal_code": "FA1 4KE", "country": "GB"}`	delivery_address	verified	true
`{"line1": "123a Fake St", "city": "Sometown", "postal_code": "FA1 4KE", "country": "GB"}`	permanent	deleted	false

This setup shows how a customer might have several methods of contact, with different intended purposes (usage), different reliability levels (status), and one primary detail for each type.