---
canonical_url: "https://docs.composio.dev/toolkits/seven_io"
markdown_url: "https://docs.composio.dev/toolkits/seven_io.md"
product: "platform"
version: null
last_updated: null
---

# Seven.io

Seven.io provides APIs for SMS, voice, messaging, contacts, phone-number management, and communication analytics.

- **Category:** phone & sms
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `SEVEN_IO`
- **Version:** 00000000_00

## Tools

### Create Contact

**Slug:** `SEVEN_IO_CREATE_CONTACT`

Create a Seven.io contact with identity, address, phone, notes, and group fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | No | Contact city. |
| `email` | string | No | Contact email address. |
| `notes` | string | No | Free-form contact notes. |
| `address` | string | No | Contact street address. |
| `birthday` | string | No | Contact birthday in the format accepted by Seven.io, such as YYYY-MM-DD. |
| `group_ids` | array | No | Existing Seven.io group IDs to assign to the contact. |
| `last_name` | string | No | Contact's last name. |
| `first_name` | string | No | Contact's first name. |
| `home_number` | string | No | Contact home phone number. |
| `postal_code` | string | No | Contact postal code. |
| `mobile_number` | string | No | Contact mobile number, preferably in international format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Contact

**Slug:** `SEVEN_IO_DELETE_CONTACT`

Permanently delete one Seven.io contact by ID. This is destructive and cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_id` | integer | Yes | ID of the contact to permanently delete. Confirm the intended contact before calling. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Format Phone Numbers

**Slug:** `SEVEN_IO_FORMAT_PHONE_NUMBERS`

Validate and normalize one or more phone numbers without performing a paid carrier lookup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `numbers` | array | Yes | Phone numbers to validate and format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Analytics

**Slug:** `SEVEN_IO_GET_ANALYTICS`

Return Seven.io usage statistics for a date range, optionally grouped by date, label, subaccount, or country.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `end` | string | No | Inclusive end date in YYYY-MM-DD format. |
| `label` | string | No | Restrict statistics to this message label. |
| `start` | string | No | Inclusive start date in YYYY-MM-DD format. |
| `group_by` | string ("date" | "label" | "subaccount" | "country") | No | Dimension used to group the statistics. |
| `subaccounts` | string | No | Use only_main, all, or a specific subaccount ID. This filters reporting only and does not route the authenticated account. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Balance

**Slug:** `SEVEN_IO_GET_BALANCE`

Return the connected Seven.io account's available credit balance and currency.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get SMS Pricing

**Slug:** `SEVEN_IO_GET_SMS_PRICING`

Return Seven.io SMS prices, preferably narrowed to one destination country.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `country` | string | No | ISO 3166-1 alpha-2 destination country code, such as DE. Omit only when pricing for all countries is needed. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contacts

**Slug:** `SEVEN_IO_LIST_CONTACTS`

List or search Seven.io contacts, optionally restricted to a contact group.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum contacts to return (30-500). |
| `offset` | integer | No | Zero-based result offset. Increase it by the returned paging count while paging.has_more is true. |
| `search` | string | No | Search text for matching contacts. |
| `group_id` | integer | No | Return only contacts in this group ID. |
| `order_by` | string | No | Contact field used for sorting. |
| `order_direction` | string ("asc" | "desc") | No | Sort direction. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contact Groups

**Slug:** `SEVEN_IO_LIST_GROUPS`

List Seven.io contact groups and their member counts for use in contact filtering or assignment.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum groups to return. Defaults to Seven.io's own page size of 10; raise it for larger pages. |
| `offset` | integer | No | Zero-based result offset. While paging.has_more is true, continue with paging.offset plus paging.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Query Message Journal

**Slug:** `SEVEN_IO_QUERY_MESSAGE_JOURNAL`

Query one page of outbound SMS, inbound SMS, or voice journal entries using a consistent filter interface.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | No | Destination-number filter. |
| `limit` | integer | No | Maximum journal entries to return (1-100). |
| `state` | string | No | Provider journal state filter. |
| `offset` | integer | No | Zero-based result offset. While has_more is true, use the returned next_offset for the following page. |
| `date_to` | string | No | Inclusive end date in YYYY-MM-DD format. |
| `date_from` | string | No | Inclusive start date in YYYY-MM-DD format. |
| `message_id` | integer | No | Restrict results to this provider message ID. |
| `journal_type` | string ("outbound" | "inbound" | "voice") | Yes | Journal to query: outbound SMS, inbound SMS, or voice. The replies journal is intentionally unavailable. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send SMS

**Slug:** `SEVEN_IO_SEND_SMS`

Send an SMS through Seven.io. Live calls contact external recipients and are billable. Sandbox calls validate the request but do not dispatch messages or consume paid products.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | array | Yes | Recipient phone numbers, contact names or IDs, or group names or IDs. Each entry is sent as one recipient. |
| `ttl` | integer | No | Delivery time-to-live in minutes. The default is 2880 (48 hours). |
| `from` | string | No | Sender ID or approved sender number. Seven.io permits up to 11 alphanumeric or 16 numeric characters; a numeric sender may be given in international format with a leading plus. |
| `text` | string | Yes | SMS body, up to 1520 characters. Long messages may be split into multiple billable parts. |
| `delay` | string | No | Future dispatch time as a Unix timestamp or YYYY-MM-DD hh:mm:ss. Omit to send immediately. |
| `flash` | boolean | No | Send as a flash SMS, which supported devices display immediately. |
| `label` | string | No | Tracking label of at most 100 characters using letters, digits, dot, hyphen, underscore, or @. |
| `foreign_id` | string | No | Caller-defined correlation ID of at most 64 characters using letters, digits, dot, hyphen, underscore, or @. |
| `get_replies` | boolean | No | Enable Seven.io reply handling for 48 hours when supported by the account. |
| `performance_tracking` | boolean | No | Enable Seven.io URL shortening and performance tracking for links in the message. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Contact

**Slug:** `SEVEN_IO_UPDATE_CONTACT`

Update selected standard fields or group memberships on an existing Seven.io contact.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | No | Replacement city. |
| `email` | string | No | Replacement email address. |
| `notes` | string | No | Replacement contact notes. |
| `address` | string | No | Replacement street address. |
| `birthday` | string | No | Replacement birthday in the format accepted by Seven.io, such as YYYY-MM-DD. |
| `group_ids` | array | No | Replacement group memberships. Provide at least one existing Seven.io group ID. |
| `last_name` | string | No | Replacement last name. |
| `contact_id` | integer | Yes | ID of the contact to update. |
| `first_name` | string | No | Replacement first name. |
| `home_number` | string | No | Replacement home number. |
| `postal_code` | string | No | Replacement postal code. |
| `mobile_number` | string | No | Replacement mobile number, preferably in international format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |