API docs by Redocly

Textable Backend API (7.4.15@99c40ebc)

Download OpenAPI specification:Download

Canned Responses

Get list of canned responses for a user.

Authorizations:
UserToken

Responses

Response samples

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

Drip Campaigns

Get list of drip campaigns for the current user.

Authorizations:
UserToken

Responses

Response samples

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

Contacts

Get list of contacts.

Lists contacts owned by the user associated with the API key used to make the request

Authorizations:
UserToken

Responses

Response samples

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

Create a contact.

Authorizations:
UserToken
Request Body schema: application/json
required

Create a contact.

phoneNumber
required
string

The contact's phone number in E.164 format

fullName
string

Full name of contact.

email
string

E-mail address of contact.

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "+15554443333",
  • "fullName": "John Doe",
  • "email": "john.doe@gmail.com"
}

Response samples

Content type
application/json
{
  • "id": "abc123xyz",
  • "fullName": "John Doe",
  • "email": "john.doe@gmail.com",
  • "last_message": "Hello, Textable!",
  • "last_message_date": 1670372913091
}

Get a single contact by id.

Authorizations:
UserToken
path Parameters
id
any

Contact document id

Responses

Response samples

Content type
application/json
{
  • "id": "abc123xyz",
  • "fullName": "John Doe",
  • "email": "john.doe@gmail.com",
  • "last_message": "Hello, Textable!",
  • "last_message_date": 1670372913091
}

Apply a drip campaign to a contact

Applies a drip campaign to a specific contact if the authenticated user has access to both the contact and the campaign.

Authorizations:
UserToken
path Parameters
id
required
string

The ID of the contact

Request Body schema: application/json
required
dripCampaignId
required
string

ID of the drip campaign to apply

Responses

Request samples

Content type
application/json
{
  • "dripCampaignId": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "error": "string"
}

Messages

Send (or schedule) a SMS or MMS message

Send (or schedule) a SMS or MMS message for a specified phone number, store a "note" or a message sent from an external system.

Authorizations:
UserToken
Request Body schema: application/json
required

Send, schedule or store a SMS / MMS message or store a note.

to
required
string

The recipient's phone number in E.164 format.

from
required
string

The sender's phone number in E.164 format.

message
required
string

The body of the message.

media
Array of strings

(Optional) An array of publicly available URLs to include as MMS attachments.

notify
boolean

(Optional) A boolean that dictates whether or not to send a notification to the Texatble user that a note or message has been stored.

sendAt
number

(Optional) A UTC timestamp in the future when to schedule the message to be sent. The timestamp is in ms.

sendStatus
string
Value: "sent"

(Optional) If set to "sent", this will store a message, not send it, assuming it has already been sent to the carrier.

type
string
Value: "note"

(Optional) If set to "note", this will store the message body as a note that is visible to all users and shared users of the from number. This will NOT send a message to the recipient.

autoArchive
boolean
Default: false

If true, the conversation's archived status will be set to true.

reminder
boolean

If true, the message will be a reminder and displayed in the reminder section in the app. **note reminder messages require timezone and sendAt fields

scheduleTimezone
string
Enum: "America/Los_Angeles" "America/Denver" "America/Chicago" "America/New_York"

A required field for sending reminders.

Responses

Request samples

Content type
application/json
{
  • "to": "+15554443333",
  • "from": "+15554442222",
  • "message": "Hello, Textable!",
  • "media": [],
  • "notify": true,
  • "sendAt": 2880544055000,
  • "sendStatus": "sent",
  • "type": "note",
  • "autoArchive": false,
  • "reminder": true,
  • "scheduleTimezone": "America/Los_Angeles"
}

Organizations

Get list of organizations.

Authorizations:
UserToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates an organization.

Authorizations:
UserToken
Request Body schema: application/json
required
organizationName
required
string

A short name for the organization.

description
string

Description or note for the organization.

organizationPlanSelection
string

A string representing the plan name of the organization.

object
requireContactConsent
boolean

