Skip to main content

CONTACT API Reference

Module Information​

Service Files:

  • Private: service/private/contact.js
  • Public: service/contact.js

Available Services: 43 Documented Services: 23


contact.invite​

Send a contact invitation by email. Creates a contact entry and dispatches an invitation email. For non-Drumee users, sends a signup link. For registered Drumee users on different domains, sends a notification email. Same-domain colleagues on a Paid plan cannot be invited as they are automatically in contacts.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.invite

Parameters​

ParameterTypeRequiredDefaultDescription
emailstringYes-Email address of the person to invite
messagestringNo-Optional personal message to include in the invitation email
firstnamestringNo-First name of the invitee
lastnamestringNo-Last name of the invitee
surnamestringNo-Middle or additional name of the invitee

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
INVALID_DATA400The email address format is invalid
ALREADY_IN_CONTACT409This email is already an active contact in your list
INVITE_RECEIVED409You already have a pending invitation from this person
SAME_DOMAIN400Cannot invite a colleague from the same paid-plan domain; they are automatically in your contacts

contact.invite_accept​

Accept a pending contact invitation from another Drumee user. Creates a bidirectional contact connection, initiates a welcome chat exchange via handshake, logs the accept activity, and notifies the inviting party via WebSocket.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.invite_accept

Parameters​

ParameterTypeRequiredDefaultDescription
emailstringYes-Email address of the Drumee user whose invitation you are accepting

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
NOT_A_DRUMATE404The email address does not belong to a registered Drumee user
NO_INVITE404No pending invitation found from this user

contact.invite_refuse​

Refuse a pending contact invitation from another Drumee user. Updates the invitation status, logs the refuse activity, and notifies the inviting party via WebSocket.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.invite_refuse

Parameters​

ParameterTypeRequiredDefaultDescription
emailstringYes-Email address of the Drumee user whose invitation to refuse

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
NOT_A_DRUMATE404The email address does not belong to a registered Drumee user
NO_INVITE404No pending invitation found from this user

contact.add​

Manually add a new contact by Drumee user ID or by email address list. These two inputs are mutually exclusive. Optionally sends an invitation email by setting invite=1.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.add

Parameters​

ParameterTypeRequiredDefaultDescription
invitee_idstringNo-Drumee user ID of the contact to add. Mutually exclusive with email array.
emailarrayNo-Array of email objects: [{ email, is_default, category }]. Required if invitee_id is not provided. One entry must have is_default=1.
firstnamestringNo-Contact's first name
lastnamestringNo-Contact's last name
surnamestringNo-Contact's middle or additional name
mobilearrayNo-Array of phone objects: [{ phone, areacode, category, is_default }]
addressarrayNo-Array of address objects: [{ street, city, country, category, is_default }]
tagarrayNo-Array of tag identifiers to assign to this contact
commentstringNo-Internal comment or note about this contact
messagestringNo-Personal message included in invitation email when invite=1
invitestringNo"0"Set to '1' to send an invitation email to the contact

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
INVALID_DATA400Provide either invitee_id or email array, but not both (or neither)
INVALID_INVITEE_ID404The provided invitee_id does not match any registered Drumee user
SAME_DOMAIN400Cannot add a colleague from the same paid-plan domain as an external contact
MANY_DEFAULT_EMAIL400Only one email address can be designated as default (is_default=1)
NO_DEFAULT_MAIL400At least one email address must be designated as default
ALREADY_IN_CONTACT409This contact already exists in your contact list
SELF_CONTACT400You cannot add yourself as a contact
EMAIL_NOT_SENT207Contact was created successfully but the invitation email failed to send

contact.update​

Update an existing contact's information including name, email addresses, phone numbers, addresses, and tags. All sub-arrays are fully replaced on update (not merged). Optionally re-sends or initiates an invitation via invite=1.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.update

Parameters​

ParameterTypeRequiredDefaultDescription
contact_idstringYes-ID of the contact to update
firstnamestringNo-Updated first name. Required when the contact is linked to a Drumee user (uid is set).
lastnamestringNo-Updated last name. Required when the contact is linked to a Drumee user (uid is set).
surnamestringNo-Updated middle or additional name
emailarrayNo-Replacement email list: [{ email, is_default, category }]. Fully replaces existing emails.
mobilearrayNo-Replacement phone list: [{ phone, areacode, category, is_default }]. Fully replaces existing phones.
addressarrayNo-Replacement address list: [{ street, city, country, category, is_default }]. Fully replaces existing addresses.
tagarrayNo-Replacement tag list. Fully replaces existing tags.
commentstringNo-Updated internal comment
messagestringNo-Message for invitation email (used when invite=1)
invitestringNo"0"Set to '1' to send or re-send an invitation email

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
CONACT_NOT_EXIST404No contact found with the given contact_id
EMPTY_FIRSTNAME400First name is required when updating a contact linked to a Drumee user
EMPTY_LASTNAME400Last name is required when updating a contact linked to a Drumee user
MANY_DEFAULT_EMAIL400Only one email address can be designated as default (is_default=1)
NO_DEFAULT_MAIL400A default email address is required when is_need_email is set on this contact
ALREADY_IN_CONTACT409The new email/entity is already used by another contact in your list
SAME_DOMAIN400Cannot assign a same-domain colleague as an external contact
SELF_CONTACT400You cannot set yourself as a contact
EMAIL_NOT_SENT207Contact was updated successfully but the invitation email failed to send

