Contacts

Summary

The Contact Schema Type defines the structure, behavior, and access patterns for individual or organizational contact records. As a core domain object, the Contact schema provides a unified and consistent representation for contact data across all SDK components and integrations.

This document provides a comprehensive overview of the Contact schema type, its structure, and its usage via the SchemaTypeClient.

What is a Contact?

A Contact represents an individual person, company, or organization known to the system. It serves as a centralized “address book” entity, standardizing how the system models people and organizations.

The primary purpose of the Contact schema is to identify and resolve entities interacting with the system. For example, when an incoming call is received, the system can use the caller’s phone number to look up a matching contact and retrieve their details.

Typical use cases include:

Managing customer, partner, or account profiles.
Identifying an inbound caller and displaying their information to an agent.
Associating contacts with support tickets or other work items.

Structure of a Contact

A Contact object is composed of several fields that define its identity, attributes, and metadata.

Identifier: contact

Field summary

Field	Type	Description	Required
_id	string	Internal unique identifier for the contact (MongoDB ID).	Yes
accountId	string	The ID of the account this contact belongs to.	No
addresses	Array<{ address?: string; city?: string; country?: string; id: string; state?: string; timezone: string; type: string; zip?: string; }>	An array of structured address objects associated with the contact.	No
blockedAt	number	Unix timestamp (ms) when the contact was blocked.	No
blockedBy	string	Identifier of the user who blocked the contact.	No
connections	Array<{ country?: string; countryCode?: string; id?: string; isPrimary?: boolean; isVerified?: boolean; name: string; phoneNumber?: string; type: string; value: string; }>	An array of connection objects (e.g., phone numbers, email addresses, social media handles). Each connection has a type and a value.	No
contactId	string	Public unique identifier for the contact (e.g., `ct_123`).	Yes
contactSegments	string[]	An array of contact segment IDs this contact belongs to.	No
createdAt	number	Unix timestamp (ms) when the contact was created.	Yes
createdBy	string	Identifier of the user who created the contact.	Yes
deletedAt	number	Unix timestamp (ms) when the contact was deleted.	No
email	string	Primary email address. (Deprecated: Use `connections` for email.)	No
expansions	object	Related objects that can be expanded, such as `accountId` to the full Account object or `contactSegments` to ContactSegment objects.	No
firstName	string	The given name of the contact.	Yes
id	string	Alias for `contactId`.	Yes
jobTitle	string	The job title of the contact.	No
lastName	string	The family name of the contact.	Yes
mobile	string	Mobile phone number. (Deprecated: Use `connections` for phone numbers.)	No
modifiedAt	number	Unix timestamp (ms) when the contact was last modified.	Yes
modifiedBy	string	Identifier of the user who last modified the contact.	Yes
name	string	Full display name for the contact.	Yes
objectType	string	The type of object; will always be `"contact"`.	Yes
phone	string	Primary phone number. (Deprecated: Use `connections` for phone numbers.)	No
profileColor	string	A hexadecimal color code for the contact’s profile.	No
state	string	The state/province of the contact’s address.	No
tenantId	string	The ID of the tenant the contact belongs to.	Yes
timezone	string	The timezone of the contact.	No
unknown	boolean	Indicates if the contact is an “unknown” contact.	No
userId	string	The ID of the user associated with this contact.	No
zip	string	The zip/postal code of the contact’s address.	No

Example object

import { Contact } from '@ncx/ncx-core-sdk/types/contact'; // Correct import path