A boolean value representing whether or not the organization should enforce sending the consent message.

requireContactConsentMessage
string

A string representing the content of the organization's consent message.

tenantId
string

The ID of the tenant that this organization belongs to.
This is required for new organizations if more than one tenant exists in the instance. If only one tenant exists in the instance, this field will be automatically set to the tenant ID of the only tenant. It is not currently supported to change an organization's tenantId, but this will be added in the future.

Responses

Request samples

Content type
application/json
{
  • "organizationName": "string",
  • "description": "string",
  • "organizationPlanSelection": "mcpl-starter",
  • "billing": {
    },
  • "requireContactConsent": true,
  • "requireContactConsentMessage": "string",
  • "tenantId": "string"
}

Response samples

Content type
application/json
{
  • "id": "iw8guE9ndCkMXzyVmDezmyO0Il0SzA9i"
}

Update an organization.

Authorizations:
UserToken
Request Body schema: application/json
required
organizationName
required
string

A short name for the organization.

description
string

Description or note for the organization.

organizationPlanSelection
string

A string representing the plan name of the organization.

object
requireContactConsent
boolean

A boolean value representing whether or not the organization should enforce sending the consent message.

requireContactConsentMessage
string

A string representing the content of the organization's consent message.

is_disabled
boolean

Marks this organization (and all users belonging to it) as disabled. This will prevent log-in, sending mesages, and blasts / reminders for the afffected users. Billing (if applicable) will also be suspended for affected users.

Responses

Request samples

Content type
application/json
{
  • "organizationName": "string",
  • "description": "string",
  • "organizationPlanSelection": "mcpl-starter",
  • "billing": {
    },
  • "requireContactConsent": true,
  • "requireContactConsentMessage": "string",
  • "is_disabled": true
}

Add Organization Admin

Adds an organization admin to organization referenced by "id", based on e-mail address

Authorizations:
UserToken
path Parameters
id
required
string

The ID of the organization to edit

Request Body schema: application/json
required

email address of the user to add

email
required
string

The email address of the user to add as an org admin

Must already exist as a user in the application

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Delete Organization Admin

Delete organization admin from provided organization id

Authorizations:
UserToken
path Parameters
orgid
required
string

The ID of the organization to edit

userid
required
string

The user id of the admin to remove from the org

Responses

Users

Gets users

Gets all users in the application. Requires admin since no users are trimmed from the result set.

Authorizations:
UserToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create user

Creates a user.

Only valid in privatelabel context.

Newly created users must have a email and phone number that are not already in use.

Authorizations:
UserToken
Request Body schema: application/json
required

Details about the user to create

phoneNumber
required
string

The user's phone number in E.164 format.

The supplied phone number must not be in use by any other users.

provider
string

The name of the provider to use for this user

Required if credentialSource is user

If supplied, all credential properties for the selected provider must be included as top-level keys on the submitted post object

emailAddress
required
string
password
string
fullName
string
organizationId
string

If not supplied, this will default to the organization of the user making this request

relayWebhook
string

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "provider": "string",
  • "emailAddress": "string",
  • "password": "string",
  • "fullName": "string",
  • "organizationId": "string",
  • "relayWebhook": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Edit user

Updates a user's details.

Notice: it is not possible to update certain user fields via this API:

  • Provider Credentials
  • Application password
Authorizations:
UserToken
path Parameters
id
required
string

The ID of the user to edit

Request Body schema: application/json
required

Details about the user to update

phoneNumber
string

The user's phone number in E.164 format.

The supplied phone number must not be in use by any other users.

emailAddress
string

If the email supplied is different from the users existing email, it will be updated in the authentication system and the existing password will continue to work

provider
string

The name of the provider to use for this user

fullName
string
organizationId
string
relayWebhook
string
disabled
boolean

Users marked as disabled may not log in or make API calls.
Canned resposnes or auto replies for these users will not be sent. If applicable, the billing quantity will also be reduced for disabled users.

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "emailAddress": "string",
  • "provider": "string",
  • "fullName": "string",
  • "organizationId": "string",
  • "relayWebhook": "string",
  • "disabled": true
}

