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)

post

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

1. To create a contact and eventually immediately associate one or more advisors.
2. To add more advisors to an existing contact.

In both cases, you must provide all the contact's mandatory fields listed as "body params".

Note

• If both advisorSymphonyId and advisorEmailAddresses are passed, the advisorSymphonyId will prevail.

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Body

application/json

firstNamestringRequiredExample: John

lastNamestringRequiredExample: Doe

companyNamestring · max: 100Optional

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

Example: Company

emailAddressstring · emailOptional

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

Example: [email protected]

phoneNumberstring · phoneRequiredExample: 911234567890

externalNetworkstringRequired

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

Example: WHATSAPP

advisorSymphonyIdsnumber[]Optional

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

Example: 14362370637825

preferredLanguagestringOptional

Contact preferred language code

Example: CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE (among others, see release note for more)

advisorEmailAddressesstring · email[]Optional

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.

Example: [email protected]

onboarderEmailAddressstringRequired

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

Example: [email protected]

createRoombooleanOptional

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.

Responses

200

Contact added successfully

application/json

firstNamestringOptionalExample: John

lastNamestringOptionalExample: Doe

companyNamestringOptionalExample: Company

emailAddressstringOptionalExample: [email protected]

phoneNumberstringOptionalExample: 911234567890

externalNetworkstringOptional

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

Example: WHATSAPP

symphonyIdstringOptionalExample: 12345678912365

statusstring · enumOptionalPossible values:

statusUpdateDatestring · date-timeOptionalExample: 1547661232368

preferredLanguagestringOptionalExample: CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE (among others, see release note for more)

invitationCodestringOptionalExample: AB12DE43

400

Missing or malformed input

application/json

401

Unauthorized

application/json

403

Onboard user forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

500

User creation failed

application/json

post

/api/v2/customer/contacts

HTTPcURLJavaScriptPython

POST /api/v2/customer/contacts HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 431

{
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "Company",
  "emailAddress": "[email protected]",
  "phoneNumber": 911234567890,
  "externalNetwork": "WHATSAPP",
  "advisorSymphonyIds": [
    14362370637825
  ],
  "preferredLanguage": "CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE (among others, see release note for more)",
  "advisorEmailAddresses": [
    "[email protected]"
  ],
  "onboarderEmailAddress": "[email protected]",
  "createRoom": true
}

{
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "Company",
  "emailAddress": "[email protected]",
  "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": "2026-03-23T19:29:47.038Z"
    }
  ]
}

Copy contact

Copy contact

post

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:

• A new account is created for the user, with a new Symphony user ID.
• There is no change in the user's data.
• The original user account is removed from all rooms and the new account is added to these rooms. Then, a system message is pushed to each room: Maintenance completed on account: {contact first name} {contact last name}. No action on your part is required.
• The email format of the user will appear differently in Content Export. Old format: {network}.{phone}@symphony.com. New format: {network}.{phone}.{tenantId}@symphony.com
• This API is only supported for WHATSAPP and SMS contacts.
• Users who are still part of Symphony IMs cannot be copied. IMs should be first removed from Federation Services.
• The copy action is not required for users onboarded by a single tenant before the 23.03 release, or for all users onboarded after 23.03 release.

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

contactSymphonyIdstringRequired

Contact's Symphony ID

Example: 1234567890Pattern: ^\d+$

Responses

200

Contact successfully copied

application/json

newSymphonyIdstringOptional

Symphony user ID of the account copy

Example: 12345678912365

migratedStreamIdsstring[]Optional

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

400

Missing or malformed input

application/json

403

Copy user forbidden

application/json

404

Contact not found

application/json

409

Conflict

application/json

500

Contact update failed

application/json

post

/api/v1/customer/contacts/{contactSymphonyId}/copy

HTTPcURLJavaScriptPython

POST /api/v1/customer/contacts/{contactSymphonyId}/copy HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Update contact

Update contact (recommended)

put

Update a contact's first name, last name, company name (maximum 100 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.

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

contactSymphonyIdstringRequired

Contact's Symphony user ID

Example: 1234567890

Body

application/json

firstNamestringRequiredExample: John

lastNamestringRequiredExample: DoeABC

