It Glue Contacts

Contact Hierarchy

Organizations can have multiple contacts with different roles:

Organization: Acme Corporation
├── Primary Contact: John Smith (CEO)
├── Technical Contact: Jane Doe (IT Manager)
├── Billing Contact: Bob Wilson (CFO)
└── End Users:
    ├── Alice Brown (Sales)
    ├── Charlie Davis (Marketing)
    └── Diana Evans (HR)

Field Reference

Core Fields

Communication Fields

Location Fields

Documentation Fields

PSA Integration Fields

Metadata Fields

API Patterns

List Contacts

GET /contacts
x-api-key: YOUR_API_KEY
Content-Type: application/vnd.api+json

By Organization:

GET /organizations/123/relationships/contacts

With Filters:

GET /contacts?filter[organization-id]=123&filter[contact-type-id]=456

With Pagination:

GET /contacts?page[size]=100&page[number]=1&sort=name

Get Single Contact

GET /contacts/789
x-api-key: YOUR_API_KEY

With Includes:

GET /contacts/789?include=organization,location,contact-type

Create Contact

POST /contacts
Content-Type: application/vnd.api+json
x-api-key: YOUR_API_KEY

{
  "data": {
    "type": "contacts",
    "attributes": {
      "organization-id": 123456,
      "first-name": "John",
      "last-name": "Smith",
      "title": "IT Manager",
      "contact-type-id": 12,
      "contact-emails": [
        {
          "value": "[email protected]",
          "label-name": "Work",
          "primary": true
        },
        {
          "value": "[email protected]",
          "label-name": "Personal",
          "primary": false
        }
      ],
      "contact-phones": [
        {
          "value": "555-123-4567",
          "label-name": "Office",
          "primary": true
        },
        {
          "value": "555-987-6543",
          "label-name": "Mobile",
          "primary": false
        }
      ],
      "notes": "<p>Primary technical contact. Available M-F 9-5.</p>",
      "important": true
    }
  }
}

Update Contact

PATCH /contacts/789
Content-Type: application/vnd.api+json
x-api-key: YOUR_API_KEY

{
  "data": {
    "type": "contacts",
    "attributes": {
      "title": "Senior IT Manager",
      "notes": "<p>Promoted to Senior IT Manager. Still primary contact.</p>"
    }
  }
}

Delete Contact

DELETE /contacts/789
x-api-key: YOUR_API_KEY

Search by Various Fields

By Name:

GET /contacts?filter[name]=John Smith

By Organization:

GET /contacts?filter[organization-id]=123

By PSA ID:

GET /contacts?filter[psa-id]=54321

Contact Emails

Email Structure

{
  "contact-emails": [
    {
      "value": "[email protected]",
      "label-name": "Work",
      "primary": true
    }
  ]
}

Label Names:

• Work
• Personal
• Other

Update Email

To update emails, include the full array in your PATCH request.

Contact Phones

Phone Structure

{
  "contact-phones": [
    {
      "value": "555-123-4567",
      "label-name": "Office",
      "primary": true,
      "extension": "123"
    }
  ]
}

Label Names:

• Office
• Mobile
• Home
• Fax
• Other

Common Workflows

New Contact Creation

async function createOrgContact(orgId, contactData) {
  const emails = contactData.emails.map((email, i) => ({
    value: email.address,
    'label-name': email.type || 'Work',
    primary: i === 0
  }));

  const phones = contactData.phones.map((phone, i) => ({
    value: phone.number,
    'label-name': phone.type || 'Office',
    primary: i === 0,
    extension: phone.extension
  }));

  return await createContact({
    'organization-id': orgId,
    'first-name': contactData.firstName,
    'last-name': contactData.lastName,
    title: contactData.title,
    'contact-type-id': contactData.typeId,
    'contact-emails': emails,
    'contact-phones': phones,
    notes: contactData.notes,
    important: contactData.isVip
  });
}

Find Primary Contact

async function getPrimaryContact(orgId) {
  const contacts = await fetchContacts({
    filter: {
      'organization-id': orgId,
      'contact-type-id': PRIMARY_CONTACT_TYPE
    }
  });

  // Return first primary contact or null
  return contacts[0] || null;
}