Edit user Webhook URL

Updates the webhook URL for a user

Authorizations:
UserToken
Request Body schema: application/json
required

Update detail for the webhook URL

url
string

URL to which messages (inbound and outbound) should be POSTed

Format of the POST body will be:

{
   MessageID: string
   ConversationID: string
   ToNumber: string
   FromNumber: string
   MessageBody: string
   MessageDirection: string
   TextableUserID: string
   ContactName: string
   ContactEmail: string
   AccessToken?: string  
}

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Create user API Token

Create a user API token

Authorizations:
UserToken

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

Other

Get an export

Authorizations:
UserToken

Responses

Contacts

Update Contact By Id

Updates a contact according to the attributes supplied.

Authorizations:
FirebaseAuthUserTokenSystemToken
Request Body schema: application/json
required

the properties to update.

full_name
string
phone_number
string
email
string
title
string
companyName
string
notes
string
optedOut
boolean

Sets Boolean value controling if the contact has opted out of communications

isArchived
boolean

Sets the status of the contact and conversations to archived

Responses

Request samples

Content type
application/json
{
  • "full_name": "string",
  • "phone_number": "string",
  • "email": "string",
  • "title": "string",
  • "companyName": "string",
  • "notes": "string",
  • "optedOut": true,
  • "isArchived": true
}

Delete Contact By Id

Deletes a contact by its unique identifier.

Authorizations:
FirebaseAuthUserTokenSystemToken

Responses

Apply Drip Campaign to Contact

Applies a drip campaign to a contact.

Authorizations:
FirebaseAuthUserTokenSystemToken
Request Body schema: application/json
required

the properties to update.

dripCampaignId
string

The ID of the drip campaign to apply to the contact

Responses

Request samples

Content type
application/json
{
  • "dripCampaignId": "string"
}

Response samples

Content type
application/json
{
  • "dripCampaignId": "string",
  • "addedDripMessages": [
    ]
}

Users

Get User by Id

Retrieves details for a user by ID

Authorizations:
FirebaseAuthSystemTokenUserToken
path Parameters
id
required
string

The user's ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "is_disabled": true,
  • "full_name": "string",
  • "email": "string",
  • "organizationId": "string",
  • "phone_number": "string",
  • "sharedWith": [
    ],
  • "deleted": 0,
  • "restrictions": [
    ],
  • "relayWebhook": "string",
  • "autoReplyMessage": "string",
  • "signatureEnabled": true,
  • "signatureText": "string",
  • "isAdmin": true,
  • "provider": "string"
}

Deletes a Private Label User

API Route to delete a user by id.

Defaults to marking the user for deletion insted of actually removing the user. Specify force in the query string to forcefully delete the user

UserToken authentication for this API call is restricted for retail instances.

Super Admin users may not be deleted and attempts to do so will fail

Admin users may be deleted by other admin users

The user making the request may not delete their own account

Authorizations:
FirebaseAuthSystemTokenUserToken
path Parameters
id
required
string

The ID of the user to delete

query Parameters
force
boolean

When true, the user is deleted immediately. Defaults to false, so the user will be deleted after some time.

Responses

Update User

Updates properties for a user

Authorizations:
FirebaseAuthSystemTokenUserToken
Request Body schema: application/json
required

User update request body

email
required
string

Provide the e-mail address of the user. This is used for login and notifications.

full_name
required
string

The full name of the user. e.g. John Doe

phone_number
string

The user's phone number in E.164 format.

The supplied phone number must not be in use by any other users.

restrictions
Array of strings
Items Enum: "blasts" "reminders" "dripCampaign" "importContacts" "lists" "deleteAll" "disableDelete" "integrations"

List of restrictions applied to the user to manage their ability access features.

Here are the matching permission names on Textable UI.