companyNamestring · max: 100RequiredExample: Company

phoneNumberstring · phoneRequiredExample: 911234567890

emailAddressstringOptionalExample: [email protected]

advisorSymphonyIdstringRequiredExample: 1234567890Pattern: ^\d+$

preferredLanguagestringOptional

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

Example: CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE, etc.

Responses

200

Contact successfully updated

application/json

firstNamestringOptionalExample: John

lastNamestringOptionalExample: DoeABC

companyNamestringOptionalExample: Company

emailAddressstringOptionalExample: [email protected]

phoneNumberstringOptionalExample: 911234567890

symphonyIdstringOptional

Federated user Symphony id

Example: 12345678912365

advisorsstring[]Optional

Advisors Symphony IDs

Example: 14362370637825

preferredLanguagestringOptional

Contact preferred language

Example: CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE, etc.

400

Missing or malformed input

application/json

401

Unauthorized

application/json

403

Update user forbidden

application/json

404

Contact not found

application/json

409

Conflict

application/json

500

Contact update failed

application/json

put

/api/v2/customer/contacts/{contactSymphonyId}

HTTPcURLJavaScriptPython

PUT /api/v2/customer/contacts/{contactSymphonyId} HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "firstName": "John",
  "lastName": "DoeABC",
  "companyName": "Company",
  "phoneNumber": 911234567890,
  "emailAddress": "[email protected]",
  "advisorSymphonyId": 1234567890,
  "preferredLanguage": "CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE, etc."
}

{
  "firstName": "John",
  "lastName": "DoeABC",
  "companyName": "Company",
  "emailAddress": "[email protected]",
  "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

post

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.

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

contactSymphonyIdstring · numberRequired

Contact's Symphony user ID

Example: 1234567890

advisorSymphonyIdstring · numberRequired

Onboarder's Symphony user ID

Example: 1234567890

Responses

200

The invite has been resent successfully.

application/json

invitationCodestringOptionalExample: AB12DE43

400

Missing or malformed input

application/json

404

Not found

application/json

500

Failed

application/json

post

/api/v1/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId}/resendInvite

HTTPcURLJavaScriptPython

POST /api/v1/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId}/resendInvite HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "invitationCode": "AB12DE43"
}

Remove contact

Remove contact (recommended)

delete

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

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

advisorSymphonyIdstring · numberRequired

Advisor's Symphony user ID

Example: 1234567890

contactSymphonyIdstring · numberRequired

Contact's Symphony user ID

Example: 1234567890

Responses

204

Contact successfully removed

401

Unauthorized

application/json

404

Contact not found

application/json

delete

/api/v2/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId}

HTTPcURLJavaScriptPython

DELETE /api/v2/customer/contacts/{contactSymphonyId}/advisor/{advisorSymphonyId} HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Remove all contacts

Remove all contacts (recommended)

delete

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

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

advisorSymphonyIdstring · numberRequired

Advisor's Symphony user ID

Example: 1234567890

Responses

200

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

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

404

Advisor or contact not found

application/json

delete

/api/v2/customer/contacts/advisor/{advisorSymphonyId}

HTTPcURLJavaScriptPython

DELETE /api/v2/customer/contacts/advisor/{advisorSymphonyId} HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "report": [
    {
      "contact": {
        "advisorSymphonyId": 1234567890,
        "phoneNumber": "[phone]",
        "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)

delete

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

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

contactSymphonyIdstring · numberRequired

Contact's Symphony user ID

Example: 1234567890

Responses

200

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

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

404

Contact not found

application/json

delete

/api/v2/customer/contacts/{contactSymphonyId}

HTTPcURLJavaScriptPython

DELETE /api/v2/customer/contacts/{contactSymphonyId} HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Bulk remove advisor-contact connections

Bulk remove advisor-contact connection (recommended)

post

Remove specific advisor-contact connections in bulk.

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Body

application/json

Responses

200

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.

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

post

/api/v2/customer/contacts/removal

HTTPcURLJavaScriptPython

POST /api/v2/customer/contacts/removal HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "contacts": [
    {
      "advisorSymphonyId": 1234567890,
      "contactSymphonyId": 1234567890
    }
  ]
}

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