Contacts API

Contacts API

The Contacts API manages your customer and prospect contact records. Contacts are distinct from leads — a contact represents a verified individual, while a lead represents a sales opportunity. Contacts can be associated with multiple deals and conversations.

List Contacts

curl -X GET "https://api.skode.ai/v1/contacts?page=1&per_page=50&sort=name" \
  -H "Authorization: Bearer sk_live_your_api_key"

Filter parameters: email, company, tag, created_after, created_before, updated_after. Supports full-text search with the q parameter.

Create a Contact

const response = await fetch('https://api.skode.ai/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Sarah Johnson',
    email: 'sarah@techcorp.com',
    phone: '+1-555-0456',
    company: 'TechCorp',
    title: 'VP of Engineering',
    address: {
      street: '123 Innovation Drive',
      city: 'San Francisco',
      state: 'CA',
      zip: '94105',
      country: 'US'
    },
    tags: ['enterprise', 'decision-maker'],
    custom_fields: {
      linkedin: 'https://linkedin.com/in/sarahjohnson',
      preferred_contact: 'email'
    }
  })
});

Required fields: name and at least one of email or phone. Skode deduplicates contacts by email address — creating a contact with an existing email returns a 409 Conflict with the existing contact ID.

Get a Contact

curl -X GET "https://api.skode.ai/v1/contacts/contact_xyz789" \
  -H "Authorization: Bearer sk_live_your_api_key"

The response includes the contact record, associated deals, recent activities, conversation history links, and tags.

Update a Contact

curl -X PATCH "https://api.skode.ai/v1/contacts/contact_xyz789" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "CTO", "tags": ["enterprise", "decision-maker", "vip"]}'

Merge Contacts

curl -X POST "https://api.skode.ai/v1/contacts/merge" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"primary_id": "contact_xyz789", "duplicate_ids": ["contact_abc123"]}'

Merging combines all activities, deals, conversations, and tags into the primary contact. Duplicate contacts are soft-deleted and redirect to the primary record.

Delete a Contact

curl -X DELETE "https://api.skode.ai/v1/contacts/contact_xyz789" \
  -H "Authorization: Bearer sk_live_your_api_key"

Returns 204 No Content. Associated deals and conversations are not deleted but will show the contact as removed. Recoverable from trash for 30 days.