const exampleContact: Contact = {
  _id: "60c72b2f9b1e8e0007c8e8e8",
  contactId: "ct_12345",
  id: "ct_12345",
  objectType: "contact",
  tenantId: "t_abcde",
  createdAt: 1678886400000, // March 15, 2023 12:00:00 PM UTC
  createdBy: "user_johndoe",
  modifiedAt: 1678972800000, // March 16, 2023 12:00:00 PM UTC
  modifiedBy: "user_janedoe",
  firstName: "Jordan",
  lastName: "Kline",
  name: "Jordan Kline",
  connections: [
    { type: "email", value: "[email protected]", isPrimary: true },
    { type: "phone", value: "+14805551212", isPrimary: true, countryCode: "US" }
  ],
  addresses: [
    {
      id: "addr_1",
      type: "billing",
      address: "123 Main St",
      city: "Scottsdale",
      state: "AZ",
      zip: "85251",
      country: "US",
      timezone: "America/Phoenix"
    }
  ],
  profileColor: "#FF5733",
  jobTitle: "Software Engineer",
  accountId: "acc_67890",
  unknown: false,
  // Other fields can be included as needed
};

CRUD operations

All interactions with Contact objects are handled through the standard methods of the BaseSchemaTypeClient, accessed via sdk.getSchemaTypeClient().

Create a contact

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Contact } from '@ncx/ncx-core-sdk/types/contact';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const newContactData = {
  firstName: "Alex",
  lastName: "Ray",
  name: "Alex Ray",
  connections: [
    { type: "email", value: "[email protected]", isPrimary: true }
  ],
  tenantId: "t_abcde", // Required
  createdAt: Date.now(),
  createdBy: "user_current",
  objectType: "contact" // Required
};

const newContact: Contact = await schemaTypeClient.create("contact", {
  data: newContactData
});

console.log("Created Contact:", newContact);

Retrieve a contact

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Contact } from '@ncx/ncx-core-sdk/types/contact';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const contactIdToRetrieve = "ct_12345"; // Example contact ID
const retrievedContact: Contact = await schemaTypeClient.retrieve("contact", {
  id: contactIdToRetrieve,
});

console.log("Retrieved Contact:", retrievedContact);

Search contacts

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Contact, FetchContactsResponseBody } from '@ncx/ncx-core-sdk/types/contact';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const searchResults: FetchContactsResponseBody = await schemaTypeClient.search("contact", {
  q: "Jordan Kline", // Search query string
  rows: 10,          // Number of results to return
  start: 0,          // Starting offset for pagination
});

console.log("Search Results (list):", searchResults.list);
console.log("Total Matches:", searchResults.total);

Update a contact

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Contact } from '@ncx/ncx-core-sdk/types/contact';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const contactIdToUpdate = "ct_12345"; // Example contact ID
const updatedContactData = {
  connections: [
    { type: "email", value: "[email protected]", isPrimary: true },
    { type: "phone", value: "+14805551212", isPrimary: true, countryCode: "US" }
  ],
  jobTitle: "Senior Software Engineer",
  modifiedAt: Date.now(), // Update timestamp
  modifiedBy: "user_current",
  name: "Jordan A. Kline"
};

const updatedContact: Contact = await schemaTypeClient.update("contact", {
  id: contactIdToUpdate,
  data: updatedContactData
});

console.log("Updated Contact:", updatedContact);

Delete a contact

import { Nextiva } from '@nextiva/ncx-web-sdk';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const contactIdToDelete = "ct_12345"; // Example contact ID
await schemaTypeClient.delete("contact", {
  id: contactIdToDelete,
});

console.log("Contact deleted successfully.");

Relationships

Relationship	Type	Description
workitems	WorkitemRef[]	A list of work items (e.g., tickets, tasks) associated with this contact.
organization	ContactRef	For a person contact, this provides a link to their organization.
owner	UserRef	The user who created or manages this contact.

Validation rules

displayName must not be empty.
Type must be either "person" or "organization".
At least one entry in connections (like an email or phone number) is required for a person.
Email addresses must pass standard format validation.
Tags are limited to 32 entries per contact.

Permissions

The Contact schema type uses the following permission scopes:

Scope	Description
contacts:read	Allows viewing contact details.
contacts:write	Allows creating and modifying contact data.
contacts:delete	Allows archiving or removing contact records.
contacts:admin	Grants permissions for administrative tasks like merging duplicates or bulk operations.