API docs by Redocly

SendHub (v1)

Contact SendHub: support@sendhub.com License: Limited Terms of Service

SendHub's REST-like API allows you to control & interact with your SendHub account programmatically.

Note: this documentation is in Beta and may be updated periodically.

Contacts

Create and manage contacts.

List Contacts

Gets a list of contacts

See also: List Group Contacts

Authorizations:
(usernameapi_key) basic_auth
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 20

(Pagination) How many records to return

offset
integer
Default: 0

(Pagination) How many records to skip

number
string
Examples:
  • number=%2B18004445555 - Only show contacts with a `number` matching +18004445555
  • number=%2B12015716227 - Only show contacts with a `number` matching +12015716227

Filters contacts by their phone number

The value must be in the E.164 format and URI-encoded (eg. +18004445555 would become %2B18004445555)

name
string
Examples:
  • name=John Smith -
  • name=Bob Parker -

Filters contacts by their name (Will only return contacts whose name matches exactly)

screened
boolean
Examples:
  • screened=true - Only show contacts that you have blocked
  • screened=false - Only show contacts that you haven't blocked

Filters the contacts by their screened status (eg. if you blocked them)

blocked
boolean
Examples:
  • blocked=true - Only show contacts that have opted-out
  • blocked=false - Only show contacts that haven't opted-out

Filters the contacts by opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

ordering
string
Enum: "name" "-name" "date_created" "-date_created" "date_modified" "-date_modified" "id" "-id" "blocked" "-blocked" "screened" "-screened" "is_owned" "-is_owned" "keyword" "-keyword" "number" "-number"
Examples:
  • ordering=-date_created - Sort contacts by date_created last-to-first
  • ordering=date_created - Sort contacts by date_created first-to-last
  • ordering=-date_modified - Sort contacts by date_modified last-to-first
  • ordering=date_modified - Sort contacts by date_modified first-to-last
  • ordering=-name - Sort contacts by their name Z-to-A
  • ordering=name - Sort contacts by their name A-to-Z

Sort contacts by a specified field (prepend a hyphen to reverse order)

Must be a built-in contact field, not a custom field

Responses

Response Schema: application/json
object (meta)
Array of objects (Contact)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "objects": [
    ]
}

Create/Update Contact

Creates or updates a contact

You can add arbitrary custom fields to a contact (see [Custom Fields](#todo: add link here))

Note: the contact's id is required in the request payload if the supplied number already exists in your contacts

This operation doesn't remove properties that aren't specified when updating an existing contact

Use PUT to remove custom fields or groups

Authorizations:
(usernameapi_key) basic_auth
Request Body schema: application/json
Any of
blocked
boolean (blocked)

Opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

contactId (string) or contactIdInt (string) (contactIdBoth)
keyword
string (contactKeyword)

The keyword must be unique and is generated by the contact's name by default. Learn more about how contact keywords are used here.

name
required
string (contactName) [ 1 .. 128 ] characters

The contact's name

number
required
string (contactNumber) ^\+1\d{10}$

The contact's phone number

screened
boolean (screened)

Whether the contact has been blocked by you

Array of groupId (string) or groupIdInt (integer) or groupResourceUri (string) (listOfGroupIds)

List of group resource URIs and/or IDs

property name*
additional property
string or null (customField)

Custom field(s)

There's no limit to the number or size of custom fields (this may be subject to change in the future) except for a total limit of 65,535 bytes for the string of the json object that they're stored in

Note: Custom fields may add very slight load time per contact. This is typically only noticable when listing many contacts that have a large amount of custom fields Note: Setting the value to null removes the custom field

Responses

Response Schema: application/json
Any of
blocked
boolean (blocked)

Opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

deleted
boolean (deleted)
id_str
string (idStr) ^\d+$

Same as id but always a string

is_owned
boolean (isOwned)

This is used internally and may be expanded upon or removed in the future

keyword
string (contactKeyword)

The keyword must be unique and is generated by the contact's name by default. Learn more about how contact keywords are used here.

name
required
string (contactName) [ 1 .. 128 ] characters

The contact's name

number
required
string (contactNumber) ^\+1\d{10}$

The contact's phone number

screened
boolean (screened)

Whether the contact has been blocked by you

id
string (contactId) ^\d+$

The contact ID

date_created
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

date_modified
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

local_gateway
boolean (localGateway)

True if the contact is a SendHub line

resource_uri
string (contactResourceUri) ^\/v\d+(\.\d+)*\/contacts\/\d+$

Resource URI for this contact

groups
Array of strings (listOfGroupResourceUris)

List of group resource URIs

landline
boolean (landline)

Whether SendHub has determined the contact's number is a landline number

landline_override
boolean (landlineOverride)

TODO:

property name*
additional property
string or null (customField)

Custom field(s)

There's no limit to the number or size of custom fields (this may be subject to change in the future) except for a total limit of 65,535 bytes for the string of the json object that they're stored in

Note: Custom fields may add very slight load time per contact. This is typically only noticable when listing many contacts that have a large amount of custom fields Note: Setting the value to null removes the custom field

Request samples

Content type
application/json
Example
{
  • "id": "116006957938283973",
  • "name": "John Smith",
  • "number": "+19198915828"
}

Response samples

Content type
application/json
Example
{
  • "blocked": false,
  • "date_created": "2021-08-24T19:44:31.266590",
  • "date_modified": "2021-08-24T19:44:31.266590",
  • "deleted": false,
  • "groups": [ ],
  • "id": "116006957938283973",
  • "id_str": "116006957938283973",
  • "is_owned": true,
  • "keyword": "john",
  • "local_gateway": false,
  • "name": "John Smith",
  • "number": "+19198915828",
  • "resource_uri": "/v1/contacts/116006957938283973",
  • "screened": false,
  • "landline": false,
  • "landline_override": false,
  • "contact_id": "116006957938283973"
}

Creates, updates, or deletes multiple contacts in one request

Creates, updates, or deletes multiple contacts in one request

Authorizations:
(usernameapi_key) basic_auth
Request Body schema: application/json
Array of upsertContactRequestWithoutId (object) or upsertContactRequestWithoutId (object) (upsertContactRequest)

Responses

Request samples

Content type
application/json
{
  • "objects": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Contact

Retrieves a contact by its id

Authorizations:
(usernameapi_key) basic_auth
path Parameters
required
integer or string

The contact ID

Responses

Response Schema: application/json
blocked
boolean (blocked)

Opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

deleted
boolean (deleted)
id_str
string (idStr) ^\d+$

Same as id but always a string

is_owned
boolean (isOwned)

This is used internally and may be expanded upon or removed in the future

keyword
string (contactKeyword)

The keyword must be unique and is generated by the contact's name by default. Learn more about how contact keywords are used here.

name
required
string (contactName) [ 1 .. 128 ] characters

The contact's name

number
required
string (contactNumber) ^\+1\d{10}$

The contact's phone number

screened
boolean (screened)

Whether the contact has been blocked by you

id
string (contactId) ^\d+$

The contact ID

date_created
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

date_modified
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

local_gateway
boolean (localGateway)

True if the contact is a SendHub line

resource_uri
string (contactResourceUri) ^\/v\d+(\.\d+)*\/contacts\/\d+$

Resource URI for this contact

groups
Array of strings (listOfGroupResourceUris)

List of group resource URIs

landline
boolean (landline)

Whether SendHub has determined the contact's number is a landline number

landline_override
boolean (landlineOverride)

TODO:

property name*
additional property
string or null (customField)

Custom field(s)

There's no limit to the number or size of custom fields (this may be subject to change in the future) except for a total limit of 65,535 bytes for the string of the json object that they're stored in

Note: Custom fields may add very slight load time per contact. This is typically only noticable when listing many contacts that have a large amount of custom fields Note: Setting the value to null removes the custom field

Response samples

Content type
application/json
Example
{
  • "blocked": false,
  • "date_created": "2021-08-24T19:44:31.266590",
  • "date_modified": "2021-08-24T19:44:31.266590",
  • "deleted": false,
  • "groups": [ ],
  • "id": "116006957938283973",
  • "id_str": "116006957938283973",
  • "is_owned": true,
  • "keyword": "john",
  • "local_gateway": false,
  • "name": "John Smith",
  • "number": "+19198915828",
  • "resource_uri": "/v1/contacts/116006957938283973",
  • "screened": false,
  • "landline": false,
  • "landline_override": false
}

Update Contact

Updates an individual contact referenced by its id

You can add arbitrary custom fields to a contact (see Custom Fields)

Note: this is a replace operation; any properties the contact already has that you don't specify in your request will be removed

Use POST for upsert functionality

Authorizations:
(usernameapi_key) basic_auth
path Parameters
required
integer or string

The contact ID

Request Body schema: application/json
blocked
boolean (blocked)

Opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

required
contactId (string) or contactIdInt (string) (contactIdBoth)
keyword
string (contactKeyword)

The keyword must be unique and is generated by the contact's name by default. Learn more about how contact keywords are used here.

name
required
string (contactName) [ 1 .. 128 ] characters

The contact's name

number
required
string (contactNumber) ^\+1\d{10}$

The contact's phone number

screened
boolean (screened)

Whether the contact has been blocked by you

Array of groupId (string) or groupIdInt (integer) or groupResourceUri (string) (listOfGroupIds)

List of group resource URIs and/or IDs

property name*
additional property
string or null (customField)

Custom field(s)

There's no limit to the number or size of custom fields (this may be subject to change in the future) except for a total limit of 65,535 bytes for the string of the json object that they're stored in

Note: Custom fields may add very slight load time per contact. This is typically only noticable when listing many contacts that have a large amount of custom fields Note: Setting the value to null removes the custom field

Responses

Response Schema: application/json
blocked
boolean (blocked)

Opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

deleted
boolean (deleted)
id_str
string (idStr) ^\d+$

Same as id but always a string

is_owned
boolean (isOwned)

This is used internally and may be expanded upon or removed in the future

keyword
string (contactKeyword)

The keyword must be unique and is generated by the contact's name by default. Learn more about how contact keywords are used here.

name
required
string (contactName) [ 1 .. 128 ] characters

The contact's name

number
required
string (contactNumber) ^\+1\d{10}$

The contact's phone number

screened
boolean (screened)

Whether the contact has been blocked by you

id
string (contactId) ^\d+$

The contact ID

date_created
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

date_modified
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

local_gateway
boolean (localGateway)

True if the contact is a SendHub line

resource_uri
string (contactResourceUri) ^\/v\d+(\.\d+)*\/contacts\/\d+$

Resource URI for this contact

groups
Array of strings (listOfGroupResourceUris)

List of group resource URIs

landline
boolean (landline)

Whether SendHub has determined the contact's number is a landline number

landline_override
boolean (landlineOverride)

TODO:

contactId (string) or contactIdInt (string) (contactIdBoth)
property name*
additional property
string or null (customField)

Custom field(s)

There's no limit to the number or size of custom fields (this may be subject to change in the future) except for a total limit of 65,535 bytes for the string of the json object that they're stored in

Note: Custom fields may add very slight load time per contact. This is typically only noticable when listing many contacts that have a large amount of custom fields Note: Setting the value to null removes the custom field

Request samples

Content type
application/json
Example
{
  • "id": "116006957938283973",
  • "name": "John Smith",
  • "number": "+19198915828"
}

Response samples

Content type
application/json
Example
{
  • "blocked": false,
  • "date_created": "2021-08-24T19:44:31.266590",
  • "date_modified": "2021-08-24T19:44:31.266590",
  • "deleted": false,
  • "groups": [ ],
  • "id": "116006957938283973",
  • "id_str": "116006957938283973",
  • "is_owned": true,
  • "keyword": "john",
  • "local_gateway": false,
  • "name": "John Smith",
  • "number": "+19198915828",
  • "resource_uri": "/v1/contacts/116006957938283973",
  • "screened": false,
  • "landline": false,
  • "landline_override": false,
  • "contact_id": "116006957938283973"
}

Delete Contact

Deletes a contact

Authorizations:
(usernameapi_key) basic_auth
path Parameters
required
integer or string

The contact ID

Responses

Response samples

Content type
application/json
{
  • "error": "Requested contact not found",
  • "status": 404
}

List Group's Contacts

Lists contacts in a specified group

Authorizations:
(usernameapi_key) basic_auth
path Parameters
group_id
required
string

The group ID

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 20

(Pagination) How many records to return

offset
integer
Default: 0

(Pagination) How many records to skip

number
string
Examples:
  • number=%2B18004445555 - Only show contacts with a `number` matching +18004445555
  • number=%2B12015716227 - Only show contacts with a `number` matching +12015716227

Filters contacts by their phone number

The value must be in the E.164 format and URI-encoded (eg. +18004445555 would become %2B18004445555)

name
string
Examples:
  • name=John Smith -
  • name=Bob Parker -

Filters contacts by their name (Will only return contacts whose name matches exactly)

screened
boolean
Examples:
  • screened=true - Only show contacts that you have blocked
  • screened=false - Only show contacts that you haven't blocked

Filters the contacts by their screened status (eg. if you blocked them)

blocked
boolean
Examples:
  • blocked=true - Only show contacts that have opted-out
  • blocked=false - Only show contacts that haven't opted-out

Filters the contacts by opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

ordering
string
Enum: "name" "-name" "date_created" "-date_created" "date_modified" "-date_modified" "id" "-id" "blocked" "-blocked" "screened" "-screened" "is_owned" "-is_owned" "keyword" "-keyword" "number" "-number"
Examples:
  • ordering=-date_created - Sort contacts by date_created last-to-first
  • ordering=date_created - Sort contacts by date_created first-to-last
  • ordering=-date_modified - Sort contacts by date_modified last-to-first
  • ordering=date_modified - Sort contacts by date_modified first-to-last
  • ordering=-name - Sort contacts by their name Z-to-A
  • ordering=name - Sort contacts by their name A-to-Z

Sort contacts by a specified field (prepend a hyphen to reverse order)

Must be a built-in contact field, not a custom field

Responses

Response Schema: application/json
object (meta)
Array of objects (Contact)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "objects": [
    ]
}

Groups

Create and manage groups.

List Groups

Gets a list of groups

Authorizations:
(usernameapi_key) basic_auth
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 20

(Pagination) How many records to return

offset
integer
Default: 0

(Pagination) How many records to skip

Responses

Response Schema: application/json
object (meta)
Array of objects (group)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "objects": [
    ]
}

Create Group

Creates a group

Authorizations:
(usernameapi_key) basic_auth
Request Body schema: application/json
name
required
string (groupName) [ 1 .. 128 ] characters

The group's name

is_shared
boolean (isShared)
Deprecated

Whether the group is shared between the lines

slug
string (groupSlug)

The "keyword" used to text-to-join

Defaults to the group name lowercased, without any spaces and not duplicate by appending an incrementing number if needed

mediums
string or null (groupMediums)
Deprecated

This is used internally and may be expanded upon or removed in the future

permissions
string or null (groupPermissions)
Default: "write"
Value: "write"
text_to_subscribe
boolean (textToSubscribe)
Default: false

Whether to enable text-to-join functionality for this group

ttjResponse
string (ttjResponse) <= 70
Default: "You are now subscribed."

A custom response sent when someone texts-to-join this group

Responses

Response Schema: application/json
date_created
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

date_modified
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

deleted
boolean (deleted)
id
string (groupId) ^\d+$

The group ID

id_str
string (idStr) ^\d+$

Same as id but always a string

is_shared
boolean (isShared)
Deprecated

Whether the group is shared between the lines

name
string (groupName) [ 1 .. 128 ] characters

The group's name

parent_id
string or null (nullableString)
parent_user_id
string or null (nullableString)
permissions
string or null (groupPermissions)
Default: "write"
Value: "write"
resource_uri
string (groupResourceUri) ^\/v\d+(\.\d+)*\/groups\/\d+$

Resource URI for this group

share_invite_count
integer or null (nullableInteger)
size
integer or null (groupSize)

The number of contacts that are a memeber of this group

slug
string (groupSlug)

The "keyword" used to text-to-join

Defaults to the group name lowercased, without any spaces and not duplicate by appending an incrementing number if needed

text_to_subscribe
boolean (textToSubscribe)
Default: false

Whether to enable text-to-join functionality for this group

ttjResponse
string (ttjResponse) <= 70
Default: "You are now subscribed."

A custom response sent when someone texts-to-join this group

mediums
string or null (groupMediums)
Deprecated

This is used internally and may be expanded upon or removed in the future

Request samples

Content type
application/json
Example
{
  • "name": "ACME Product Alerts"
}

Response samples

Content type
application/json
Example
{
  • "date_created": "2021-08-24T19:44:31.266590",
  • "date_modified": "2021-08-24T19:44:31.266590",
  • "deleted": false,
  • "id": "115999753870990933",
  • "id_str": "115999753870990933",
  • "is_shared": false,
  • "name": "ACME Product Alerts",
  • "parent_id": null,
  • "parent_user_id": null,
  • "permissions": "write",
  • "resource_uri": "/v1/groups/115999753870990933",
  • "share_invite_count": null,
  • "size": null,
  • "slug": "alerts",
  • "text_to_subscribe": true,
  • "ttjResponse": "Thanks for opting in!\nOpt-out anytime by replying UNSUBSCRIBE ALERTS",
  • "mediums": null
}

Get Group

Gets an individual group by its id

Authorizations:
(usernameapi_key) basic_auth
path Parameters
group_id
required
string

The group ID

Responses

Response Schema: application/json
date_created
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

date_modified
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

deleted
boolean (deleted)
id
string (groupId) ^\d+$

The group ID

id_str
string (idStr) ^\d+$

Same as id but always a string

is_shared
boolean (isShared)
Deprecated

Whether the group is shared between the lines

name
string (groupName) [ 1 .. 128 ] characters

The group's name

parent_id
string or null (nullableString)
parent_user_id
string or null (nullableString)
permissions
string or null (groupPermissions)
Default: "write"
Value: "write"
resource_uri
string (groupResourceUri) ^\/v\d+(\.\d+)*\/groups\/\d+$

Resource URI for this group

share_invite_count
integer or null (nullableInteger)
size
integer or null (groupSize)

The number of contacts that are a memeber of this group

slug
string (groupSlug)

The "keyword" used to text-to-join

Defaults to the group name lowercased, without any spaces and not duplicate by appending an incrementing number if needed

text_to_subscribe
boolean (textToSubscribe)
Default: false

Whether to enable text-to-join functionality for this group

ttjResponse
string (ttjResponse) <= 70
Default: "You are now subscribed."

A custom response sent when someone texts-to-join this group

Response samples

Content type
application/json
Example
{
  • "date_created": "2021-08-24T19:44:31.266590",
  • "date_modified": "2021-08-24T19:44:31.266590",
  • "deleted": false,
  • "id": "115999753870990933",
  • "id_str": "115999753870990933",
  • "is_shared": false,
  • "name": "ACME Product Alerts",
  • "parent_id": null,
  • "parent_user_id": null,
  • "permissions": "write",
  • "resource_uri": "/v1/groups/115999753870990933",
  • "share_invite_count": 0,
  • "size": 1,
  • "slug": "alerts",
  • "text_to_subscribe": true,
  • "ttjResponse": "Thanks for opting in!\nOpt-out anytime by replying UNSUBSCRIBE ALERTS"
}

Update Group

Updates an individual group referenced by its id

Note: this is a replace operation; any properties the group already has that you don't specify in your request will be set to their defaults

Authorizations:
(usernameapi_key) basic_auth
path Parameters
group_id
required
string

The group ID

Request Body schema: application/json
name
required
string (groupName) [ 1 .. 128 ] characters

The group's name

is_shared
boolean (isShared)
Deprecated

Whether the group is shared between the lines

slug
string (groupSlug)

The "keyword" used to text-to-join

Defaults to the group name lowercased, without any spaces and not duplicate by appending an incrementing number if needed

mediums
string or null (groupMediums)
Deprecated

This is used internally and may be expanded upon or removed in the future

permissions
string or null (groupPermissions)
Default: "write"
Value: "write"
text_to_subscribe
boolean (textToSubscribe)
Default: false

Whether to enable text-to-join functionality for this group

ttjResponse
string (ttjResponse) <= 70
Default: "You are now subscribed."

A custom response sent when someone texts-to-join this group

id
required
string (contactId) ^\d+$

The contact ID

Responses

Response Schema: application/json
date_created
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

date_modified
string (timestamp) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

deleted
boolean (deleted)
id
string (groupId) ^\d+$

The group ID

id_str
string (idStr) ^\d+$

Same as id but always a string

is_shared
boolean (isShared)
Deprecated

Whether the group is shared between the lines

name
string (groupName) [ 1 .. 128 ] characters

The group's name

parent_id
string or null (nullableString)
parent_user_id
string or null (nullableString)
permissions
string or null (groupPermissions)
Default: "write"
Value: "write"
resource_uri
string (groupResourceUri) ^\/v\d+(\.\d+)*\/groups\/\d+$

Resource URI for this group

share_invite_count
integer or null (nullableInteger)
size
integer or null (groupSize)

The number of contacts that are a memeber of this group

slug
string (groupSlug)

The "keyword" used to text-to-join

Defaults to the group name lowercased, without any spaces and not duplicate by appending an incrementing number if needed

text_to_subscribe
boolean (textToSubscribe)
Default: false

Whether to enable text-to-join functionality for this group

ttjResponse
string (ttjResponse) <= 70
Default: "You are now subscribed."

A custom response sent when someone texts-to-join this group

mediums
string or null (groupMediums)
Deprecated

This is used internally and may be expanded upon or removed in the future

Request samples

Content type
application/json
Example
{
  • "id": "115999753870990933",
  • "name": "ACME Product Alerts"
}

Response samples

Content type
application/json
Example
{
  • "date_created": "2021-08-24T19:44:31.266590",
  • "date_modified": "2021-08-24T19:44:31.266590",
  • "deleted": false,
  • "id": "115999753870990933",
  • "id_str": "115999753870990933",
  • "is_shared": false,
  • "name": "ACME Product Alerts",
  • "parent_id": null,
  • "parent_user_id": null,
  • "permissions": "write",
  • "resource_uri": "/v1/groups/115999753870990933",
  • "share_invite_count": 0,
  • "size": 1,
  • "slug": "alerts",
  • "text_to_subscribe": true,
  • "ttjResponse": "Thanks for opting in!\nOpt-out anytime by replying UNSUBSCRIBE ALERTS",
  • "mediums": null
}

Delete Group

Deletes a group

Authorizations:
(usernameapi_key) basic_auth
path Parameters
group_id
required
string

The group ID

Responses

Response samples

Content type
application/json
{
  • "error": "You have made too many requests and are being rate limited"
}

List Group's Contacts

Lists contacts in a specified group

Authorizations:
(usernameapi_key) basic_auth
path Parameters
group_id
required
string

The group ID

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 20

(Pagination) How many records to return

offset
integer
Default: 0

(Pagination) How many records to skip

number
string
Examples:
  • number=%2B18004445555 - Only show contacts with a `number` matching +18004445555
  • number=%2B12015716227 - Only show contacts with a `number` matching +12015716227

Filters contacts by their phone number

The value must be in the E.164 format and URI-encoded (eg. +18004445555 would become %2B18004445555)

name
string
Examples:
  • name=John Smith -
  • name=Bob Parker -

Filters contacts by their name (Will only return contacts whose name matches exactly)

screened
boolean
Examples:
  • screened=true - Only show contacts that you have blocked
  • screened=false - Only show contacts that you haven't blocked

Filters the contacts by their screened status (eg. if you blocked them)

blocked
boolean
Examples:
  • blocked=true - Only show contacts that have opted-out
  • blocked=false - Only show contacts that haven't opted-out

Filters the contacts by opt-out status (eg. if they texted Stop, Cancel, Block, Quit or End - more info)

ordering
string
Enum: "name" "-name" "date_created" "-date_created" "date_modified" "-date_modified" "id" "-id" "blocked" "-blocked" "screened" "-screened" "is_owned" "-is_owned" "keyword" "-keyword" "number" "-number"
Examples:
  • ordering=-date_created - Sort contacts by date_created last-to-first
  • ordering=date_created - Sort contacts by date_created first-to-last
  • ordering=-date_modified - Sort contacts by date_modified last-to-first
  • ordering=date_modified - Sort contacts by date_modified first-to-last
  • ordering=-name - Sort contacts by their name Z-to-A
  • ordering=name - Sort contacts by their name A-to-Z

Sort contacts by a specified field (prepend a hyphen to reverse order)

Must be a built-in contact field, not a custom field

Responses

Response Schema: application/json
object (meta)
Array of objects (Contact)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "objects": [
    ]
}

Add/Remove Group's Contacts

Add and/or remove contacts from a group

Authorizations:
(usernameapi_key) basic_auth
path Parameters
group_id
required
string

The group ID

Request Body schema: application/json
One of
required
Array of contactId (string) or contactIdInt (string) (contactIdBoth)

Contact ids that you want to add to this group

Responses

Request samples

Content type
application/json
Example
{
  • "add": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "add": [
    ],
  • "errors": { },
  • "remove": [
    ]
}

Inbox & Threads

View and manage inbox threads.

List Threads

Gets a list of inbox threads

Note: the URL must include the forward-slash after /v1/inbox

The next field in the meta object doesn't include this forward-slash in the URI it provides

We suggest constructing your URIs via your code and using the next field to determine if there's a next page (eg. if next is null)

Authorizations:
(usernameapi_key) basic_auth
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 20

(Pagination) How many records to return

offset
integer
Default: 0

(Pagination) How many records to skip

Responses

Response Schema: application/json
object (meta)
Array of objects (inboxThread)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "objects": [
    ]
}

Get thread

Gets an individual thread by its id

Authorizations:
(usernameapi_key) basic_auth
path Parameters
thread_id
required
integer <int64> >= 1

The thread ID

Responses

Response Schema: application/json
object (threadMeta)
Array of objects

