ExternalContactsService

A list of all methods in the ExternalContactsService service. Click on the method name to view detailed information about that method.

Methods	Description
address_book_bulk_upload	Uploads multiple contacts for multiple extensions at once. Maximum 500 extensions can be uploaded per request. Max amount of contacts that can be uploaded per extension is 10,000. Each contact uploaded for a certain extension is not visible to other extensions.
get_address_book_bulk_upload_task	Returns the status of a task on adding multiple contacts to multiple extensions.
list_favorite_contacts	Returns the list of favorite contacts of the current extension. Favorite contacts include both company contacts (extensions) and personal contacts (address book records).
update_favorite_contact_list	Updates the list of favorite contacts of the current extension. Favorite contacts include both company contacts (extensions) and personal contacts (address book records).Please note: Currently personal address book size is limited to 10 000 contacts.
list_contacts	Returns the user personal contacts.
create_contact	Creates the user personal contact.
read_contact	Returns the user personal contact(s). Batch request syntax is supported.
update_contact	Updates the user personal contact(s) (full resource update). Batch request syntax is supported.
patch_contact	Updates particular values of a personal contact attributes specified in request (partial resource update). Omitted attributes will remain unchanged. If any attribute is passed in request body with the null value, then this attribute value will be removed.
delete_contact	Deletes the user personal contact(s). Batch request syntax is supported.
sync_address_book	Synchronizes user contacts.

address_book_bulk_upload

Uploads multiple contacts for multiple extensions at once. Maximum 500 extensions can be uploaded per request. Max amount of contacts that can be uploaded per extension is 10,000. Each contact uploaded for a certain extension is not visible to other extensions.

HTTP Method: POST
Endpoint: /restapi/v1.0/account/{accountId}/address-book-bulk-upload

Parameters

Name	Type	Required	Description
request_body	AddressBookBulkUploadRequest	✅	The request body.
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)

Return Type

AddressBookBulkUploadResponse

Example Usage Code Snippet

from ring_central import RingCentral, Environment
from ring_central.models import AddressBookBulkUploadRequest

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

request_body = AddressBookBulkUploadRequest(
    records=[
        {
            "extension_id": "extensionId",
            "contacts": [
                {
                    "email": "[email protected]",
                    "notes": "#1 Customer",
                    "company": "Example, Inc.",
                    "first_name": "Charlie",
                    "last_name": "Williams",
                    "job_title": "CEO",
                    "birthday": "birthday",
                    "web_page": "http://www.example.com",
                    "middle_name": "J",
                    "nick_name": "The Boss",
                    "email2": "[email protected]",
                    "email3": "[email protected]",
                    "home_phone": "+15551234567",
                    "home_phone2": "+15551234567",
                    "business_phone": "+15551234567",
                    "business_phone2": "+15551234567",
                    "mobile_phone": "+15551234567",
                    "business_fax": "+15551234567",
                    "company_phone": "+15551234567",
                    "assistant_phone": "+15551234567",
                    "car_phone": "+15551234567",
                    "other_phone": "+15551234567",
                    "other_fax": "+15551234567",
                    "callback_phone": "+15551234567",
                    "business_address": {
                        "country": "country",
                        "state": "state",
                        "city": "city",
                        "street": "street",
                        "zip": "zip"
                    },
                    "home_address": {
                        "country": "country",
                        "state": "state",
                        "city": "city",
                        "street": "street",
                        "zip": "zip"
                    },
                    "other_address": {
                        "country": "country",
                        "state": "state",
                        "city": "city",
                        "street": "street",
                        "zip": "zip"
                    }
                }
            ]
        }
    ]
)

result = sdk.external_contacts.address_book_bulk_upload(
    request_body=request_body,
    account_id="~"
)

print(result)

get_address_book_bulk_upload_task

Returns the status of a task on adding multiple contacts to multiple extensions.

HTTP Method: GET
Endpoint: /restapi/v1.0/account/{accountId}/address-book-bulk-upload/tasks/{taskId}

Parameters

Name	Type	Required	Description
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
task_id	str	✅	Internal identifier of a task

Return Type

AddressBookBulkUploadResponse

Example Usage Code Snippet

from ring_central import RingCentral, Environment

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

result = sdk.external_contacts.get_address_book_bulk_upload_task(
    account_id="~",
    task_id="taskId"
)

print(result)

list_favorite_contacts

Returns the list of favorite contacts of the current extension. Favorite contacts include both company contacts (extensions) and personal contacts (address book records).

HTTP Method: GET
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/favorite

Parameters

Name	Type	Required	Description
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)

Return Type

FavoriteContactList

Example Usage Code Snippet

from ring_central import RingCentral, Environment

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

result = sdk.external_contacts.list_favorite_contacts(
    account_id="~",
    extension_id="~"
)

print(result)

update_favorite_contact_list

