Contact API

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

Add a contact and/or advisors to a contact

Add a contact and/or advisors to a contact (recommended)

Add a contact and/or advisor(s) to the contact. This end point can be called in 2 situations:

Note

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

Authorization

Body

firstName*string

lastName*string

companyNamestring

For SMS, LINE, WHATSAPP and WECHAT, the companyName is mandatory

emailAddressstring (email)

For SMS, LINE, WHATSAPP and WECHAT, the emailAddress is mandatory

phoneNumber*string (phone)

externalNetwork*string

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

advisorSymphonyIdsarray of number

A list of Symphony user IDs of the advisors to add the contact to.

preferredLanguagestring

Contact preferred language code

advisorEmailAddressesarray of string (email)

A list of email addresses of the advisor to whom the contact is to be added. For WeChat, an "onboarder" is an advisor with the permission "create:contact". For WhatsApp, SMS, SMS Direct and LINE, the permission is set by default.

onboarderEmailAddress*string

If both advisorSymphonyIds and advisorEmailAddresses are empty, the contact will be added to the onboarder with this email address.

createRoomboolean

Can be set to false in order to prevent the room creation when onboarding a contact on SMS Direct or WhatsApp Direct. This parameter can't be set to true for WhatsApp, SMS, Wechat and LINE for now.

Response

Contact added successfully

Body

firstNamestring

lastNamestring

companyNamestring

emailAddressstring

phoneNumberstring

externalNetworkstring

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

symphonyIdstring

statusenum

PENDING_CONFIRMATIONCONFIRMEDINVITE_EXPIREDCANCELEDUNAVAILABLEINCOMPLETE

statusUpdateDatestring (date-time)

preferredLanguagestring

invitationCodestring

phoneNumberBlockedByarray of blocked-by-item (object)

Request

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/contacts', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "externalNetwork": "WHATSAPP",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": 911234567890,
      "onboarderEmailAddress": "william.smith@symphony.com"
    }),
});
const data = await response.json();

Response

{
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "Company",
  "emailAddress": "johndoe@symphony.com",
  "phoneNumber": 911234567890,
  "externalNetwork": "WHATSAPP",
  "symphonyId": 12345678912365,
  "status": "PENDING_CONFIRMATION",
  "statusUpdateDate": 1547661232368,
  "preferredLanguage": "CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE (among others, see release note for more)",
  "invitationCode": "AB12DE43",
  "phoneNumberBlockedBy": [
    {
      "advisorSymphonyId": "text",
      "reason": "SPAM",
      "comment": "text",
      "requestDate": "2024-05-01T07:05:59.592Z"
    }
  ]
}

Copy contact

Create a new contact copy. Some contacts might be shared between tenants. Shared contacts updates are not allowed. This API allows to create a contact copy that is dedicated for the requesting tenant and that can be updated. Contacts that are created starting from the 23.03 release are already not shared between tenants. This API is dedicated for shared contacts created prior to the 23.03 release. Please note:

POSThttps://CONNECT-DOMAIN/api/v1/customer/contacts/{contactSymphonyId}/copy

Authorization

Path parameters

contactSymphonyId*string

Contact's Symphony ID

Response

Contact successfully copied

Body

newSymphonyIdstring

Symphony user ID of the account copy

migratedStreamIdsarray of string

StreamIds of the rooms in which the user's account has been replaced with the account copy.

Request

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/contacts/{contactSymphonyId}/copy', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "newSymphonyId": 12345678912365,
  "migratedStreamIds": [
    "text"
  ]
}

Update contact

Update contact (recommended)

Update a contact's first name, last name, company name (maximum 25 characters) and, if the advisor has the permission for this, the contact's email address for a given external network. Note: Updating a contact's phone number is not supported.

PUThttps://CONNECT-DOMAIN/api/v2/customer/contacts/{contactSymphonyId}

Authorization

Path parameters

contactSymphonyId*string

Contact's Symphony user ID

Body

firstName*string

lastName*string

companyName*string

phoneNumber*string (phone)

emailAddressstring

advisorSymphonyId*string

preferredLanguagestring

Contact preferred language. Refer to contact preferred language section at the beginning of this documentation for valid language name.

Response

Contact successfully updated

Body

firstNamestring

lastNamestring

companyNamestring

emailAddressstring

phoneNumberstring

symphonyIdstring

Federated user Symphony id

advisorsarray of string