Contact Directory

async function generateContactDirectory(orgId) {
  const contacts = await fetchContacts({
    filter: { 'organization-id': orgId },
    include: 'contact-type,location'
  });

  return contacts.map(contact => ({
    name: contact.attributes.name,
    title: contact.attributes.title,
    type: contact.included?.find(i =>
      i.type === 'contact-types' &&
      i.id === contact.relationships['contact-type']?.data?.id
    )?.attributes?.name,
    emails: contact.attributes['contact-emails']?.map(e => ({
      email: e.value,
      type: e['label-name'],
      primary: e.primary
    })),
    phones: contact.attributes['contact-phones']?.map(p => ({
      number: p.value,
      type: p['label-name'],
      ext: p.extension,
      primary: p.primary
    })),
    important: contact.attributes.important
  }));
}

PSA Contact Sync

async function syncContactFromPsa(psaContact, orgId) {
  // Check if contact already exists
  const existing = await findContactByPsaId(psaContact.id);

  if (existing) {
    // Update existing contact
    return await updateContact(existing.id, {
      'first-name': psaContact.firstName,
      'last-name': psaContact.lastName,
      title: psaContact.title,
      'contact-emails': [{
        value: psaContact.email,
        'label-name': 'Work',
        primary: true
      }],
      'contact-phones': [{
        value: psaContact.phone,
        'label-name': 'Office',
        primary: true
      }]
    });
  } else {
    // Create new contact
    return await createContact({
      'organization-id': orgId,
      'psa-id': psaContact.id,
      'first-name': psaContact.firstName,
      'last-name': psaContact.lastName,
      title: psaContact.title,
      'contact-emails': [{
        value: psaContact.email,
        'label-name': 'Work',
        primary: true
      }],
      'contact-phones': [{
        value: psaContact.phone,
        'label-name': 'Office',
        primary: true
      }]
    });
  }
}

VIP Contact Alert

async function getVipContacts() {
  const contacts = await fetchAllContacts({
    filter: { important: true },
    include: 'organization'
  });

  return contacts.map(c => ({
    name: c.attributes.name,
    organization: c.included?.find(i =>
      i.type === 'organizations' &&
      i.id === c.relationships.organization?.data?.id
    )?.attributes?.name,
    title: c.attributes.title,
    email: c.attributes['contact-emails']?.find(e => e.primary)?.value,
    phone: c.attributes['contact-phones']?.find(p => p.primary)?.value
  }));
}

Error Handling

Common API Errors

Validation Errors

Error Recovery Pattern

async function safeCreateContact(data) {
  try {
    return await createContact(data);
  } catch (error) {
    if (error.status === 422) {
      const errors = error.errors || [];

      // Handle invalid email
      if (errors.some(e => e.detail?.includes('email'))) {
        console.log('Invalid email format. Removing invalid emails.');
        data['contact-emails'] = data['contact-emails']?.filter(
          e => isValidEmail(e.value)
        );
        return await createContact(data);
      }

      // Handle missing contact type
      if (errors.some(e => e.detail?.includes('contact-type'))) {
        const types = await getContactTypes();
        console.log('Valid contact types:', types);
      }
    }

    throw error;
  }
}

Best Practices

1. Use contact types - Classify all contacts for filtering and organization
2. Set primary contact - Each organization should have a primary contact
3. Include multiple methods - Add both email and phone when available
4. Mark VIPs - Use important flag for key stakeholders
5. Document notes - Include availability, preferences, special instructions
6. Link to PSA - Set psa-id for cross-platform lookups
7. Verify emails - Ensure email addresses are current
8. Associate locations - Link contacts to their physical location
9. Regular cleanup - Remove departed employees promptly
10. Maintain titles - Keep job titles current for proper escalation

Related Skills

• IT Glue Organizations - Parent organization management
• IT Glue Passwords - Contact-related credentials
• IT Glue Documents - Contact documentation
• IT Glue API Patterns - API reference