contact.show_contact​

List the current user's contacts with optional filtering by tag, name, and status. Free users (domain_id=1) see only their personal contact table. Paid users (domain_id>1) see personal contacts only; same-domain colleagues are available via my_contacts.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.show_contact

Parameters​

ParameterTypeRequiredDefaultDescription
tag_idstringNo-Filter contacts belonging to a specific tag ID. Pass empty string to show all tags.
namestringNo-Search keyword to filter contacts by name (partial match)
orderstringNo"asc"Sort direction: 'asc' or 'desc'
pagenumberNo1Page number for pagination
optionstringNo"active"Filter by contact status: 'active', 'archived', or 'all'

Returns​

FieldTypeDescription
typeany-
docany-
itemsany-

Possible Errors​

Error codes not documented


contact.my_contacts​

Search and filter the current user's contacts. Free users (domain_id=1) see only their personal contact table. Paid users (domain_id>1) see personal contacts UNION colleagues from the same domain. Returns an empty array when the search key is empty.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.my_contacts

Parameters​

ParameterTypeRequiredDefaultDescription
valuestringNo""Search keyword to filter by name or email. Returns empty array if omitted or blank.
pagenumberNo1Page number for pagination
only_drumatenumberNo0Set to 1 to return only contacts who are registered Drumee users
filterarrayNo-Array of additional filter criteria
statusstringNo""Filter by contact status (active, archived, etc.)

Returns​

FieldTypeDescription
typeany-
docany-
itemsany-

Possible Errors​

Error codes not documented


contact.email_in_use​

Check whether an email is already referenced by any of the caller's contacts — as the contact's entity (default identifier) or in their contact_email rows. Pass contact_id when editing to exclude that contact from the check.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.email_in_use

Parameters​

ParameterTypeRequiredDefaultDescription
emailstringYes-Email address to check
contact_idstringNo-Contact ID to exclude (the one being edited)

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.get_contact​

Retrieve full details of a specific contact including all associated email addresses, phone numbers, postal addresses, and tags.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.get_contact

Parameters​

ParameterTypeRequiredDefaultDescription
contact_idstringYes-ID of the contact to retrieve

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.delete_contact​

Permanently delete a contact from the current user's contact list. Sends a real-time WebSocket notification to both the owner and the contact (if they are a Drumee user).

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.delete_contact

Parameters​

ParameterTypeRequiredDefaultDescription
contact_idstringYes-ID of the contact to permanently delete

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.search​

Search for Drumee users across the platform by keyword within the current domain. Intended for discovering potential contacts to add. Returns an empty array if the search key is blank.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.search

Parameters​

ParameterTypeRequiredDefaultDescription
keystringNo-Search keyword (name or email). Returns empty array if omitted.
stringstringNo-Alternative parameter name for key
pagenumberNo1Page number for pagination

Returns​

FieldTypeDescription
typeany-
docany-
itemsany-

Possible Errors​

Error codes not documented


contact.invite_get​

Retrieve the list of pending contact invitations received by the current user. Used to display the invitation inbox.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.invite_get

Parameters​

No parameters

Returns​

FieldTypeDescription
typeany-
docany-
itemsany-

Possible Errors​

Error codes not documented


contact.invite_count​

Get the count of pending contact invitations received by the current user. Used to display notification badges in the UI.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.invite_count

Parameters​

No parameters

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.accept_informed​

Acknowledge that the current user has been notified that their sent invitation was accepted by the recipient. Transitions the contact status from 'informed' to 'active' on the sender's side and sends a WebSocket update.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.accept_informed

Parameters​

ParameterTypeRequiredDefaultDescription
emailstringYes-Email address of the Drumee user who accepted your invitation

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
NOT_A_DRUMATE404The email address does not belong to a registered Drumee user
NO_INVITE404No informed-status invitation found for this user

contact.block​

Block a contact to prevent further interaction. Updates the contact relationship record for both parties and sends real-time WebSocket notifications.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.block

Parameters​

ParameterTypeRequiredDefaultDescription
contact_idstringYes-ID of the contact to block

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.unblock​

