Phonebooks
Phonebooks are containers that hold an organisation's contacts. Typically you will create one phonebook per integration (e.g. CRM) to store Contacts for that integration against.
List shared phonebooks with contacts
List shared phonebooks and their contacts.
Not all contacts may be returned. The limit query parameter applies to the total number of contacts in the result set, not the number returned in each phonebook.
If excludeEmpty is set to true and the search parameter is not provided, only phonebooks with contacts are returned. By default, the excludeEmpty parameter is false and all phonebooks will be returned.
query Parameters
searchThe search term for filtering contacts. Must have at least 3 characters if provided.
limitThe maximum number of contacts to return. Default to 100, maximum is 1000
excludeEmptySet this value as true to exclude phonebooks that do not contain any contacts. Set it as false to get all phonebooks. Defaults to false. This parameter is ignored if the search parameter is provided.
Headers
AuthorizationAuthorization header bearing the access token
List shared phonebooks with contacts › Responses
Phonebooks and their contacts
The list of contacts belonging to the phonebook. May be empty if no matched contacts are found.
idID of the phonebook
managedBySpecifies whether the phonebook is managed by the phonebook owner or by the organisation via the Spoke API.
Possible values:
organisation: Contacts in the phonebook can only be managed by the organisation administrators via the Spoke API. For a personal phonebook, the owner of the phonebook will have read access to contacts but cannot update or delete any contacts.user: For phonebooks owned by a user only. Contacts in the phonebook can only be managed by the owner of the phonebook. Contacts will not be accessible via the Spoke API for Read, Update or Delete operations.
When accessed via the Spoke API, this value will always be organisation.
nameThe name of the phonebook
ownerId** DEPRECATED **. Refer to owner field instead.
uploadedUTC timestamp of the latest upload time
descriptionThe description of the phonebook
sourceIdID of the phonebook's source
Create phonebook with contacts
Create a new phonebook and populates it with the provided contacts.
Headers
AuthorizationAuthorization header bearing the access token
Create phonebook with contacts › Request Body optional
nameThe name of the phonebook
The list of contacts belonging to this phonebook
countryIsoCountry ISO code for formatting local phone numbers. Must be set if contacts are given
descriptionThe description of the phonebook
Create phonebook with contacts › Responses
Successfully created phonebook
idID of the phonebook
managedBySpecifies whether the phonebook is managed by the phonebook owner or by the organisation via the Spoke API.
Possible values:
organisation: Contacts in the phonebook can only be managed by the organisation administrators via the Spoke API. For a personal phonebook, the owner of the phonebook will have read access to contacts but cannot update or delete any contacts.user: For phonebooks owned by a user only. Contacts in the phonebook can only be managed by the owner of the phonebook. Contacts will not be accessible via the Spoke API for Read, Update or Delete operations.
When accessed via the Spoke API, this value will always be organisation.
nameThe name of the phonebook
ownerId** DEPRECATED **. Refer to owner field instead.
uploadedUTC timestamp of the latest upload time
descriptionThe description of the phonebook
sourceIdID of the phonebook's source
Get phonebook with contacts
Retrieve the phonebook and its contacts. For a large phonebook with number of contacts exceeding the limit, next contact ID is given for pagination.
If id is an email address of a user, then the user's personal phonebook will be retrieved.
path Parameters
idThe phonebook ID
query Parameters
Headers
AuthorizationAuthorization header bearing the access token
Get phonebook with contacts › Responses
Phonebook with contacts
The list of contacts belonging to the phonebook. May be empty if no matched contacts are found.
idID of the phonebook
managedBySpecifies whether the phonebook is managed by the phonebook owner or by the organisation via the Spoke API.
Possible values:
organisation: Contacts in the phonebook can only be managed by the organisation administrators via the Spoke API. For a personal phonebook, the owner of the phonebook will have read access to contacts but cannot update or delete any contacts.user: For phonebooks owned by a user only. Contacts in the phonebook can only be managed by the owner of the phonebook. Contacts will not be accessible via the Spoke API for Read, Update or Delete operations.
When accessed via the Spoke API, this value will always be organisation.
nameThe name of the phonebook
ownerId** DEPRECATED **. Refer to owner field instead.
uploadedUTC timestamp of the latest upload time
descriptionThe description of the phonebook
sourceIdID of the phonebook's source
Update phonebook and its contacts
Update an existing phonebook and replace its contacts with the provided contacts.
path Parameters
idThe phonebook ID
Headers
AuthorizationAuthorization header bearing the access token
Update phonebook and its contacts › Request Body optional
The list of contacts belonging to this phonebook
countryIsoCountry ISO code for formatting local phone numbers. Must be set if contacts are given
descriptionThe description of the phonebook
nameThe name of the phonebook
Update phonebook and its contacts › Responses
Successfully updated phonebook
idID of the phonebook
managedBySpecifies whether the phonebook is managed by the phonebook owner or by the organisation via the Spoke API.
Possible values:
organisation: Contacts in the phonebook can only be managed by the organisation administrators via the Spoke API. For a personal phonebook, the owner of the phonebook will have read access to contacts but cannot update or delete any contacts.user: For phonebooks owned by a user only. Contacts in the phonebook can only be managed by the owner of the phonebook. Contacts will not be accessible via the Spoke API for Read, Update or Delete operations.
When accessed via the Spoke API, this value will always be organisation.
nameThe name of the phonebook
ownerId** DEPRECATED **. Refer to owner field instead.
uploadedUTC timestamp of the latest upload time
descriptionThe description of the phonebook
sourceIdID of the phonebook's source
Delete phonebook and its contacts
Delete the specified phonebook and all of its contacts.
If id is an email address of a user, then the user's personal phonebook will be deleted.
path Parameters
idThe phonebook ID
Headers
AuthorizationAuthorization header bearing the access token
Delete phonebook and its contacts › Responses
Successfully deleted the phonebook
Create or update a personal phonebook with contacts
Create or update a personal phonebook. Personal phonebooks are owned by a user and are not shared with other users. If the user matching the email does not already have a personal phonebook, then it will be created.
path Parameters
The email of the user that the personal phonebook is owned by
Headers
AuthorizationAuthorization header bearing the access token
Create or update a personal phonebook with contacts › Request Body optional
The list of contacts belonging to this phonebook
countryIsoCountry ISO code for formatting local phone numbers. Must be set if contacts are given
descriptionThe description of the phonebook
nameThe name of the phonebook
Create or update a personal phonebook with contacts › Responses
Successfully updated phonebook
idID of the phonebook
managedBySpecifies whether the phonebook is managed by the phonebook owner or by the organisation via the Spoke API.
Possible values:
organisation: Contacts in the phonebook can only be managed by the organisation administrators via the Spoke API. For a personal phonebook, the owner of the phonebook will have read access to contacts but cannot update or delete any contacts.user: For phonebooks owned by a user only. Contacts in the phonebook can only be managed by the owner of the phonebook. Contacts will not be accessible via the Spoke API for Read, Update or Delete operations.
When accessed via the Spoke API, this value will always be organisation.
nameThe name of the phonebook
ownerId** DEPRECATED **. Refer to owner field instead.
uploadedUTC timestamp of the latest upload time
descriptionThe description of the phonebook
sourceIdID of the phonebook's source