"blasts"(Blasts), "reminders"(Reminders), "dripCampaign"(Drip Campaign), "importContacts"(Import Contacts), "lists"(Contact Lists), "deleteAll"(Delete All Contacts), "disableDelete"(Delete Contact and Messages), or "integrations"(Integrations)

provider
string

The name of the provider to use for this user

Required if credentialSource is user

If supplied, all credential properties for the selected provider must be included as top-level keys on the submitted post object

password
string

Sets the password to the provided value.

organizationId
string

If not supplied, this will default to the organization of the user making this request

relayWebhook
string

A publicly available URL that a copy of each message (inbound and outbound) will be sent to via HTTP POST.

external_id
string

Use this field to store an external_id field for this user (e.g. from your PBX or your identity provider.)

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "full_name": "string",
  • "phone_number": "string",
  • "restrictions": [
    ],
  • "provider": "string",
  • "password": "string",
  • "organizationId": "string",
  • "relayWebhook": "string",
  • "external_id": "string"
}

Create a Private Label user

Creates a user in the context of a Private Label

Authorizations:
FirebaseAuthSystemTokenUserToken
Request Body schema: application/json
required
email
required
string

Provide the e-mail address of the user. This is used for login and notifications.

full_name
string

The full name of the user. e.g. John Doe

isAdmin
boolean

If true, this field sets the user as a system admin. Note: This is a sensitive field as it will provide the user access to all organizations and user settings.

phone_number
required
string

The user's phone number in E.164 format.

The supplied phone number must not be in use by any other users.

restrictions
Array of strings
Items Enum: "blasts" "reminders" "dripCampaign" "importContacts" "lists" "deleteAll" "disableDelete" "integrations"

List of restrictions applied to the user to manage their ability access features.

Here are the matching permission names on Textable UI.

"blasts"(Blasts), "reminders"(Reminders), "dripCampaign"(Drip Campaign), "importContacts"(Import Contacts), "lists"(Contact Lists), "deleteAll"(Delete All Contacts), "disableDelete"(Delete Contact and Messages), or "integrations"(Integrations)

provider
string

The name of the provider to use for this user

Required if credentialSource is user

If supplied, all credential properties for the selected provider must be included as top-level keys on the submitted post object

password
string

Sets the password to the provided value.

organizationId
required
string

If not supplied, this will default to the organization of the user making this request

relayWebhook
string

A publicly available URL that a copy of each message (inbound and outbound) will be sent to via HTTP POST.

external_id
string

Use this field to store an external_id field for this user (e.g. from your PBX or your identity provider.)

tenantId
required
string

The ID of the tenant this user belongs to.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "full_name": "string",
  • "isAdmin": true,
  • "phone_number": "string",
  • "restrictions": [
    ],
  • "provider": "string",
  • "password": "string",
  • "organizationId": "string",
  • "relayWebhook": "string",
  • "external_id": "string",
  • "tenantId": "string"
}

Response samples

Content type
application/json
null

Sends welcome email

Sends or resends the welcome email to a new user

Authorizations:
FirebaseAuthSystemTokenUserToken

Responses

Sends a test push notification to the user's device(s)

Sends a test push notification to the user's device(s)

Responses

Change password

Changes the password of the user specified in :id. All other logged-in sessions of this user will be terminated. If the requestor is changing their own password, a new auth token will be returned.

Authorizations:
FirebaseAuthSystemTokenUserToken
Request Body schema: application/json
required

New password

password
string

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
Example
{
  • "status": "Reset own password",
  • "newToken": "#NEW TOKEN"
}

Create user API Token

Create user API Token

Authorizations:
FirebaseAuthSystemTokenUserToken

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

Delete user API Token

Delete user API Token

Authorizations:
FirebaseAuthSystemTokenUserToken

Responses

Organizations

Get Organizations

Get all organizations.

Presently only available to admins, as the results are not trimmed according to organizations within the user's management scope.

TODO: TXBDEV-1916 - Allow tenant admin / org admin users to GET /api/v2/organizations

Authorizations:
FirebaseAuthUserTokenSystemToken

Update Organization

