Introduction to the Custom Fields API

Last updated: 2020-03-29 Contributors Byrne Reese

What are custom fields?

A custom field is an additional piece of information or metadata that can be associated with a RingCentral user (a.k.a. an extension). A maximum of 5 custom fields can be created and associated with a user. In order to use custom fields, an admin must first be enable them for your account.

How can custom fields be used?

Custom fields can be used any time you need to extend the user object to store additional data relating to a user. Here are some specific use cases you may consider:

  • Advanced search. Custom field data is searchable, so it could be a useful way to enable search to find users by their employee Id, or other information unique to your enterprise.
  • Ad tracking. Track and manage marketing campaigns by assigning campaign IDs to user records, and then track calls received per campaign.
  • Organization. Group users based on custom categories.

What is the Custom Fields API?

The Custom Fields API is a REST-based interface that enables developers to create, update, delete and fetch custom fields programatically.

Explore Custom Fields API sample code

Create custom fields on User Extension

Developers can use this API to create a custom field on a user extension object. Maximum of 5 custom fields can be created.

POST /restapi/v1.0/account/{accountId}/custom-fields HTTP/1.1
Content-Type: application/json
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
Authorization: <YOUR_ACCESS_TOKEN>

{  
   "category": "User",
   "displayName": "HRCODE-TEST3"
}
from ringcentral import SDK
from ringcentral.http.api_exception import ApiException

sdk = SDK(APP_KEY, APP_SECRET, SERVER)
platform = sdk.platform()
platform.login(USERNAME, EXTENSION, PASSWORD)

body ={
    "category": "User",
    "displayName": "HRCODE-TEST3"
    }

try:
    response =  platform.post('/account/~/custom-fields', body)
    print("Custom Field Created")
except ApiException as e:
    print("Error while creating custom fields" + e)

Fetch Custom fields

Developers can use this API to fetch all the custom fields created on a RingCentral Account.

GET /restapi/v1.0/account/{accountId}/custom-fields HTTP/1.1
Authorization: <YOUR_ACCESS_TOKEN>
from ringcentral import SDK
from ringcentral.http.api_exception import ApiException

sdk = SDK(APP_KEY, APP_SECRET, SERVER)
platform = sdk.platform()
platform.login(USERNAME, EXTENSION, PASSWORD)

response = platform.get('/account/~/custom-fields')
custom_fields = response.json()
try:
    for x in range(len(custom_fields.records)):
        print('Display Name- ' + custom_fields.records[x].displayName + ' id- ' +custom_fields.records[x].id + ' Category- '+custom_fields.records[x].category + '\n' )
    except ApiException as e:
        print("Error while fetching custom fields" + e)

Update Custom fields

Developers can use this API to rename an existing custom field by specifying the custom field id in the query path parameter.

PUT /restapi/v1.0/account/{accountId}/custom-fields/2200033 HTTP/1.1
Authorization: <YOUR_ACCESS_TOKEN>
from ringcentral import SDK
from ringcentral.http.api_exception import ApiException

sdk = SDK(APP_KEY, APP_SECRET, SERVER)
platform = sdk.platform()
platform.login(USERNAME, EXTENSION, PASSWORD)

body ={
    "displayName": "HRCODE"
    }

try:
    response =  platform.put('/account/~/custom-fields/{}'.format(id), body)
    print(response.json().displayName)
except ApiException as e:
    print("Error while creating custom fields" + e)

Delete Custom fields

Developers can delete one or more existing custom field by passing the custom field id in the query parameter (separate by comma in case of multiple custom fields)

DELETE /restapi/v1.0/account/{accountId}/custom-fields/2200033,2200589 HTTP/1.1
Authorization: <YOUR_ACCESS_TOKEN>
from ringcentral import SDK
from ringcentral.http.api_exception import ApiException

sdk = SDK(APP_KEY, APP_SECRET, SERVER)
platform = sdk.platform()
platform.login(USERNAME, EXTENSION, PASSWORD)

try:
    response =  platform.delete('/account/~/custom-fields/{}'.format(id))
    print("Deleted")
    print("Custom Field Deleted")
except ApiException as e:
    print("Error while creating custom fields" + e)