Advisors Symphony IDs

preferredLanguagestring

Contact preferred language

Request

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/contacts/{contactSymphonyId}', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "firstName": "John",
      "lastName": "DoeABC",
      "companyName": "Company",
      "phoneNumber": 911234567890,
      "advisorSymphonyId": 1234567890
    }),
});
const data = await response.json();

Response

{
  "firstName": "John",
  "lastName": "DoeABC",
  "companyName": "Company",
  "emailAddress": "johndoe@symphony.com",
  "phoneNumber": 911234567890,
  "symphonyId": 12345678912365,
  "advisors": [
    14362370637825
  ],
  "preferredLanguage": "CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE, etc."
}

Resend a new invitation

Resend a new onboarding invitation to contact

Only applicable for networks requiring onboarding invitations: WeChat, LINE. Sends a new onboarding invitation to the contact with the onboarding instructions and a new authentication one-time-password token, if applicable. Required to reset the contact's invitation after it expires. The invitation expiry counter (7 days) is reset to zero and the status is changed from "Expired" to "Pending". LINE since 23.04: If the user enters an expired one-time-password token within the first 7 days they were onboarded, they automatically receive a new valid token. After the 7 days, calling this api is required to reset the user invitation status and to generate a new token.

POSThttps://CONNECT-DOMAIN/api/v1/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId}/resendInvite

Authorization

Path parameters

contactSymphonyId*string (number)

Contact's Symphony user ID

advisorSymphonyId*string (number)

Onboarder's Symphony user ID

Response

The invite has been resent successfully.

Body

invitationCodestring

Request

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId}/resendInvite', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "invitationCode": "AB12DE43"
}

Remove contact

Remove contact (recommended)

Remove an advisor's contact searching by the advisor's Symphony user ID and the contact's Symphony user ID

DELETEhttps://CONNECT-DOMAIN/api/v2/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId}

Authorization

Path parameters

advisorSymphonyId*string (number)

Advisor's Symphony user ID

contactSymphonyId*string (number)

Contact's Symphony user ID

Response

Contact successfully removed

Request

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

Remove all contacts

Remove all contacts (recommended)

Removes all contacts of an advisor matching the advisor's Symphony user ID.

DELETEhttps://CONNECT-DOMAIN/api/v2/customer/contacts/advisor/{advisorSymphonyId}

Authorization

Path parameters

advisorSymphonyId*string (number)

Advisor's Symphony user ID

Response

Call completed - Report provided with the list of SUCCESSFUL and FAILED operations

Body

reportarray of customer-deleteAdvisorContact-responsev2 (object)

Request

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

Response

{
  "report": [
    {
      "contact": {
        "advisorSymphonyId": 1234567890,
        "phoneNumber": "+1 234567890",
        "externalNetwork": "WHATSAPP"
      },
      "status": "FAILURE"
    }
  ]
}

Remove the contact from all advisors they are connected to for a given external network

Remove the contact from all advisors they are connected to for a given external network (recommended)

Remove the contact from all the advisors they are connected to for a given external network.

DELETEhttps://CONNECT-DOMAIN/api/v2/customer/contacts/{contactSymphonyId}

Authorization

Path parameters

contactSymphonyId*string (number)

Contact's Symphony user ID

Response

Contact found. The response includes a status report (SUCCESS or FAILURE) of the connection removal for each advisors initially connected to the contact.

Body

reportarray of customer-contactWithId-responsev2 (object)

Request

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

Response

{
  "report": [
    {
      "contact": {
        "advisorSymphonyId": "text"
      },
      "status": "FAILURE"
    }
  ]
}

Bulk remove advisor-contact connections

Bulk remove advisor-contact connection (recommended)

Remove specific advisor-contact connections in bulk.

POSThttps://CONNECT-DOMAIN/api/v2/customer/contacts/removal

Authorization

Body

contactsarray of deleteContact-requestv2 (object)

Response

Contacts found. The response includes a status report (SUCCESS, NOT_FOUND or FAILURE) of the connection removal for each advisor initially connected to each contact in the array of objects.

Body

reportarray of deleteContact-responsev2 (object)

Request

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

Response

{
  "report": [
    {
      "contact": {
        "advisorSymphonyId": 1234567890,
        "contactSymphonyId": 1234567890
      },
      "status": "FAILURE"
    }
  ]
}

PreviousPermissions NextContact status

Last updated 12 days ago