Updates the list of favorite contacts of the current extension. Favorite contacts include both company contacts (extensions) and personal contacts (address book records).Please note: Currently personal address book size is limited to 10 000 contacts.

HTTP Method: PUT
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/favorite

Parameters

Name	Type	Required	Description
request_body	FavoriteCollection	✅	The request body.
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)

Return Type

FavoriteContactList

Example Usage Code Snippet

from ring_central import RingCentral, Environment
from ring_central.models import FavoriteCollection

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

request_body = FavoriteCollection(
    records=[
        {
            "id_": 10,
            "extension_id": "extensionId",
            "account_id": "accountId",
            "contact_id": "contactId"
        }
    ]
)

result = sdk.external_contacts.update_favorite_contact_list(
    request_body=request_body,
    account_id="~",
    extension_id="~"
)

print(result)

list_contacts

Returns the user personal contacts.

HTTP Method: GET
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact

Parameters

Name	Type	Required	Description
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
starts_with	str	❌	If specified, only contacts which 'First name' or 'Last name' start with the mentioned substring will be returned. Case-insensitive
sort_by	List[SortBy]	❌	Sorts results by the specified property
page	int	❌	The result set page number (1-indexed) to return
per_page	int	❌	The number of items per page. If provided value in the request is greater than a maximum, the maximum value is applied
phone_number	List[str]	❌	Phone number in e.164 format

Return Type

ContactList

Example Usage Code Snippet

from ring_central import RingCentral, Environment

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)
sort_by=[
    "FirstName"
]
phone_number=[
    "phoneNumber"
]

result = sdk.external_contacts.list_contacts(
    account_id="~",
    extension_id="~",
    starts_with="startsWith",
    sort_by=sort_by,
    page=1,
    per_page=100,
    phone_number=phone_number
)

print(result)

create_contact

Creates the user personal contact.

HTTP Method: POST
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact

Parameters

Name	Type	Required	Description
request_body	PersonalContactRequest	✅	The request body.
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
dialing_plan	str	❌	Country code value complying with the ISO 3166-1 alpha-2 format. The default value is home country of the current extension

Return Type

PersonalContactResource

Example Usage Code Snippet

from ring_central import RingCentral, Environment
from ring_central.models import PersonalContactRequest

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

request_body = PersonalContactRequest(
    first_name="Charlie",
    last_name="Williams",
    middle_name="J",
    nick_name="The Boss",
    company="Example, Inc.",
    job_title="CEO",
    email="[email protected]",
    email2="[email protected]",
    email3="[email protected]",
    birthday="birthday",
    web_page="http://www.example.com",
    notes="#1 Customer",
    home_phone="+15551234567",
    home_phone2="+15551234567",
    business_phone="+15551234567",
    business_phone2="+15551234567",
    mobile_phone="+15551234567",
    business_fax="+15551234567",
    company_phone="+15551234567",
    assistant_phone="+15551234567",
    car_phone="+15551234567",
    other_phone="+15551234567",
    other_fax="+15551234567",
    callback_phone="+15551234567",
    home_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    business_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    other_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    ringtone_index="ringtoneIndex"
)

result = sdk.external_contacts.create_contact(
    request_body=request_body,
    account_id="~",
    extension_id="~",
    dialing_plan="dialingPlan"
)

print(result)

read_contact

Returns the user personal contact(s). Batch request syntax is supported.

HTTP Method: GET
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact/{contactId}

Parameters

Name	Type	Required	Description
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
contact_id	List[int]	✅	The list of contact identifiers (comma-separated)

Return Type

PersonalContactResource

Example Usage Code Snippet

from ring_central import RingCentral, Environment

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)
contact_id=[
    3
]

result = sdk.external_contacts.read_contact(
    account_id="~",
    extension_id="~",
    contact_id=contact_id
)

print(result)

update_contact

Updates the user personal contact(s) (full resource update). Batch request syntax is supported.

HTTP Method: PUT
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact/{contactId}

Parameters

Name	Type	Required	Description
request_body	PersonalContactRequest	✅	The request body.
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
contact_id	List[int]	✅	The list of contact identifiers (comma-separated)
dialing_plan	str	❌	Country code value complying with the ISO 3166-1 alpha-2 format. The default value is home country of the current extension

Return Type

PersonalContactResource

Example Usage Code Snippet

from ring_central import RingCentral, Environment
from ring_central.models import PersonalContactRequest

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

request_body = PersonalContactRequest(
    first_name="Charlie",
    last_name="Williams",
    middle_name="J",
    nick_name="The Boss",
    company="Example, Inc.",
    job_title="CEO",
    email="[email protected]",
    email2="[email protected]",
    email3="[email protected]",
    birthday="birthday",
    web_page="http://www.example.com",
    notes="#1 Customer",
    home_phone="+15551234567",
    home_phone2="+15551234567",
    business_phone="+15551234567",
    business_phone2="+15551234567",
    mobile_phone="+15551234567",
    business_fax="+15551234567",
    company_phone="+15551234567",
    assistant_phone="+15551234567",
    car_phone="+15551234567",
    other_phone="+15551234567",
    other_fax="+15551234567",
    callback_phone="+15551234567",
    home_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    business_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    other_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    ringtone_index="ringtoneIndex"
)
contact_id=[
    7
]

