Phone.com

Phone.com Express Sign-Up Integration Guide

Version: 1.0.23 @ 2025-10-08T20:09:38.418Z

Demo: express-signup-demo.cit-phone.com

Markdown version

Overview

Phone.com offers Express Sign-Up functionality for partners to enable them to provide Phone.com services to their customers.

This integration requires approval and cooperation with Phone.com. If you haven't been in touch with us yet, please reach out to our support team.

Services Offered Through Express Sign-Up

Customers onboarded via Express Sign-Up can choose from the following services:

How It Works

You need to import our Express Sign-Up library, run its components, and implement a few endpoints in your server-side application.

Express Sign-Up Diagram

Full integration

Express Sign-Up library is flexible, so it could be different setups, but the most Phone.com-based setup includes usage of Phone.com billing and authorization. In that case we will take care of your integration's back-end.

Requirements

Partner Portal Requirements

Phone.com Account Configuration

Integration

Server-Side Application + Phone.com API

API calls related to the sign-up are meant to be performed from your server-side application with your access token. Thus, you will need to create some endpoints which will act as a proxy between your customers and Phone.com API.

Create Subaccount

The endpoint should send a username, password, and contact to the Create Subaccount API endpoint.

Please make sure that you create accounts for real paying customers because you will be billed for the services they consume.

Username

You should generate a username in a way that it will be associated with some identifier of the user of your Portal and be unique for Phone.com. For example, it can be super-partner-12345, where super-partner is the name of your business and 12345 will be the ID of the user in your system.

Password

You can generate long random passwords and securely store them or don't store them at all - in that case, you will need to use the token of your main account as a password, but this option is disabled by default and requires approval from Phone.com.

Contact

Contact can be requested at the client-side or, if there is a contact on file, it can be used without asking the customer to provide it.

NodeJS Example
async function createSubaccount(username, password, contact) {
    const { token, voip_id } = getPhoneComAPIConfig();
    const res = await fetch(`https://api.phone.com/v4/accounts/${voip_id}/subaccounts`, {
        headers: { Authorization: `Bearer ${token}` },
        method: 'POST',
        body: JSON.stringify({ username, password, contact }),
    });
    if (!res.ok) throw new Error('Something went wrong');
    return await res.json();
}

If Phone.com Billing is being used, you may also need to provide billing_contact and credit-card token

Get Phone.com Access Token for the User

Once the user signs up, you need to generate a token for that specific user which will be used by the client-side application.

If you don't store passwords, you will need to use your account's token as a password.

NodeJS Example
async function getPhoneComTokenForUser(username, password = null) {
    const { token } = getPhoneComAPIConfig();
    const q = new URLSearchParams();
    q.append('redirect_uri', 'https://express.phone.com');
    q.append('response_type', 'token');
    q.append('scope', 'account-owner');
    const url = `https://oauth-api.phone.com/client/6b75f80c-3390-5409-1c05-b9f7bfd778b6/authorization?${q.toString()}`;
    const res = await fetch(url, {
      method: 'POST',
      body: JSON.stringify({ username, password: password || token }),
    });
    const payload = await res.json();
    if (res.ok) return payload;
    console.warn(payload);
    return null;
  }

Front-End Application + Phone.com Express Sign-Up Library

Our library is hosted at express-signup-lib.cit-phone.com.

It uses ES6 import/export functionality, so you can only import it into a JavaScript file included into the page as a module:

<script type="module" src="/integration.mjs"></script>

integration.mjs will look like this:

import ExpressSignUpFlow from 'https://express-signup-lib.cit-phone.com/latest/index.mjs';

// ...
const expressSignUp = await ExpressSignUpFlow.init('PARTNER_ID', options, callback);
expressSignUp.render(document.getElementById('express-sign-up-container'));
// ...

Express Sign In Flow

If the user has not yet created a Phone.com account, you should render the ExpressSignUpFlow component.

It accepts two arguments - options and callback. callback is the function which will be called when sign-up is finished successfully. options define the component's behavior.

Available Options

Most Important Options
Styling
Other Options
Contact Example
{
    "name": "FirstName LastName",
    "company": "Book Depository",
    "address": {
        "line_1": "411 Elm, st.",
        "line_2": "",
        "city": "Dallas",
        "province": "TX",
        "postal_code": "75202",
        "country": "US"
    },
    "phone": "+15555550001",
    "primary_email": "test@example.com"
}

Express Console

When the customer already has a Phone.com account or just signed up, you should render the ExpressConsole component of the Library. It requires an access token generated for the user.

ExpressConsole.init accepts 3 arguments - partner, options and callback. callback is the function which will be called when the user decides to sign out from the Express Console. options define the component's behavior.

Available Options