Unblock a previously blocked contact, restoring the contact relationship. Sends real-time WebSocket notifications to both parties.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.unblock

Parameters​

ParameterTypeRequiredDefaultDescription
contact_idstringYes-ID of the contact to unblock

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.change_status​

Change the status of a contact to 'active' (restore) or 'archived' (soft-archive without deletion). Sends a real-time WebSocket update to the current user's sessions.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.change_status

Parameters​

ParameterTypeRequiredDefaultDescription
contact_idstringYes-ID of the contact whose status to change
statusstringYes-New status value. Allowed values: 'active', 'archived'

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
INVALID_STATUS0400Status must be either 'active' or 'archived'
CONACT_NOT_EXIST404No contact found with the given contact_id

contact.join​

Join a contact network via an invitation token received in an invitation email. Validates the token, creates the contact relationship, and returns the newly created contact record.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.join

Parameters​

ParameterTypeRequiredDefaultDescription
tokenstringYes-Invitation token received in the invitation email link

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
INVALID_TOKEN400The provided invitation token is invalid or does not exist
EXPIRIED_TOKEN410The invitation token has expired and is no longer active

contact.summary​

Get a contact summary for a hub node. Returns the count of active contacts and the timestamp of the most recent contact modification. Requires owner-level access to the specified node.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.summary

Parameters​

ParameterTypeRequiredDefaultDescription
hub_idstringYes-Hub ID containing the target node
nidstringYes-Node ID to retrieve the contact summary for

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
FOLDER_NOT_FOUND404The specified node does not exist in this hub
PERMISSION_DENIED403Only the node owner can retrieve the contact summary

contact.google_auth​

Initiate the Google OAuth authorization flow to import contacts from Google Contacts. Returns a Google authorization URL that the user must visit to grant read-only access to their Google Contacts.

PropertyValue
ScopeHub (requires hub context)
PermissionAnonymous (1)

Endpoint:

https://hostname/-/svc/contact.google_auth

Parameters​

No parameters

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.invitation_status​

Check the status of a contact invitation using its token. Public endpoint (no authentication required) used to display the invitation landing page before the recipient logs in.

PropertyValue
ScopeHub (requires hub context)
PermissionAnonymous (1)

Endpoint:

https://hostname/-/svc/contact.invitation_status

Parameters​

ParameterTypeRequiredDefaultDescription
tokenstringYes-Invitation token from the invitation email URL
uidstringNo-Optional Drumee user ID to provide additional context about the recipient

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error codes not documented


contact.load​

Import contacts from an uploaded CSV or VCF (vCard) file. Processes the file and reports real-time import progress via WebSocket using socket_id. Each entry requires at least one email address. Supports .csv and .vcf formats.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.load

Parameters​

ParameterTypeRequiredDefaultDescription
socket_idstringYes-WebSocket session ID for streaming real-time progress updates during import
uploaded_idstringNo-ID of the file from an upload operation. Mutually exclusive with secret.
secretstringNo-Legacy file ID. Mutually exclusive with uploaded_id.
servicestringNo-Optional service tag used in WebSocket progress messages

Returns​

FieldTypeDescription
typeany-
docany-
propertiesany-

Possible Errors​

Error CodeHTTP StatusDescription
NO_FILE400No file ID was provided; either uploaded_id or secret is required
INVALID_INPUT400Both uploaded_id and secret were provided; only one is allowed at a time
WRONG_FORMAT415The uploaded file is not a supported format; only .csv and .vcf are accepted

contact.connection_status​

Retrieve the current online/offline presence state of all contacts. Used to display real-time presence indicators in the contact list.

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.connection_status

Parameters​

No parameters

Returns​

FieldTypeDescription
typeany-
docany-
itemsany-

Possible Errors​

Error codes not documented


contact.add_to_group​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.add_to_group

contact.create_group​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.create_group

contact.delete​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.delete

contact.delete_contact_address​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.delete_contact_address

contact.delete_contact_email​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.delete_contact_email

contact.delete_contact_phone​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.delete_contact_phone

contact.delete_group​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.delete_group

contact.export_all​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.export_all

contact.get​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.get

contact.get_group_avatar​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.get_group_avatar

contact.import​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.import

contact.invite_drumate​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.invite_drumate

contact.remove_from_group​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.remove_from_group

contact.search_drumee_contacts​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.search_drumee_contacts

contact.search_my_contacts​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.search_my_contacts

contact.set_group_avatar​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.set_group_avatar

contact.show​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.show

contact.show_gmail_contacts​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.show_gmail_contacts

contact.show_groups​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.show_groups

contact.show_members​

No description provided

PropertyValue
ScopeHub (requires hub context)
PermissionOwner (32)

Endpoint:

https://hostname/-/svc/contact.show_members