List Contacts

Contacts are the people your workspace interacts with. A contact can be linked to platform identities (channels) and carry custom field values. Contacts can be scoped to a profile.

The contact object

{
  "id": "con_7hN...",
  "profile_id": "pro_9aB...",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "company": "Acme",
  "tags": ["vip"],
  "notes": "Met at conference",
  "subscribed": true,
  "blocked": false,
  "created_at": "2026-07-12T10:00:00.000Z",
  "updated_at": "2026-07-12T10:00:00.000Z"
}

GET/v1/contacts

Filter with ?profile_id=, ?search= (name or email), or ?tag=.

{
  "contacts": [
    {
      "id": "con_7hN...",
      "profile_id": "pro_9aB...",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "company": "Acme",
      "tags": [
        "vip"
      ],
      "notes": "Met at conference",
      "subscribed": true,
      "blocked": false,
      "created_at": "2026-07-12T10:00:00.000Z",
      "updated_at": "2026-07-12T10:00:00.000Z"
    }
  ]
}

Create Contact

POST/v1/contacts

Body parameters

Field	Type	Notes
`name`	string	Required
`profile_id`	string	Optional
`email, company, notes`	string	Optional
`tags`	array	Optional
`platform + platform_identifier`	string	Optionally attach a channel

POST /v1/contacts

curl -X POST https://api.socialit.com/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "email": "jane@example.com", "tags": ["vip"] }'

{
  "contact": {
    "id": "con_7hN...",
    "profile_id": "pro_9aB...",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "company": "Acme",
    "tags": [
      "vip"
    ],
    "notes": "Met at conference",
    "subscribed": true,
    "blocked": false,
    "created_at": "2026-07-12T10:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}

Get Contact

GET/v1/contacts/:id

Includes custom field values.

{
  "contact": {
    "id": "con_7hN...",
    "profile_id": "pro_9aB...",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "company": "Acme",
    "tags": [
      "vip"
    ],
    "notes": "Met at conference",
    "subscribed": true,
    "blocked": false,
    "created_at": "2026-07-12T10:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}

Update Contact

PATCH/v1/contacts/:id

PATCH /v1/contacts/:id

curl -X PATCH https://api.socialit.com/v1/contacts/con_7hN... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "company": "Acme Inc", "tags": ["vip", "partner"] }'

{
  "contact": {
    "id": "con_7hN...",
    "profile_id": "pro_9aB...",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "company": "Acme",
    "tags": [
      "vip"
    ],
    "notes": "Met at conference",
    "subscribed": true,
    "blocked": false,
    "created_at": "2026-07-12T10:00:00.000Z",
    "updated_at": "2026-07-12T10:00:00.000Z"
  }
}

Delete Contact

DELETE/v1/contacts/:id

{ "ok": true }

List Channels

GET/v1/contacts/:id/channels

{ "channels": [ { "id": "ch_...", "platform": "instagram", "external_id": "178...", "display": "@jane" } ] }

Set Custom Field

PUT/v1/contacts/:id/fields/:slug

Set a custom field value by its slug.

PUT /v1/contacts/:id/fields/:slug

curl -X PUT https://api.socialit.com/v1/contacts/con_7hN.../fields/plan \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "value": "pro" }'

{ "ok": true }