Updates an organization according to the attributes supplied.

Authorizations:
FirebaseAuthUserTokenSystemToken
Request Body schema: application/json
required

the properties to update.

organizationName
string
organizationAdmins
Array of strings
managedBy
string

User ID of mangager of Organization.

description
string
requireContactConsent
boolean

When an organization has this property set to true, anytime a user in the organization sends a message to a contact who has not yet received a consent message, a consent message will automatically be sent to the contact

requireContactConsentMessage
string

The body text of the consent message to send.

object
is_disabled
boolean

Marks this organization (and all users belonging to it) as disabled. This will prevent log-in, sending mesages, and blasts / reminders for the afffected users. Billing (if applicable) will also be suspended for affected users.

tenantId
string

The ID of the tenant that this organization belongs to.
This is required for new organizations if more than one tenant exists in the instance. If only one tenant exists in the instance, this field will be automatically set to the tenant ID of the only tenant. It is not currently supported to change an organization's tenantId, but this will be added in the future.

object

Responses

Request samples

Content type
application/json
{
  • "organizationName": "string",
  • "organizationAdmins": [
    ],
  • "managedBy": "string",
  • "description": "string",
  • "requireContactConsent": true,
  • "requireContactConsentMessage": "string",
  • "billing": {
    },
  • "is_disabled": true,
  • "tenantId": "string",
  • "provider": {
    }
}

Delete Organization

Delete organization from provided organization id

Authorizations:
FirebaseAuthSystemTokenUserToken
path Parameters
orgid
required
string

The ID of the organization to delete

query Parameters
force
boolean

When true, the organization is deleted immediately. Defaults to false, so the org will be deleted after some time.

Responses

Other

Start document schema validation

Initiates the document schema validation process.

Authorizations:
FirebaseAuthUserToken
path Parameters
uid
string

Optionally constrains the schema validation to documents owned by this user ID.

Responses

Bulk Operations

Mark as unread

API Route to mark a number of selected contact ids and set read_status to false.

Authorizations:
FirebaseAuth
Request Body schema: application/json
required

Array of contact id strings.

contactsArray
Array of strings

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": true
}

Canned Responses

Create a canned response.

Creates a canned response.

Authorizations:
FirebaseAuthUserToken
Request Body schema: application/json
required
uid
string

The user id of the user to add the canned response for.

name
string

A friendly name to represent the canned response content.

body
string

The body of the canned response text message.

auto_keyword
string

A keyword that when received would trigger the canned response as an auto-reply.

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "name": "string",
  • "body": "string",
  • "auto_keyword": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Tenants

Creates a new Tenant object

Authorizations:
SystemToken
Request Body schema: application/json
required
tenantName
required
string
tenant_external_identifier
required
string

store an identifer for the tenant for referencing another system

billingGroup
string

an identifier used to group multiple tenants for billing purposes

adminBillingPlan
string

the internal name of the billing plan assigned to organizations created for Tenant Admins

required
object
primarySupportContactEmail
required
string

Responses

Request samples

Content type
application/json
{
  • "tenantName": "string",
  • "tenant_external_identifier": "string",
  • "billingGroup": "string",
  • "adminBillingPlan": "string",
  • "provider": {
    },
  • "primarySupportContactEmail": "string"
}

Response samples

Content type
application/json
{
  • "body": "Created tenant `tenantName` (`tenantId`)"
}

Create Tenant Admin

Creates or updates the tenant admin user (identified by email).

If a user with the specified email address already exists, the user will be added to the list of administrators for the tenant idenfied by tenant_external_identifier

If this is the first admin created for this tenant, a new organization will be created: "Tenant Administrators of " with a billing plan defaulting to either the tenant's adminBillingPlan, or the instance's defaultTenantAdminBillingPlan value.

The the tenant to which this admin is being added does not have a support email address, the domain of this request's email address will be used to generate a support address of support@<domain>

Request Body schema: application/json
required
email
required
string

Email address of the user to create; NOT used for correlating the user when consuming SSO claims

external_id
required
string

