Entitlements API

Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.

List entitlements

List entitlements (recommended)

List the available entitlements.

GEThttps://CONNECT-DOMAIN/api/v2/customer/entitlements

Authorization

sfsAuthentication

Response

200401403

List of found entitlements

Body

application/json

entitlementsany

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/entitlements', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "entitlements": [
    "WECHAT",
    "WHATSAPP",
    "SMS",
    "SMS-DIRECT",
    "LINE"
  ]
}

Add entitlement

Add entitlement (recommended)

Entitle a Symphony user to use the external network.

POSThttps://CONNECT-DOMAIN/api/v2/customer/entitlements

Authorization

sfsAuthentication

Body

application/json

advisorEmailAddressstring

externalNetwork*string

External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE

symphonyIdstring

advisorPhoneNumberstring (phone)

Required for the advisor to access SMS Direct In-Network and supported for SMS Direct Second-Number. Supported for the advisor to access WhatsApp Direct. However, note that the advisor’s phone number is not applicable for onboarding the advisor to other external networks (WeChat, WhatsApp, SMS or LINE).

permissionsarray of string

federationGroupIdstring

Response

201400401403404409500

The user has successfully been added in the list of entitlements.

Body

application/json

symphonyIdstring

firstNamestring

lastNamestring

companyNamestring

displayNamestring

emailAddressstring

advisorPhoneNumberstring (phone)

avatarstring

externalNetworkstring

permissionsarray of list-permission-response (string)

federationGroupIdstring

ownContactIdstring

phonephone (object)

Phone number (direct EMP case)

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/entitlements', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "externalNetwork": "WHATSAPP"
    }),
});
const data = await response.json();

Response

{
  "symphonyId": 14362370637825,
  "firstName": "William",
  "lastName": "Smith",
  "companyName": "Company",
  "displayName": "William Smith",
  "emailAddress": "[e-mail]",
  "advisorPhoneNumber": "text",
  "avatar": "https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png",
  "externalNetwork": "WHATSAPP",
  "permissions": [
    "create:room"
  ],
  "federationGroupId": "federationGroupId",
  "ownContactId": 14362370637825,
  "phone": {
    "number": "[phone]",
    "product": "PRE_ALLOCATED_HOSTED",
    "subNetwork": "SECOND-NUMBER"
  }
}

List entitled advisors

List entitled advisors

List all entitled advisors on a given external network.

GEThttps://CONNECT-DOMAIN/api/v1/customer/entitlements/externalNetwork/{externalNetwork}/advisors

Authorization

sfsAuthentication

Path parameters

externalNetwork*string

External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE

Query parameters

Response

200401403

List of found entitled advisors.

Body

application/json

entitlementsarray of entitlement-response (object)

paginationPagination

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/entitlements/externalNetwork/{externalNetwork}/advisors', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "entitlements": [
    {
      "symphonyId": "14362370637825",
      "firstName": "William",
      "lastName": "Smith",
      "companyName": "Company",
      "displayName": "William Smith",
      "emailAddress": "[e-mail]",
      "avatar": "https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png",
      "externalNetwork": "text",
      "federationGroupId": "federationGroupId",
      "phone": {
        "number": "[phone]",
        "product": "PRE_ALLOCATED_HOSTED",
        "subNetwork": "SECOND-NUMBER"
      }
    }
  ],
  "pagination": {
    "previous": "?before=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "next": "?after=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "cursors": {
      "before": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
      "after": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9"
    }
  }
}

Get an advisor's entitlement

Get an advisor's entitlement (recommended)

Check if a given advisor is entitled for a given external network. Advisors can be identified using their email address or their Symphony user ID (if both are provided, the Symphony user ID will take precedence)

GEThttps://CONNECT-DOMAIN/api/v2/customer/advisor/entitlements

Authorization

sfsAuthentication

Query parameters

Response

200400401403404500

Advisor data (if an entitled advisor has been found)

Body

application/json

symphonyIdstring

firstNamestring

lastNamestring

companyNamestring

displayNamestring

emailAddressstring

avatarstring

externalNetworkstring

federationGroupIdstring

phonephone (object)

Phone number (direct EMP case)

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/advisor/entitlements', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "symphonyId": "14362370637825",
  "firstName": "William",
  "lastName": "Smith",
  "companyName": "Company",
  "displayName": "William Smith",
  "emailAddress": "[e-mail]",
  "avatar": "https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png",
  "externalNetwork": "text",
  "federationGroupId": "federationGroupId",
  "phone": {
    "number": "[phone]",
    "product": "PRE_ALLOCATED_HOSTED",
    "subNetwork": "SECOND-NUMBER"
  }
}

Remove entitlement

Remove entitlement (recommended)

Removes a given advisor's entitlement for a given external network. Advisors can be identified using their email address or their Symphony user ID (if both are provided, the Symphony user ID will take precedence)

DELETEhttps://CONNECT-DOMAIN/api/v2/customer/advisor/entitlements

Authorization

sfsAuthentication

Query parameters

Response

200401403404

The entitlement has been successfully removed.

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/advisor/entitlements', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Add pre-entitlement

Pre-entitle an advisor to a phone number (WhatsApp Direct only)

Pre-allocate a phone number to an advisor to allow the advisor to activate their phone number. Supported on WhatsApp Direct only Umony numbers are not eligible for pre-entitlements. Symphony users using Umony numbers can skip the pre-entitlement step and be entitled directly.

POSThttps://CONNECT-DOMAIN/api/v1/customer/pre-entitlements/{symphonyId}/externalNetwork/{externalNetwork}

Authorization

sfsAuthentication

Path parameters

symphonyIdstring

Symphony User Id

externalNetworkstring

External network: WHATSAPP-DIRECT

Body

application/json

advisorPhoneNumber*string (phone)

federationGroupIdstring

Response

200400404409500

The phone number has been successfully allocated to the user.

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/pre-entitlements/{symphonyId}/externalNetwork/{externalNetwork}', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "advisorPhoneNumber": "text"
    }),
});
const data = await response.json();

Remove pre-entitlement

Remove an advisor pre-entitlement (WhatsApp Direct only)

Remove an advisor pre-entitlement Supported on WhatsApp Direct only

DELETEhttps://CONNECT-DOMAIN/api/v1/customer/pre-entitlements/{symphonyId}/externalNetwork/{externalNetwork}

Authorization

sfsAuthentication

Path parameters

symphonyIdstring

Symphony User Id

externalNetworkstring

External network: WHATSAPP-DIRECT

Response

200400403404

The pre-entitlement has been removed successfully.

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/pre-entitlements/{symphonyId}/externalNetwork/{externalNetwork}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();