result = sdk.external_contacts.update_contact(
    request_body=request_body,
    account_id="~",
    extension_id="~",
    contact_id=contact_id,
    dialing_plan="dialingPlan"
)

print(result)

patch_contact

Updates particular values of a personal contact attributes specified in request (partial resource update). Omitted attributes will remain unchanged. If any attribute is passed in request body with the null value, then this attribute value will be removed.

HTTP Method: PATCH
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact/{contactId}

Parameters

Name	Type	Required	Description
request_body	PersonalContactRequest	✅	The request body.
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
contact_id	int	✅	Internal identifier of a contact record in the RingCentral database
dialing_plan	str	❌	Country code value complying with the ISO 3166-1 alpha-2 format. The default value is home country of the current extension

Return Type

PersonalContactResource

Example Usage Code Snippet

from ring_central import RingCentral, Environment
from ring_central.models import PersonalContactRequest

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

request_body = PersonalContactRequest(
    first_name="Charlie",
    last_name="Williams",
    middle_name="J",
    nick_name="The Boss",
    company="Example, Inc.",
    job_title="CEO",
    email="[email protected]",
    email2="[email protected]",
    email3="[email protected]",
    birthday="birthday",
    web_page="http://www.example.com",
    notes="#1 Customer",
    home_phone="+15551234567",
    home_phone2="+15551234567",
    business_phone="+15551234567",
    business_phone2="+15551234567",
    mobile_phone="+15551234567",
    business_fax="+15551234567",
    company_phone="+15551234567",
    assistant_phone="+15551234567",
    car_phone="+15551234567",
    other_phone="+15551234567",
    other_fax="+15551234567",
    callback_phone="+15551234567",
    home_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    business_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    other_address={
        "street": "20 Davis Dr.",
        "city": "Belmont",
        "country": "country",
        "state": "CA",
        "zip": "94002"
    },
    ringtone_index="ringtoneIndex"
)

result = sdk.external_contacts.patch_contact(
    request_body=request_body,
    account_id="~",
    extension_id="~",
    contact_id=3,
    dialing_plan="dialingPlan"
)

print(result)

delete_contact

Deletes the user personal contact(s). Batch request syntax is supported.

HTTP Method: DELETE
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact/{contactId}

Parameters

Name	Type	Required	Description
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
contact_id	List[int]	✅	The list of contact identifiers (comma-separated)

Example Usage Code Snippet

from ring_central import RingCentral, Environment

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)
contact_id=[
    8
]

result = sdk.external_contacts.delete_contact(
    account_id="~",
    extension_id="~",
    contact_id=contact_id
)

print(result)

sync_address_book

Synchronizes user contacts.

HTTP Method: GET
Endpoint: /restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book-sync

Parameters

Name	Type	Required	Description
account_id	str	✅	Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)
extension_id	str	✅	Internal identifier of the RingCentral extension/user (can be set to "~" to indicate that the extension associated with current authorization session should be used)
sync_type	SyncAddressBookSyncType	❌	Type of synchronization
sync_token	str	❌	Value of syncToken property of the last sync request response
per_page	int	❌	Number of records per page to be returned. Max number of records is 250, which is also the default. For 'FSync' - if the number of records exceeds the parameter value (either specified or default), all of the pages can be retrieved in several requests. For 'ISync' - if the number of records exceeds page size, then the number of incoming changes to this number is limited
page_id	int	❌	Internal identifier of a page. It can be obtained from the 'nextPageId' parameter passed in response body

Return Type

AddressBookSync

Example Usage Code Snippet

from ring_central import RingCentral, Environment
from ring_central.models import SyncAddressBookSyncType

sdk = RingCentral(
    access_token="YOUR_ACCESS_TOKEN",
    base_url=Environment.DEFAULT.value
)

result = sdk.external_contacts.sync_address_book(
    account_id="~",
    extension_id="~",
    sync_type="FSync",
    sync_token="syncToken",
    per_page=2,
    page_id=4
)

print(result)

Build Your Own SDKs with liblab

Build developer friendly SDKs in minutes from your APIs

Start for Free →

address_book_bulk_upload​

get_address_book_bulk_upload_task​

list_favorite_contacts​

update_favorite_contact_list​

list_contacts​

create_contact​

read_contact​

update_contact​

patch_contact​

delete_contact​

sync_address_book​

Build Your Own SDKs with liblab

address_book_bulk_upload

get_address_book_bulk_upload_task

list_favorite_contacts

update_favorite_contact_list

list_contacts

create_contact

read_contact

update_contact

patch_contact

delete_contact

sync_address_book