Skip to main content

​
Overview

Unify provides an official TypeScript library that makes it easy to interact with the Unify API from your code. The library handles authentication, request formatting, and response parsing so you can focus on building your integration.
The TypeScript library source code is available on GitHub.

​
Quick start

The Unify TypeScript SDK provides server-side access to the Unify API. For client-side integrations or environments where the API key is exposed, use the Intent Client instead.
You can install the Unify TypeScript library with your preferred package manager: 
npm install @unifygtm/sdk
Generate an API key in Settings → Developers and then initialize the client: 
import Unify from '@unifygtm/sdk';

const client = new Unify({
  // This is the default and can be omitted
  apiKey: process.env['UNIFY_API_KEY'],
});

const objects = await client.data.objects.list();
console.log(objects.data);
The TypeScript library reads the UNIFY_API_KEY environment variable by default. If the variable is set, you can omit the apiKey parameter when initializing the client.

​
Usage

Retrieve all objects in your Unify workspace to see what’s available:
TypeScript
import Unify from '@unifygtm/sdk';

const client = new Unify();

const objects = await client.data.objects.list();

for (const obj of objects.data) {
  console.log(`${obj.api_name} (${obj.display_name})`);
}

company (Company)
person (Person)
opportunity (Opportunity)
...
Retrieve the attributes defined on a specific object to understand its schema:
TypeScript
const attributes = await client.data.attributes.list('person');

for (const attr of attributes.data) {
  console.log(`${attr.api_name} — ${attr.type} (required: ${attr.is_required})`);
}

email — Text (required: true)
first_name — Text (required: false)
last_name — Text (required: false)
title — Text (required: false)
company — Reference (required: false)
...
Use the upsert endpoint to create a new record or update an existing one based on a unique attribute. This is the recommended approach for syncing data into Unify because it handles deduplication automatically.
TypeScript
const record = await client.data.records.upsert('person', {
  match: {
    email: 'jane@acme.com',
  },
  create_or_update: {
    email: 'jane@acme.com',
    first_name: 'Jane',
    last_name: 'Smith',
    title: 'Head of Growth',
    company: {
      match: {
        domain: 'acme.com',
      },
      create_or_update_if_empty: {
        domain: 'acme.com',
        name: 'Acme Corp',
      },
    },
  },
});

console.log(`Record ID: ${record.data.id}`);
console.log(`Created at: ${record.data.created_at}`);
console.log(`Updated at: ${record.data.updated_at}`);

Record ID: b0fdcba7-a8e5-4fa3-abb0-26ee20f5ba47
Created at: 2025-04-15T14:30:00Z
Updated at: 2025-04-15T14:30:00Z
Running this again with updated attributes (for example, a new title) will update the existing record rather than creating a duplicate, because email is used as the match key.
If you know the value of a unique attribute (like an email address), you can look up the record directly without needing the record ID:
TypeScript
const record = await client.data.records.findUnique('person', {
  match: {
    email: 'jane@acme.com',
  },
});

console.log(`Record ID: ${record.data.id}`);
console.log(`Name: ${record.data.attributes.first_name} ${record.data.attributes.last_name}`);
console.log(`Title: ${record.data.attributes.title}`);

Record ID: b0fdcba7-a8e5-4fa3-abb0-26ee20f5ba47
Name: Jane Smith
Title: Head of Growth

​
Next steps

Send records via API

Send data from external tools and systems via API.

Data API reference

Explore the full Data API reference.