Skip to main content

​
Contacts API

Manage your contact database with full CRUD operations, tagging, list membership, dynamic segments, and per-channel opt-in/opt-out preferences. Base path: /v1/contacts

​
Create Contact

POST /v1/contacts Add a new contact to your account.
​
phone
string
Phone number in E.164 format (e.g., +14155552671)
​
email
string
Contact email address
​
first_name
string
First name
​
last_name
string
Last name
​
country_code
string
ISO 3166-1 alpha-2 country code (e.g., US, TR)
​
lifecycle_stage
string
Contact lifecycle stage: lead, customer, churned, etc.
​
tags
string[]
Initial tags to assign
​
metadata
object
Custom key-value data attached to the contact
curl -X POST https://orbit-api.devotel.io/api/v1/contacts \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155552671",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "country_code": "US",
    "lifecycle_stage": "lead",
    "tags": ["beta-tester"]
  }'

{
  "data": {
    "id": "con_abc123",
    "phone": "+14155552671",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "country_code": "US",
    "lifecycle_stage": "lead",
    "tags": ["beta-tester"],
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_con_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
List Contacts

GET /v1/contacts Retrieve contacts with search, filtering, and cursor-based pagination.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
​
search
string
Full-text search across name, phone, and email
​
lifecycle_stage
string
Filter by lifecycle stage
​
country_code
string
Filter by country code
curl "https://orbit-api.devotel.io/api/v1/contacts?search=jane&lifecycle_stage=lead&limit=20" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "con_abc123",
      "phone": "+14155552671",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "lifecycle_stage": "lead",
      "tags": ["beta-tester"]
    }
  ],
  "meta": {
    "request_id": "req_list_con",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_con_abc",
      "has_more": true,
      "total": 4230
    }
  }
}

​
Get Contact

GET /v1/contacts/{id} Retrieve a single contact by ID.
​
id
string
required
Contact ID (e.g., con_abc123)

​
Update Contact

PUT /v1/contacts/{id} Update one or more fields on an existing contact.
​
id
string
required
Contact ID
​
phone
string
Updated phone number (E.164)
​
email
string
Updated email address
​
first_name
string
Updated first name
​
last_name
string
Updated last name
​
lifecycle_stage
string
Updated lifecycle stage
​
metadata
object
Updated custom metadata (merged with existing)

​
Delete Contact

DELETE /v1/contacts/{id} Permanently remove a contact and all associated data.
​
id
string
required
Contact ID
Response: 204 No Content

​
Tags

​
Add Tags

POST /v1/contacts/{id}/tags Append one or more tags to a contact. Duplicate tags are ignored.
​
id
string
required
Contact ID
​
tags
string[]
required
Array of tag strings to add
curl -X POST https://orbit-api.devotel.io/api/v1/contacts/con_abc123/tags \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["vip", "enterprise"] }'

{
  "data": {
    "id": "con_abc123",
    "tags": ["beta-tester", "vip", "enterprise"]
  },
  "meta": {
    "request_id": "req_tag_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Remove Tag

DELETE /v1/contacts/{id}/tags/{tag} Remove a single tag from a contact.
​
id
string
required
Contact ID
​
tag
string
required
Tag string to remove

​
Activity Timeline

GET /v1/contacts/{id}/activity Retrieve the communication timeline for a contact — messages sent, delivered, opened, and agent interactions.
​
id
string
required
Contact ID
{
  "data": [
    {
      "type": "message.delivered",
      "channel": "sms",
      "message_id": "msg_001",
      "timestamp": "2026-03-08T11:30:00Z"
    },
    {
      "type": "message.sent",
      "channel": "whatsapp",
      "message_id": "msg_002",
      "timestamp": "2026-03-08T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_act_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Channel Preferences

PUT /v1/contacts/{id}/preferences Update a contact’s per-channel opt-in/opt-out preferences.
​
id
string
required
Contact ID
​
preferences
object
required
Channel preference map
curl -X PUT https://orbit-api.devotel.io/api/v1/contacts/con_abc123/preferences \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "sms": true,
      "whatsapp": true,
      "email": false
    }
  }'

​
Opt-outs

GET /v1/contacts/optouts List all contacts who have opted out of one or more channels.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
​
channel
string
Filter opt-outs by channel: sms, whatsapp, email, rcs, viber, voice
​
search
string
Search by name, phone, or email

​
Lists

​
List All Lists

GET /v1/contacts/lists Retrieve all contact lists.

​
Create List

POST /v1/contacts/lists Create a new contact list.
​
name
string
required
List name
​
description
string
Optional description
curl -X POST https://orbit-api.devotel.io/api/v1/contacts/lists \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP Customers", "description": "High-value accounts" }'

{
  "data": {
    "id": "lst_abc123",
    "name": "VIP Customers",
    "description": "High-value accounts",
    "member_count": 0,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_lst_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Update List

PUT /v1/contacts/lists/{id} Update a contact list’s name or description.
​
id
string
required
List ID
​
name
string
Updated name
​
description
string
Updated description

​
Delete List

DELETE /v1/contacts/lists/{id} Delete a contact list. Members are not deleted — only the list association is removed. Response: 204 No Content

​
List Members

GET /v1/contacts/lists/{id}/members List contacts belonging to a specific list (cursor-paginated).
​
id
string
required
List ID
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)

​
Segments

​
List Segments

GET /v1/contacts/segments Retrieve all dynamic contact segments with cursor-based pagination.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)

​
Create Segment

POST /v1/contacts/segments Create a new dynamic segment with filter rules.
​
name
string
required
Segment name
​
rules
object
Filter rules object that defines which contacts belong to this segment
curl -X POST https://orbit-api.devotel.io/api/v1/contacts/segments \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Enterprise Leads",
    "rules": {
      "country_code": "US",
      "lifecycle_stage": "lead",
      "tags": { "$contains": "enterprise" }
    }
  }'

{
  "data": {
    "id": "seg_abc123",
    "name": "US Enterprise Leads",
    "rules": {
      "country_code": "US",
      "lifecycle_stage": "lead",
      "tags": { "$contains": "enterprise" }
    },
    "contact_count": 142,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_seg_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Delete Segment

DELETE /v1/contacts/segments/{id} Delete a dynamic segment. Contacts are not affected.
​
id
string
required
Segment ID
Response: 204 No Content