Response samples

Content type
application/json
Example
{
  • "meta": {
    },
  • "objects": [
    ]
}

Delete thread

Deletes an individual thread by its id

Authorizations:
(usernameapi_key) basic_auth
path Parameters
thread_id
required
integer <int64> >= 1

The thread ID

Responses

Response Schema: application/json
message
string

Response samples

Content type
application/json
{
  • "message": "Thread successfully deleted"
}

Messages

Send and manage messages.

Send an SMS or MMS message

Sends an SMS (or MMS based on your plan) to a list of contacts, phone numbers or groups.

Authorizations:
(usernameapi_key) basic_auth
Request Body schema: application/json
One of
text
required
string (messageText) [ 1 .. 1600 ]

The text content of the message Note: Be sure you understand SMS segmenting ((learn more here)[https://sendhub.force.com/support/s/article/how-am-i-billed-for-long-messages])

scheduled_at
string or null (scheduledAt) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[-+]\d{4}...

The date & time in UTC to schedule the message to be sent at.

Note: it must be exactly 24-characters long and in this format: 2022-04-13T15:29:40+0000

Attachment via URL (object) or Attachment via Base64-encoded file (object) (mms)
required
Array of (contactId (string) or contactIdInt (string)) or strings (messageContactIdsOrNumbers) [ 1 .. 25 ] items

Responses

Response Schema: application/json
acknowledgment
required
string or null (acknowledgment) non-empty
required
Array of objects unique
created_at
required
string (messageCreatedAt) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

UTC timestamp of when the message was created

deleted
required
boolean (deleted)
direction
required
string (directionToFrom)
Enum: "to" "from"

The direction of the message; to or from the contact

force_shortlink_creation
required
boolean (forceShortlinkCreation)

If true, creates a shortlink for this message regardless if there's an attachment.

required
Array of objects unique
id
required
string non-empty
id_is_thread_id
required
boolean
message_id
required
string non-empty
required
object
modified_at
required
string non-empty
resource_uri
required
string non-empty
scheduled_at
required
string or null (scheduledAt) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[-+]\d{4}...

The date & time in UTC to schedule the message to be sent at.

Note: it must be exactly 24-characters long and in this format: 2022-04-13T15:29:40+0000

sent
string or null (sent) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

The date & time in UTC the message was sent at.

shortlink
required
string non-empty
text
required
string non-empty
thread_id
required
string non-empty
type
required
string non-empty
unread
boolean or null (messageUnread)

Whether or not the message is marked as unread Changing this will mark the corresponding thread as read or unread

via_shortcode
required
boolean

Request samples

Content type
application/json
Example
{
  • "contacts": [
    ],
  • "text": "Hello there"
}

Response samples

Content type
application/json
{
  • "acknowledgment": "Message queued for sending.",
  • "contacts": [
    ],
  • "created_at": "2021-09-07T19:28:39.099805",
  • "deleted": false,
  • "direction": "to",
  • "force_shortlink_creation": false,
  • "groups": [
    ],
  • "id": "115988808197247577",
  • "id_is_thread_id": true,
  • "message_id": "115995236872293501",
  • "mms": {
    },
  • "modified_at": "2021-09-07T19:28:39.123132",
  • "resource_uri": "/v1/threads/115988808197247577",
  • "scheduled_at": null,
  • "sent": "2021-09-07T19:28:39.099805",
  • "shortlink": "http://sh.gl/5vUtCa",
  • "text": "Hey got 'em'\nFile: http://sh.gl/5vUtCa",
  • "thread_id": "115988808197247577",
  • "type": "message-out",
  • "unread": null,
  • "via_shortcode": false
}

Get Message

Retrieves an existing message by its Id

Authorizations:
(usernameapi_key) basic_auth
path Parameters
message_id
required
string

The message ID

Responses

Response Schema: application/json
acknowledgment
required
string or null (acknowledgment) non-empty
required
Array of objects (messageNestedContact)
created_at
required
string (createdTs) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

deleted
required
boolean (deleted)
direction
required
string (direction)
Enum: "outbound-api" "incoming"

The direction of the message; outbound-api or incoming

force_shortlink_creation
required
boolean (forceShortlinkCreation)

If true, creates a shortlink for this message regardless if there's an attachment.

required
Array of objects (messageNestedGroup)
id
required
string (dynamicThreadId) ^\d+$

If id_is_thread_id is true, this is the thread_id, otherwise it's the message_id

id_is_thread_id
required
boolean (idIsThreadId)

Determines whether id is the thread ID or the message ID

message_id
required
string (messageId) ^\d+$

The message ID

modified_at
required
string (modifiedTs) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

resource_uri
required
string (messageResourceUri) ^\/v\d+(\.\d+)*\/messages\/\d+$

Resource URI for this message

scheduled_at
required
string or null (scheduledAt) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[-+]\d{4}...

The date & time in UTC to schedule the message to be sent at.

Note: it must be exactly 24-characters long and in this format: 2022-04-13T15:29:40+0000

sent
required
string or null (sent) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

The date & time in UTC the message was sent at.

shortlink
required
string (shortlink) ^$|^https?://sh.gl/[a-zA-Z0-9]+$

A short link generated by SendHub when you send a message with an attachment or with force_shortlink_creation set to true

text
required
string (messageText) [ 1 .. 1600 ]

The text content of the message Note: Be sure you understand SMS segmenting ((learn more here)[https://sendhub.force.com/support/s/article/how-am-i-billed-for-long-messages])

thread_id
required
string (threadId) ^\d+$

The thread ID

type
required
string (messageType)
Enum: "voicecall-in" "voicecall-out" "voicecall-missed" "voicecall-voicemail" "message-out" "message-in"

The type of the message (if on the thread object, then the type of the last message in the thread)

unread
required
boolean or null (messageUnread)

Whether or not the message is marked as unread Changing this will mark the corresponding thread as read or unread

via_shortcode
required
boolean (messageViaShortcode)

Send the message via your account's Short Code number (requires a plan with Short Code access (learn more here)[https://sendhub.force.com/support/s/article/shortcode])

object or object (mmsOnlyFilename)

Response samples

Content type
application/json
{
  • "acknowledgment": "Message queued for sending.",
  • "contacts": [
    ],
  • "created_at": "string",
  • "deleted": true,
  • "direction": "outbound-api",
  • "force_shortlink_creation": true,
  • "groups": [
    ],
  • "id": "string",
  • "id_is_thread_id": true,
  • "message_id": "string",
  • "modified_at": "string",
  • "resource_uri": "/v1/messages/123",
  • "scheduled_at": "string",
  • "sent": "string",
  • "shortlink": "string",
  • "text": "string",
  • "thread_id": "string",
  • "type": "voicecall-in",
  • "unread": true,
  • "via_shortcode": true,
  • "mms": {}
}

Update Message

Updates a scheduled message

Authorizations:
(usernameapi_key) basic_auth
path Parameters
message_id
required
string

The message ID

Request Body schema: application/json
One of
text
required
string (messageText) [ 1 .. 1600 ]

The text content of the message Note: Be sure you understand SMS segmenting ((learn more here)[https://sendhub.force.com/support/s/article/how-am-i-billed-for-long-messages])

scheduled_at
string or null (scheduledAt) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[-+]\d{4}...

The date & time in UTC to schedule the message to be sent at.

Note: it must be exactly 24-characters long and in this format: 2022-04-13T15:29:40+0000

Attachment via URL (object) or Attachment via Base64-encoded file (object) (mms)
required
Array of (contactId (string) or contactIdInt (string)) or strings (messageContactIdsOrNumbers) [ 1 .. 25 ] items

Responses

Response Schema: application/json
One of
text
required
string (messageText) [ 1 .. 1600 ]

The text content of the message Note: Be sure you understand SMS segmenting ((learn more here)[https://sendhub.force.com/support/s/article/how-am-i-billed-for-long-messages])

scheduled_at
string or null (scheduledAt) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[-+]\d{4}...

The date & time in UTC to schedule the message to be sent at.

Note: it must be exactly 24-characters long and in this format: 2022-04-13T15:29:40+0000

Attachment via URL (object) or Attachment via Base64-encoded file (object) (mms)
required
Array of (contactId (string) or contactIdInt (string)) or strings (messageContactIdsOrNumbers) [ 1 .. 25 ] items

Request samples

Content type
application/json
Example
{
  • "contacts": [
    ],
  • "text": "Hello there"
}

Response samples

Content type
application/json
Example
{
  • "text": "string",
  • "scheduled_at": "string",
  • "mms": {},
  • "contacts": [ ]
}

Delete Message

Deletes an individual message by its id

Authorizations:
(usernameapi_key) basic_auth
path Parameters
message_id
required
string

The message ID

Responses

Response Schema: application/json
message
string

Success message

Response samples

Content type
application/json
{
  • "message": "Record successfully deleted"
}

List scheduled messages

Lists scheduled messages

Authorizations:
(usernameapi_key) basic_auth

Responses

Response Schema: application/json
objects
Array of objects

Response samples

Content type
application/json
{
  • "objects": [
    ]
}

Profile

View and manage your account and lines

Get Settings

Gets your line's Settings

Authorizations:
(usernameapi_key) basic_auth

Responses

Response Schema: application/json
api_key
string non-empty
auto_attendant_greeting_url
string or null
auto_upgrade_plan
boolean
automated_sms_response
string or null <= 160
conference_lines_enabled
boolean
createdTs
string (createdTs) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

customer_id
string or null (customerId)
deleted
boolean or null (deletedNullable)
desktop_notifications
boolean
disable_incoming_sms
boolean
email_calling_notifications
boolean
ent_toll_free_enabled
boolean or null
enterprise_id
string (enterpriseId) ^\d+$

The enterprise ID

firstPaymentTs
string or null (nullableStringRO)
hide_link_in_bulk_messages
boolean
id
string (internalId) ^\d+$

This is an internal ID and is not the same as a user ID (SendHub line)

image
string or null (nullableStringRO)
is_verified_email
boolean
mfa_enabled
boolean or null
mfa_enforced
boolean
mixpanelid
string or null
Deprecated

This is used internally and may be expanded upon or removed in the future

modifiedTs
string (modifiedTs) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

month_start
string (dateRO) ^\d{4}-\d{2}-\d{2}$
name
string (userName) [ 1 .. 120 ] characters

User's (SendHub line's) name

onboarding_mobile_finished
boolean (onboardingMobileFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

onboarding_web_finished
boolean (onboardingWebFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

payment_period_end
string (dateRO) ^\d{4}-\d{2}-\d{2}$
payment_period_start
string (dateRO) ^\d{4}-\d{2}-\d{2}$
pending_email
string or null (nullableStringRO)
pending_phone_number
string or null (nullableStringRO)
phone_number
string (personalCell) ^\+1\d{10}$

The Personal Cell number in your My Settings page

object
pusher_key
string (pusherKey) non-empty
registration_status
string (registrationStatus) non-empty
Enum: "created" "email_verified" "payment_method_absent" "completed"
resource_uri
string
Value: "/settings"
send_only_via_short_code
boolean
send_only_via_toll_free
boolean
settings_json
string non-empty
siftScienceLabel
string or null
signature
string or null non-empty
sms_forwarding
string or null non-empty
sms_fwd_help
boolean
sms_webhook_url
string or null
sound_notifications
boolean
toll_free_number
string or null
toll_free_primary
boolean
transcribe_voice_mails
boolean
voicemail_greeting_url
string or null

Response samples

Content type
application/json
{
  • "api_key": "12a26b3bc48d52e69f70a82a94a13a29a3fa41a5",
  • "auto_attendant_greeting_url": null,
  • "auto_upgrade_plan": false,
  • "automated_sms_response": "Thank you for reaching out!\nWe'll respond shortlyWe'll respond shortlyWe'll respond shortlyWe'll respond shortly",
  • "conference_lines_enabled": true,
  • "createdTs": "2019-12-19T21:09:21.293391",
  • "customer_id": null,
  • "deleted": null,
  • "desktop_notifications": true,
  • "disable_incoming_sms": true,
  • "email_calling_notifications": true,
  • "ent_toll_free_enabled": false,
  • "enterprise_id": "232267963371095740",
  • "firstPaymentTs": null,
  • "hide_link_in_bulk_messages": true,
  • "id": "115999530581874548",
  • "image": null,
  • "is_verified_email": true,
  • "mfa_enabled": false,
  • "mfa_enforced": false,
  • "mixpanelid": null,
  • "modifiedTs": "2021-08-25T12:06:22.025499",
  • "month_start": "2021-04-20",
  • "name": "Product Alerts",
  • "onboarding_mobile_finished": false,
  • "onboarding_web_finished": false,
  • "payment_period_end": "2020-01-19",
  • "payment_period_start": "2019-12-19",
  • "pending_email": null,
  • "pending_phone_number": null,
  • "phone_number": "+18888888888",
  • "plan_usage": {
    },
  • "pusher_key": "1234567890abcdef1234",
  • "registration_status": "completed",
  • "resource_uri": "/settings",
  • "send_only_via_short_code": false,
  • "send_only_via_toll_free": false,
  • "settings_json": "{\"kazoo_callflow_id\": \"XXX\", \"transcribe_voice_mails\": true, \"kazoo_temporal_rule_id\": \"XXX\", \"kazoo_user_id\": \"XXX\", \"activityLogPath\": \"http://sendhub-prod-user-files.s3.amazonaws.com/activityLogs/2/XXX.csv\", \"toll_free_primary\": true, \"msg_send_rate_limit_timeout\": null, \"sound_notifications\": true, \"desktop_notifications\": true, \"kazoo_device_ids\": [\"XXX\"], \"sms_fwd_help\": true, \"kazoo_account_id\": \"XXX\", \"email_calling_notifications\": true, \"send_only_via_short_code\": false, \"send_only_via_toll_free\": false, \"hide_link_in_bulk_messages\": true, \"kazoo_voicemail_id\": \"XXX\", \"msg_send_rate_limit\": null, \"kazoo_account_realm\": \"232267963371095740.sip.sendhub.com\", \"kazoo_allowed\": true, \"kazoo_auto_attendant_menu_id\": \"XXX\", \"kazoo_vm_media_id\": \"XXX\", \"sms_webhook_url\": null, \"mask_caller_id\": true, \"sms_config\": {\"last_example_ts\": \"1629209040\", \"last_keyword_reminder_ts\": \"1629892091\", \"last_sms_contact_id\": \"116006957937271730\"}}",
  • "siftScienceLabel": null,
  • "signature": "Best Regards,\nSendHub Support",
  • "sms_forwarding": "115999691431257661",
  • "sms_fwd_help": true,
  • "sms_webhook_url": null,
  • "sound_notifications": true,
  • "toll_free_number": null,
  • "toll_free_primary": true,
  • "transcribe_voice_mails": true,
  • "voicemail_greeting_url": null
}

Update Settings

Updates your SendHub line's settings

Authorizations:
(usernameapi_key) basic_auth
Request Body schema: application/json
automated_sms_response
string or null <= 160
desktop_notifications
boolean
disable_incoming_sms
boolean
email_calling_notifications
boolean
hide_link_in_bulk_messages
boolean
name
string (userName) [ 1 .. 120 ] characters

User's (SendHub line's) name

phone_number
string (personalCell) ^\+1\d{10}$

The Personal Cell number in your My Settings page

send_only_via_short_code
boolean
send_only_via_toll_free
boolean
signature
string or null non-empty
sms_forwarding
string or null non-empty
sms_fwd_help
boolean
sms_webhook_url
string or null
sound_notifications
boolean
toll_free_primary
boolean
transcribe_voice_mails
boolean
mask_caller_id
boolean

Responses

Response Schema: application/json
api_key
string non-empty
auto_attendant_greeting_url
string or null
auto_upgrade_plan
boolean
automated_sms_response
string or null <= 160
conference_lines_enabled
boolean
createdTs
string (createdTs) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

customer_id
string or null (customerId)
deleted
boolean or null (deletedNullable)
desktop_notifications
boolean
disable_incoming_sms
boolean
email_calling_notifications
boolean
ent_toll_free_enabled
boolean or null
enterprise_id
string (enterpriseId) ^\d+$

The enterprise ID

firstPaymentTs
string or null (nullableStringRO)
hide_link_in_bulk_messages
boolean
id
string (internalId) ^\d+$

This is an internal ID and is not the same as a user ID (SendHub line)

image
string or null (nullableStringRO)
is_verified_email
boolean
mfa_enabled
boolean or null
mfa_enforced
boolean
mixpanelid
string or null
Deprecated

This is used internally and may be expanded upon or removed in the future

modifiedTs
string (modifiedTs) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

A UTC timestamp

2021-08-01T03:48:55.350453 equals August 1st, 2021 at 3:48 and 55.350453 seconds AM (UTC)

month_start
string (dateRO) ^\d{4}-\d{2}-\d{2}$
name
string (userName) [ 1 .. 120 ] characters

User's (SendHub line's) name

onboarding_mobile_finished
boolean (onboardingMobileFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

onboarding_web_finished
boolean (onboardingWebFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

payment_period_end
string (dateRO) ^\d{4}-\d{2}-\d{2}$
payment_period_start
string (dateRO) ^\d{4}-\d{2}-\d{2}$
pending_email
string or null (nullableStringRO)
pending_phone_number
string or null (nullableStringRO)
phone_number
string (personalCell) ^\+1\d{10}$

The Personal Cell number in your My Settings page

object
pusher_key
string (pusherKey) non-empty
registration_status
string (registrationStatus) non-empty
Enum: "created" "email_verified" "payment_method_absent" "completed"
resource_uri
string
Value: "/settings"
send_only_via_short_code
boolean
send_only_via_toll_free
boolean
settings_json
string non-empty
siftScienceLabel
string or null
signature
string or null non-empty
sms_forwarding
string or null non-empty
sms_fwd_help
boolean
sms_webhook_url
string or null
sound_notifications
boolean
toll_free_number
string or null
toll_free_primary
boolean
transcribe_voice_mails
boolean
voicemail_greeting_url
string or null
mask_caller_id
boolean

Request samples

Content type
application/json
{
  • "automated_sms_response": "string",
  • "desktop_notifications": true,
  • "disable_incoming_sms": true,
  • "email_calling_notifications": true,
  • "hide_link_in_bulk_messages": true,
  • "name": "string",
  • "phone_number": "string",
  • "send_only_via_short_code": true,
  • "send_only_via_toll_free": true,
  • "signature": "string",
  • "sms_forwarding": "string",
  • "sms_fwd_help": true,
  • "sms_webhook_url": "string",
  • "sound_notifications": true,
  • "toll_free_primary": true,
  • "transcribe_voice_mails": true,
  • "mask_caller_id": true
}

Response samples

Content type
application/json
{
  • "api_key": "12a26b3bc48d52e69f70a82a94a13a29a3fa41a5",
  • "auto_attendant_greeting_url": null,
  • "auto_upgrade_plan": false,
  • "automated_sms_response": "Thank you for reaching out!\nWe'll respond shortlyWe'll respond shortlyWe'll respond shortlyWe'll respond shortly",
  • "conference_lines_enabled": true,
  • "createdTs": "2019-12-19T21:09:21.293391",
  • "customer_id": null,
  • "deleted": null,
  • "desktop_notifications": true,
  • "disable_incoming_sms": true,
  • "email_calling_notifications": true,
  • "ent_toll_free_enabled": false,
  • "enterprise_id": "232267963371095740",
  • "firstPaymentTs": null,
  • "hide_link_in_bulk_messages": true,
  • "id": "115999530581874548",
  • "image": null,
  • "is_verified_email": true,
  • "mfa_enabled": false,
  • "mfa_enforced": false,
  • "mixpanelid": null,
  • "modifiedTs": "2021-08-25T12:06:22.025499",
  • "month_start": "2021-04-20",
  • "name": "Product Alerts",
  • "onboarding_mobile_finished": false,
  • "onboarding_web_finished": false,
  • "payment_period_end": "2020-01-19",
  • "payment_period_start": "2019-12-19",
  • "pending_email": null,
  • "pending_phone_number": null,
  • "phone_number": "+18888888888",
  • "plan_usage": {
    },
  • "pusher_key": "1234567890abcdef1234",
  • "registration_status": "completed",
  • "resource_uri": "/settings",
  • "send_only_via_short_code": false,
  • "send_only_via_toll_free": false,
  • "settings_json": "{\"kazoo_callflow_id\": \"XXX\", \"transcribe_voice_mails\": true, \"kazoo_temporal_rule_id\": \"XXX\", \"kazoo_user_id\": \"XXX\", \"activityLogPath\": \"http://sendhub-prod-user-files.s3.amazonaws.com/activityLogs/2/XXX.csv\", \"toll_free_primary\": true, \"msg_send_rate_limit_timeout\": null, \"sound_notifications\": true, \"desktop_notifications\": true, \"kazoo_device_ids\": [\"XXX\"], \"sms_fwd_help\": true, \"kazoo_account_id\": \"XXX\", \"email_calling_notifications\": true, \"send_only_via_short_code\": false, \"send_only_via_toll_free\": false, \"hide_link_in_bulk_messages\": true, \"kazoo_voicemail_id\": \"XXX\", \"msg_send_rate_limit\": null, \"kazoo_account_realm\": \"232267963371095740.sip.sendhub.com\", \"kazoo_allowed\": true, \"kazoo_auto_attendant_menu_id\": \"XXX\", \"kazoo_vm_media_id\": \"XXX\", \"sms_webhook_url\": null, \"mask_caller_id\": true, \"sms_config\": {\"last_example_ts\": \"1629209040\", \"last_keyword_reminder_ts\": \"1629892091\", \"last_sms_contact_id\": \"116006957937271730\"}}",
  • "siftScienceLabel": null,
  • "signature": "Best Regards,\nSendHub Support",
  • "sms_forwarding": "115999691431257661",
  • "sms_fwd_help": true,
  • "sms_webhook_url": null,
  • "sound_notifications": true,
  • "toll_free_number": null,
  • "toll_free_primary": true,
  • "transcribe_voice_mails": true,
  • "voicemail_greeting_url": null,
  • "mask_caller_id": true
}

Get Profile

Gets details about your SendHub line

Authorizations:
(usernameapi_key) basic_auth

Responses

Response Schema: application/json
required
Array of Auth Group (object) or Auth Group (object) or Auth Group (object) or Auth Group (object) (authGroups) non-empty unique
date_joined
required
string (dateJoined) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}$

Timestamp that this SendHub User (line) was created

downvotes
required
integer (downvotes)
Deprecated

This is used internally and may be expanded upon or removed in the future

email
required
string (email) ^(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!...
enterprise
required
string or null (enterpriseName) <= 255 characters

Your company name

enterprise_id
required
string (enterpriseId) ^\d+$

The enterprise ID

enterpriseJoinLink
required
string (enterpriseJoinLink) ^https?://sh\.gl/[a-zA-Z0-9]+$
Deprecated

This is used internally and may be expanded upon or removed in the future

enterpriseSize
required
integer (enterpriseSize)

How manu Users (lines) your account has

mixpanel_id
required
string or null <int64> (mixpanelId)
Deprecated

This is used internally and may be expanded upon or removed in the future

name
required
string or null (enterpriseName) <= 255 characters

Your company name

onboarding_mobile_finished
required
boolean (onboardingMobileFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

onboarding_web_finished
required
boolean (onboardingWebFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

payment_plan_id
required
integer <int64> (planId)

The plan ID

resource_uri
required
string (profileResourceUri) ^\/v\d+(\.\d+)*\/profile$

Resource URI for this User's profile

sendhub_number
required
string (formattedSendhubNumber) ^\(\d{3}\) \d{3}-\d{4}$

This line's SendHub number (formatted)

unread
required
integer (profileUnread)

Shows how many unread threads this User (line) has

upvotes
required
integer (upvotes)
Deprecated

This is used internally and may be expanded upon or removed in the future

user_id
required
string (userId) ^\d+$

The ID of a SendHub user (an individual line)

username
required
string (username) [ 1 .. 254 ] characters

User's (SendHub line's) username

Response samples

Content type
application/json
{
  • "auth_groups": [
    ],
  • "date_joined": "2019-12-19T21:09:21.216167",
  • "downvotes": 0,
  • "email": "alerts@acme.com",
  • "enterprise": "ACME Inc.",
  • "enterpriseJoinLink": "http://sh.gl/HAmMgR",
  • "enterpriseSize": 6,
  • "enterprise_id": "232267963371095740",
  • "mixpanel_id": null,
  • "name": "Product Alerts",
  • "onboarding_mobile_finished": false,
  • "onboarding_web_finished": false,
  • "payment_plan_id": 1268,
  • "resource_uri": "/v1/profile",
  • "sendhub_number": "(201) 571-6227",
  • "unread": 0,
  • "upvotes": 0,
  • "user_id": "283014186889381821",
  • "username": "alerts@acme.com"
}

Get Enterprise (Account)

Gets your enterprise account's details

Authorizations:
(usernameapi_key) basic_auth
path Parameters
enterprise_id
required
string

Your enterprise account's ID

Note: You can find your enterprise_id in the /v1/settings or /v1/profile endpoints

Responses

Response Schema: application/json
brand_id
string or null (brandId)

10DLC Brand ID

createdTs
required
string non-empty
customerId
required
string non-empty
hasAccessToChatSupport
required
boolean
Deprecated
hash
required
string non-empty
id
required
string non-empty
joinUrl
required
string non-empty
Deprecated
modifiedTs
required
string non-empty
month_start
required
string non-empty
name
required
string or null (enterpriseName) <= 255 characters

Your company name

payment_plan_id
required
integer
resource_uri
required
string non-empty
settingsJson
required
string non-empty
shortcode_allowed
required
boolean

Response samples

Content type
application/json
{
  • "brand_id": {
    },
  • "createdTs": "2018-06-07T17:59:51.186701",
  • "customerId": "cus_D0TMCytXFqWuNO",
  • "hasAccessToChatSupport": true,
  • "hash": "XXX",
  • "id": "232267963371095740",
  • "joinUrl": "http://sh.gl/HAmMgR",
  • "modifiedTs": "2021-08-24T19:31:26.420082",
  • "month_start": "2021-08-09",
  • "name": "ACME Inc.",
  • "payment_plan_id": 11,
  • "resource_uri": "/v1/enterprises/232267963371095740",
  • "settingsJson": "{\"mms_enabled\": false, \"integrationsAllowed\": true, \"activityLogPath\": \"http://sendhub-prod-user-files.s3.amazonaws.com/activityLogs/2/XXX.csv\"}",
  • "shortcode_allowed": false
}

List Users

Lists your enterprise account's users (lines)

Authorizations:
(usernameapi_key) basic_auth
path Parameters
enterprise_id
required
string

Your enterprise account's ID

Note: You can find your enterprise_id in the /v1/settings or /v1/profile endpoints

Responses

Response Schema: application/json
object (meta)
Array of objects (listNestedUser)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "objects": [
    ]
}

Get User

Gets a user (line)

Authorizations:
(usernameapi_key) basic_auth
path Parameters
enterprise_id
required
string

Your enterprise account's ID

Note: You can find your enterprise_id in the /v1/settings or /v1/profile endpoints

user_id
required
integer <int64> >= 1

The SendHub user (line)'s ID

Note: You can find your user_id in the /v1/profile endpoint You can list all the users in your account via the /v1/enterprises/{enterprise_id}/users endpoint

Responses

Response Schema: application/json
createdTs
required
string (createdTsWithoutDecimal) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

A UTC timestamp

2021-08-01T03:48:34 equals August 1st, 2021 at 3:48 and 34 seconds AM (UTC)

disable_incoming_sms
required
boolean (disableIncomingSms)
enterprise_id
required
string (enterpriseId) ^\d+$

The enterprise ID

enterprise_id_str
required
string (enterpriseIdStr) ^\d+$

The enterprise ID

id
required
string (id) ^\d+$
id_str
required
string (idStr) ^\d+$

Same as id but always a string

image
required
string (image)

The URL for this user's profile image

is_verified_email
required
boolean (isVerifiedEmail)

Whether this user's email has been verified

modifiedTs
required
string (modifiedTsWithoutDecimal) non-empty ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

A UTC timestamp

2021-08-01T03:48:34 equals August 1st, 2021 at 3:48 and 34 seconds AM (UTC)

name
required
string (userName) [ 1 .. 120 ] characters

User's (SendHub line's) name

onboarding_mobile_finished
required
boolean (onboardingMobileFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

onboarding_web_finished
required
boolean (onboardingWebFinished)
Deprecated

This is used internally and may be expanded upon or removed in the future

payment_period_end
required
string (paymentPeriodEnd) ^\d{4}-\d{2}-\d{2}$
payment_period_start
required
string (paymentPeriodStart) ^\d{4}-\d{2}-\d{2}$
payment_schedule_id
required
string (paymentScheduleId) non-empty ^\d+$
Enum: "1" "2" "3"

Your plan's payment schedule type:

  1. Monthly 2. Yearly 3. Consumable (eg. free trial)
pending_phone_number
string (pendingPhoneNumber) ^\+1\d{10}|$

Phone number waiting to be verified for the "Personal Cell" field

phone_number
string (personalCell) ^\+1\d{10}$

The Personal Cell number in your My Settings page

registration_status
required
string (registrationStatus) non-empty
Enum: "created" "email_verified" "payment_method_absent" "completed"
sendhub_number
required
string (sendhubNumber) ^\+1\d{10}$

This line's SendHub number (E.164 format)

settings_json
required
string (settingsJson) non-empty
signature
required
string (signature)

Signature that the SendHub apps append to new messages Note: SendHub does not use this field when sending via the API

required
id (string) or idInt (integer) (twilioPhoneNumberId)
Deprecated

This is used internally and may be expanded upon or removed in the future

required
id (string) or idInt (integer) (twilioPhoneNumberIdStr)
Deprecated

This is used internally and may be expanded upon or removed in the future

user_id
required
string (userId) ^\d+$

The ID of a SendHub user (an individual line)

user_id_str
required
string (userId) ^\d+$

The ID of a SendHub user (an individual line)

required
Array of Auth Group (object) or Auth Group (object) or Auth Group (object) or Auth Group (object) (authGroups) non-empty unique
username
required
string (username) [ 1 .. 254 ] characters

User's (SendHub line's) username

Response samples

Content type
application/json
{
  • "id": "115999530581874548",
  • "user_id": "283014186889381821",
  • "enterprise_id": "232267963371095740",
  • "phone_number": "+18888888888",
  • "twilio_phone_number_id": "115999766167712690",
  • "registration_status": "completed",
  • "image": "",
  • "signature": "Best Regards,\nACME Inc.",
  • "disable_incoming_sms": false,
  • "automated_sms_response": "",
  • "payment_schedule_id": "1",
  • "payment_period_start": "2019-12-19",
  • "payment_period_end": "2020-01-19",
  • "onboarding_web_finished": false,
  • "onboarding_mobile_finished": false,
  • "settings_json": "{\"kazoo_callflow_id\": \"XXX\", \"transcribe_voice_mails\": true, \"kazoo_temporal_rule_id\": \"XXX\", \"kazoo_user_id\": \"XXX\", \"activityLogPath\": \"http://sendhub-prod-user-files.s3.amazonaws.com/activityLogs/2/XXX.csv\", \"toll_free_primary\": false, \"msg_send_rate_limit_timeout\": null, \"sound_notifications\": true, \"desktop_notifications\": true, \"kazoo_device_ids\": [\"XXX\"], \"sms_fwd_help\": true, \"kazoo_account_id\": \"XXX\", \"email_calling_notifications\": true, \"send_only_via_short_code\": false, \"send_only_via_toll_free\": false, \"hide_link_in_bulk_messages\": true, \"kazoo_voicemail_id\": \"XXX\", \"msg_send_rate_limit\": null, \"kazoo_account_realm\": \"232267963371095740.sip.sendhub.com\", \"kazoo_allowed\": true, \"kazoo_auto_attendant_menu_id\": \"XXX\", \"kazoo_vm_media_id\": \"XXX\", \"sms_webhook_url\": null, \"mask_caller_id\": false, \"sms_config\": {\"last_example_ts\": \"1629209040\", \"last_keyword_reminder_ts\": \"1629873648\", \"last_sms_contact_id\": \"116006957938283973\"}}",
  • "is_verified_email": true,
  • "createdTs": "2019-12-19T21:09:21",
  • "modifiedTs": "2021-08-25T06:47:16",
  • "auth_groups": [
    ],
  • "username": "alerts@acme.com",
  • "id_str": "115999530581874548",
  • "user_id_str": "283014186889381821",
  • "enterprise_id_str": "232267963371095740",
  • "twilio_phone_number_id_str": "115999766167712690",
  • "name": "Product Alerts",
  • "sendhub_number": "+12015716227",
  • "sms_forwarding": "115999691431257661"
}

Authentication

Log in via Username & Password and "Sign In As User"

Username & password login

Log in via username & password

Authorizations:
(usernameapi_key) basic_auth
Request Body schema: application/json
authenticationType
string
Enum: "sendhub" "manager"
sessionId
string
username
string
password
string

Responses

Response Schema: application/json
authToken
string
authenticationType
string (authenticationType)
Enum: "sendhub" "manager"
csrf_token
string
emailAddress
string
kazooApiPassword
string or null
password
string

Always giong to return '******'

resource_uri
string
Value: "/api/v1/auth"
sendhub_number
string (sendhubNumber) ^\+1\d{10}$

This line's SendHub number (E.164 format)

object
sipDeviceId
string or null (nullableString)
sipPassword
string or null (nullableString)
user_id
string (userId) ^\d+$

The ID of a SendHub user (an individual line)

username
string (username) [ 1 .. 254 ] characters

User's (SendHub line's) username

Request samples

Content type
application/json
{
  • "authenticationType": "sendhub",
  • "sessionId": "string",
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "authToken": "string",
  • "authenticationType": "sendhub",
  • "csrf_token": "string",
  • "emailAddress": "string",
  • "kazooApiPassword": "string",
  • "password": "string",
  • "resource_uri": "/api/v1/auth",
  • "sendhub_number": "string",
  • "settings": {
    },
  • "sipDeviceId": "string",
  • "sipPassword": "string",
  • "user_id": "string",
  • "username": "string"
}