An identifier used to correlate this user with incoming claims (e.g. SAML NameID) from an external identity provider. See SAML Response

tenant_external_identifier
required
string

An identifier used to correlate this tenant with an entity in an external system

full_name
required
string

Name of the user to create/update.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "external_id": "string",
  • "tenant_external_identifier": "string",
  • "full_name": "string"
}

Response samples

Content type
application/json
{
  • "body": "string",
  • "userId": "string",
  • "tenantId": "string",
  • "organizationId": "string",
  • "warning": "string"
}

Creates a new or updates a Tenant object

Authorizations:
SystemToken
Request Body schema: application/json
required
tenantName
required
string
tenant_external_identifier
required
string

store an identifer for the tenant for referencing another system

billingGroup
string

an identifier used to group multiple tenants for billing purposes

adminBillingPlan
string

the internal name of the billing plan assigned to organizations created for Tenant Admins

required
object
primarySupportContactEmail
required
string

Responses

Request samples

Content type
application/json
{
  • "tenantName": "string",
  • "tenant_external_identifier": "string",
  • "billingGroup": "string",
  • "adminBillingPlan": "string",
  • "provider": {
    },
  • "primarySupportContactEmail": "string"
}

Response samples

Content type
application/json
{
  • "body": "Created/Updated tenant `tenantName` (`tenantId`)"
}

Billing

Get Billing For a Tenant

Gets billing details for a single tenant

Authorizations:
SystemToken
path Parameters
tenantId
required
string

The ID of the tenant for which to generate a billing report

Responses

Response samples

Content type
application/json
{
  • "TenantName": "Skyswitch Training",
  • "TenantExternalId": 20681,
  • "TenantBillingGroup": "string",
  • "LicenseAllocation": {
    },
  • "OrganizationBreakdown": [
    ],
  • "UserBreakdown": [
    ],
  • "UserQuantity": 10
}

Get billing report for all tenants

Gets billing details for all tenants

Authorizations:
SystemToken

Responses

Response samples

Content type
application/json
[
  • {
    }
]

API Beta

Behavior of routes in this group is subject to change or removal without changes to the major or minor version number

Block a number from sending messages to the user

One or more contact block requests

Authorizations:
FirebaseAuthUserToken
Request Body schema: application/json
required

Array of contact block requests

Array
action
string
Enum: "block" "unblock"

Action to take for the provided contact

sender
string

Sender to block. Can be either an E.164 phone number or a contact id

user
string

User for which to apply the block operation. Can be either an E.164 phone number or a user id

object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Upload batches of Contacts

POST an array of contact operations. The operation will be batched to the database, and the request will return once the batch is committed.

Authorizations:
FirebaseAuthUserToken
Request Body schema: application/json
required

An array of contact operations to perform

Array of objects

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "string",
  • "details": {
    }
}

Search for and merge duplicate contacts

This endpoint is used to search for and merge duplicate contacts for the requesting user

Authorizations:
FirebaseAuthUserToken
Request Body schema: application/json
optional

Parameters for the duplicate contact search / merge operation

uid
string

The user ID to search for duplicate contacts. If not specified, the authenticated user's ID will be used.

execute_merge
boolean

Whether to merge the duplicate contacts. If not specified, the default is false.

Responses

Request samples

Content type
application/json
{
  • "uid": "string",
  • "execute_merge": true
}

Response samples

Content type
application/json
{
  • "duplicates": [
    ],
  • "merged": true,
  • "errors": [
    ]
}

Frontend

Do not use these routes. The behavior is subject to change or be removed without notice. See TXBDEV-2858 for more details

Get Billing For a Tenant

Gets billing details for a single tenant

Authorizations:
FirebaseAuth

Responses

Get Billing For all Tenants

Gets billing details for all tenants

Authorizations:
FirebaseAuth

Responses

Get Installed integrations

Gets integrations currently installed for the requesting user.

Authorizations:
FirebaseAuth

Responses

Get Available integrations

Gets integrations available for installation by the requesting user.

