Contacts and companies

Scopes: contacts:read to read, contacts:write to change.

Method	Path	Description
GET	/v1/contacts	List contacts. Filters: q, company_id, tag, field.<key>
POST	/v1/contacts	Create a contact
GET	/v1/contacts/{id}	Get a contact
PATCH	/v1/contacts/{id}	Update a contact
DELETE	/v1/contacts/{id}	Delete a contact
GET	/v1/contacts/{id}/tickets	The contact’s tickets
GET, POST	/v1/companies	List or create companies. Filters: q, tag, field.<key>
GET, PATCH, DELETE	/v1/companies/{id}	Get, update or delete a company

Objects

type Contact = {
  id: string;
  email: string | null;
  name: string;
  phone: string;
  avatar_url: string;
  company: { id: string; name: string; domain: string } | null;
  external_id: string | null;
  notes: string;
  custom: Record<string, unknown>;
  tags: { id: string; name: string; color: LabelColor; group_id: string | null }[];
  fields: Record<string, FieldValue>;
  blocked: boolean;
  ticket_count: number;
  created_at: string;
  updated_at: string;
};

type Company = {
  id: string;
  name: string;
  domain: string;
  notes: string;
  custom: Record<string, unknown>;
  tags: { id: string; name: string; color: LabelColor; group_id: string | null }[];
  fields: Record<string, FieldValue>;
  contact_count: number;
  created_at: string;
  updated_at: string;
};

A contact’s email is unique within the workspace, and so is its external_id, your own id for the person (set by verified widget sessions). A company’s domain is unique within the workspace.

Writes to contacts and companies take tags (replaces), add_tags, remove_tags and fields (merged, null clears), with the same rules as tickets. See Labels and custom fields.

Examples

# Search
curl "https://api.opendesk.sh/v1/contacts?q=ana" -H "Authorization: Bearer od_live_..."

# Create
curl https://api.opendesk.sh/v1/contacts \
  -H "Authorization: Bearer od_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "name": "Ana Silva", "custom": { "plan": "pro" } }'

# Block
curl -X PATCH https://api.opendesk.sh/v1/contacts/0192f0c4-... \
  -H "Authorization: Bearer od_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "blocked": true }'

Events

contact.created, contact.updated, contact.deleted, and the same for company.*.