Authorizations:
FirebaseAuth

Responses

Adds an organization

Adds an organization for either private label or retail

Authorizations:
FirebaseAuth

Responses

Adds an organization

Adds an organization for either private label or retail

Authorizations:
FirebaseAuth

Responses

Updates number sharing for a user

Updates number sharing for a user

Authorizations:
FirebaseAuth

Responses

Updates the User's message settings

API endpoint for use only by PrivateFrontend (the web application). Allows the "Messaging Settings" page to change User Documents

Authorizations:
FirebaseAuth

Responses

Delete conversation history

Deletes all messages in a conversation, sets the last message to null, and marks the conversation as read and archived

Authorizations:
FirebaseAuth
Request Body schema: application/json
required
contact_id
required
string

The rcontact id to delete messages for

Responses

Request samples

Content type
application/json
{
  • "contact_id": "string"
}

Get Contact Consent Requirement

Determines whether the requested contact is subject to required consent-obtaining messages.

Authorizations:
FirebaseAuth

Responses

SkySwitch Exclusive

Gets SMS-enabled assignments

Gets SMS-enabled assignments for the current tenant from the SkySwitch PBX endpoint at https://telco.readme.io/v1.0/docs/list-sms-enabled-assignments

Authorizations:
FirebaseAuth

PBX number assignment to SkySwitch's telco API

Responses

PBX number assignment to SkySwitch's telco API

Authorizations:
FirebaseAuth

Responses

Click to call SkySwitch API

Authorizations:
FirebaseAuth
Request Body schema: application/json
required
destination
string
callAsUID
string

Responses

Request samples

Content type
application/json
{
  • "destination": "string",
  • "callAsUID": "string"
}

Health Check

Healthcheck

Returns 200 if the backend application is behaving correctly

Responses

Response samples

Content type
application/json
{
  • "status": "pass",
  • "time": "2019-08-24T14:15:22Z",
  • "version": "string",
  • "releaseId": "string",
  • "notes": [
    ],
  • "output": "string",
  • "checks": {
    },
  • "links": {
    },
  • "serviceId": "string",
  • "description": "string"
}

SSO

Gets available SSO providers

Gets a list of the configured Identity Providers (IdP) for this instance from Firestore.

These providers are currently maintained by manually editing documents in the auth-providers collection but TXBDEV-1102 will create an in-app management page for IdP

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Check if password login is allowed for a user

Determines whether password login is permitted for the specified e-mail address, based on the user record and system-wide settings. If the user has an external SSO ID, password login is only allowed if the feature 'restrictLocalPasswordLogin' is disabled in app-data/authentication. This same logic is applied for determining self-service passwrod reset eligibility

path Parameters
email
required
string

The e-mail address to check

Responses

Response samples

Content type
application/json
{
  • "passwordLoginAllowed": true
}

Start OAuth SSO Workflow

Called by frontend or mobile AuthNZ service's providerLogin function to initiate the SSO workflow for an OAuth Authorization Server

Will almost always be loaded within the scope of a browser popup or mobile InAppBrowser (having location bar and cache disabled)

Expected flow is defined in RFC 6749, section 4.1: Authorization Code Grant

The response from the Authorization Server should result in a GET call to /auth/oauth/:provider/callback

path Parameters
provider
required
string

The ID of the provider for which to start the SSO workflow.

Responses

Receive OAuth "Authorization Grant" code

Process the "Authorization Grant" code response from the Authorization Server.

Exchang the "code" for an "Access Token" and optionally fetch the UserInfo for the user

Correlate incoming claims with a user in our database, and issues a signing token for frontend / mobile. If no user exists and "allowJITProvisioning" is enabled, a new user is created and a signing token is issued. If no user exists and "allowJITProvisioning" is disabled, an error is returned

query Parameters
code
string

OAuth "Authorization Grant" code returned by the Authorization Server to be exchanged for an "Access Token"

refresh_token
string
Deprecated

For OAuth2 Authorization Servers that deviate from RFC6749 4.1.2, this parameter can be used in place of the "code" parameter

Responses

Response samples

Content type
text/html
<html><body><script>
  function SAMLPostback() {
  const ssoResponse={"token":"","error":true};
  if (window.webkit && window.webkit.messageHandlers) {
  return ssoResponse;
  } else { 
  opener.postMessage(ssoResponse,'undefined');
  }
  window.close();
  }
  SAMLPostback();
</script>REDIRECTING</body></html>

Start SAML SSO Workflow

Called by frontend or mobile AuthNZ service's providerLogin function to initiate the SSO workflow for an Identity Provider (IdP)

Will almost always be laoded within the scope of a browser popup or mobile InAppBrowser (having location bar and cache disabled)

The response of a successful authentication from the IdP will be posted to /auth/saml/callback

path Parameters
ProviderName
required
string

The name of the provider for which to start the SSO workflow. Must match the name of the document in auth-providers.

Used in getAuthProviderNameFromRequest to resolve to a Firebase document

Responses

Consume SAMLResponse body from IdP

Receive and process the SAML response given to us by the IdP.

Verify issuer of incoming claims by ensuring the signature can be verified by the IdP's certificate, and that the incoming claims were the result of a request we actually made (i.e. not requested by another party).

Correlate incoming claims with a user in our database, and issues a signing token for frontend / mobile

Request Body schema: application/x-www-form-urlencoded
required

Claims provided by the IdP in response to a successful authentication

RelayState
object

JSON object which was created by /auth/saml/login; passed to the IdP; and then passed back to this endpoint

SAMLResponse
string

Base64 encoded XML document conatining a SAMLResponse

Responses

Response samples

Content type
text/html
<html><body><script>
  function SAMLPostback() {
  const ssoResponse={"token":"","error":true};
  if (window.webkit && window.webkit.messageHandlers) {
  return ssoResponse;
  } else { 
  opener.postMessage(ssoResponse,'undefined');
  }
  window.close();
  }
  SAMLPostback();
</script>REDIRECTING</body></html>

Service Accounts

Generate a JWT token for a user

Generates a JWT token for a user with the given user ID.

Request Body schema: application/json
required
userId
string

The ID of the user for whom to generate the JWT.

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Revoke user token by external ID

Revokes a user's token using their external ID.

Request Body schema: application/json
required
externalId
string

The external ID of the user whose token is to be revoked.

Responses

Request samples

Content type
application/json
{
  • "externalId": "string"
}

Revoke user token by email

Revokes a user's token using their email address.

Request Body schema: application/json
required
email
string

The email of the user whose token is to be revoked.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Revoke user token by UID

Revokes a user's token using their UID.

Request Body schema: application/json
required
userId
string

The UID of the user whose token is to be revoked.

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Webhooks

Message Event Webhook

Relay sends a POST to the URL stored in the relayWebhook attribute of the user for which a message is sent or received.

Request Body schema: application/json
MessageID
string

The unique message ID

ConversationID
string

The unique contact ID

string or Array of strings

For Group MMS, this will be an array of strings. For all other messages, this will be a single string.

FromNumber
string

The number the message was sent from

MessageBody
string

The message body

MessageDirection
string

The message direction (either "in" or "out")

TextableUserID
string

The user id of the account that sent or received the message

TextableOrganizationID
string

The unique identifier for the Textable organization

ContactName
string

The Full Name property of the contact

ContactEmail
string

The e-mail address of the contact (if available). Not present for group messages.

AccessToken
string or null

The access token for the user

Media
Array of strings

Responses

Request samples

Content type
application/json
{
  • "MessageID": "string",
  • "ConversationID": "string",
  • "ToNumber": "string",
  • "FromNumber": "string",
  • "MessageBody": "string",
  • "MessageDirection": "string",
  • "TextableUserID": "string",
  • "TextableOrganizationID": "string",
  • "ContactName": "string",
  • "ContactEmail": "string",
  • "AccessToken": "string",
  • "Media": [
    ]
}