Jump to: navigation, search

Get contacts

This operation is part of the Contacts API section of the Web Services API.

Overview

Retrieves a list of contacts. The contacts resources supports queries with filtering (see Parameters below) and pagination.

Request URL /api/v2/contacts
HTTP Method GET
Required Features

Parameters

Parameter Type Description
name Comma-separated list of names Retrieves all contacts whose name exactly matches any of the names specified in the comma-separated list. The "name" parameter corresponds to the "username" for User contacts, and the "name" for Queue and Custom contacts.
phoneNumber Comma-separated list of phone numbers Retrieves all contacts whose phone number exactly matches any of the phone numbers specified in the comma-separated list. The "phone number" parameter corresponds to the number of any devices associated with the User contact, or the "phoneNumber" for the Queue or Custom contacts. When indexing, Web Services removes all non-alphanumeric symbols from phone numbers, so "phoneNumber" values should not contain any non-digits, except in the the special value '*', which is supported for backwards compatibility. If you specify '*', contacts with any phone number assigned to them are searched.
channel Comma-separated list of channels Retrieves contacts whose channel exactly matches any of the channels specified in the comma-separated list.
type Type of contact Retrieves contacts with the specified type: User, Queue or Custom.
filterName String The name of a custom filter.

NamesOrPhoneNumberMatches — For each argument passed in filterParameters, contacts are searched with fields matching the passed parameter (case-insensitive string matching with wildcard * are supported). The following fields are checked using the OR rule:

  • User: firstName, lastName, userName, number of assigned devices
  • Queue: name, phoneNumber
  • Custom: name, phoneNumber

For a contact to match the query, the contact must satisfy the above rule for EACH argument passed in filterParameters (AND rule).

Important
Web Services currently supports the sortBy field only for "name".
filterParameters Comma-separated list of strings The parameters to be passed to filter specified in filterName.
includeBusinessUnits Comma-separated list of URL-encoded business unit names. Wildcard (*) is supported. Retrieves objects that belong to at least one of the business units included in the list.
excludeBusinessUnits Comma-separated list of URL-encoded business unit names. Wildcard (*) is supported. Retrieves objects that do not belong to any of the business units in the list.

Note: This overrides includeBusinessUnits where there is an overlap.

includeUsersInBusinessUnits Comma-separated list of URL-encoded business unit names. Wildcard (*) is supported. Retrieves agents who belong to at least one of the business units included in the list.
excludeUsersInBusinessUnits Comma-separated list of URL-encoded business unit names. Wildcard (*) is supported. Retrieves agents who do not belong to any of the business units in the list.

Note: This overrides includeUsersInBusinessUnits where there is an overlap. For example, if an agent belongs to groups A and B, and excludeUsersInBusinessUnits specifies "B" while includeUsersInBusinessUnits specifies "A", the agent is excluded from the returned list.

includeBusinessUnitsExactMatch Comma-separated list of URL-encoded business unit names Retrieves objects that exactly matches at least one of the business units included in the list.
excludeBusinessUnitsExactMatch Comma-separated list of URL-encoded business unit names Retrieves objects that do not belong to any of the business units in the list.

Note:: This overrides includeBusinessUnitsExactMatch where there is an overlap.

includeVirtualAgentGroupsExactMatch Comma-separated list of URL-encoded virtual agent group names Retrieves objects that exactly matches at least one of the virtual agent groups included in the list.
excludeVirtualAgentGroupsExactMatch Comma-separated list of URL-encoded virtual agent group names Retrieves objects that do not belong to any of the virtual agent groups in the list.
availability.channels.<channel_name> Boolean Retrieves contacts based on their availability on the specified channel. For example, if you submit availability.channels.voice=true, the response contains only those users who are available on the voice channel. If a channel is not available due to feature restrictions, Web Services ignores the corresponding filter.
roles Comma-separated list of user roles Retrieves all contacts of type User who have at least one of the specified roles. The possible role values are ROLE_ADMIN, ROLE_AGENT, ROLE_SUPERVISOR, and ROLE_APIUSER.

Samples

Using the NamesOrPhoneNumberMatches filter

Request

GET /api/v2/contacts?limit=100&filterName=NamesOrPhoneNumberMatches&filterParameters=*ob*&sortBy=name&order=Ascending

HTTP Response

{  
   "statusCode":0,
   "totalCount":3,
   "contacts":[  
      {  
         "id":"65543402f8a4429ab74559dd2cde999f",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/65543402f8a4429ab74559dd2cde999f",
         "name":"Bob.Fitz@Genesys.com",
         "type":"User",
         "userName":"Bob.Fitz@Genesys.com",
         "firstName":"Bob",
         "lastName":"Fitz",
         "employeeId":"Bob.Fitz@Genesys.com"
      },
      {  
         "id":"a1a16d4985894c3897ba6ad424a93b6e",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/a1a16d4985894c3897ba6ad424a93b6e",
         "name":"Bobba.Fett@GenesysLab.com",
         "type":"User",
         "userName":"Bobba.Fett@GenesysLab.com",
         "firstName":"Bobba",
         "lastName":"Fett",
         "employeeId":"Bobba.Fett@GenesysLab.com"
      },
      {  
         "id":"8e41fc673289420fab522724f62cb0f4",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/8e41fc673289420fab522724f62cb0f4",
         "name":"Robert.Lab@genesys.com",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"+16501234567",
               "description":""
            }
         ],
         "userName":"Robert.Lab@genesys.com",
         "firstName":"Robert",
         "lastName":"Lab",
         "employeeId":"Robert.Lab@genesys.com"
      }
   ]
}

Using the includeUsersInBusinessUnits and excludeUsersInBusinessUnits filters

If you need to limit the visibility of agents by agent group, you can use the includeUsersInBusinessUnits and excludeUsersInBusinessUnits filters. For example, you might want agents in the Support agent group to only see other agents in Support as valid contacts, and not agents in the Sales agent group.

For example, consider the following deployment:

  • Agent Group 1: User A, User B
  • Agent Group 2: User C, User X
  • Internal: User X

Using the includeUsersInBusinessUnits filter, you can get only users in Agent Group 1:

Request

GET /api/v2/contacts?includeUsersInBusinessUnits=Agent%20Group%201

HTTP Response

{  
   "statusCode":0,
   "totalCount":2,
   "contacts":[  
      {  
         "id":"65543402f8a4429ab74559dd2cde999f",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/65543402f8a4429ab74559dd2cde999f",
         "name":"User A",
         "type":"User",
         "userName":"Bob.Fitz@Genesys.com",
         "firstName":"Bob",
         "lastName":"Fitz",
         "employeeId":"Bob.Fitz@Genesys.com",
         "businessUnits":[  
            {  
               "name":"Agent Group 1"
            }
         ]
      },
      {  
         "id":"a1a16d4985894c3897ba6ad424a93b6e",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/a1a16d4985894c3897ba6ad424a93b6e",
         "name":"User B",
         "type":"User",
         "userName":"Bobba.Fett@GenesysLab.com",
         "firstName":"Bobba",
         "lastName":"Fett",
         "employeeId":"Bobba.Fett@GenesysLab.com",
         "businessUnits":[  
            {  
               "name":"Agent Group 1"
            }
         ]
      }
   ]
}

Using the excludeUsersInBusinessUnits filter, you can get all users except those in the Internal group.

Request

GET /api/v2/contacts?excludeUsersInBusinessUnits=Internal

HTTP Response

{  
   "statusCode":0,
   "totalCount":3,
   "contacts":[  
      {  
         "id":"65543402f8a4429ab74559dd2cde999f",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/65543402f8a4429ab74559dd2cde999f",
         "name":"User A",
         "type":"User",
         "userName":"Bob.Fitz@Genesys.com",
         "firstName":"Bob",
         "lastName":"Fitz",
         "employeeId":"Bob.Fitz@Genesys.com",
         "businessUnits":[  
            {  
               "name":"Agent Group 1"
            }
         ]
      },
      {  
         "id":"a1a16d4985894c3897ba6ad424a93b6e",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/a1a16d4985894c3897ba6ad424a93b6e",
         "name":"User B",
         "type":"User",
         "userName":"Bobba.Fett@GenesysLab.com",
         "firstName":"Bobba",
         "lastName":"Fett",
         "employeeId":"Bobba.Fett@GenesysLab.com",
         "businessUnits":[  
            {  
               "name":"Agent Group 1"
            }
         ]
      },
      {  
         "id":"8e41fc673289420fab522724f62cb0f4",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/8e41fc673289420fab522724f62cb0f4",
         "name":"User C",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"+16501234567",
               "description":""
            }
         ],
         "userName":"Robert.Lab@genesys.com",
         "firstName":"Robert",
         "lastName":"Lab",
         "employeeId":"Robert.Lab@genesys.com",
         "businessUnits":[  
            {  
               "name":"Agent Group 2"
            }
         ]
      }
   ]
}

Using both the includeUsersInBusinessUnits and excludeUsersInBusinessUnits filters together, you can get all users who are in Agent Group 2 but not in the Internal group.

Request

GET /api/v2/contacts?includeUsersInBusinessUnits=Agent%20Group%202&excludeUsersInBusinessUnits=Internal

HTTP Response

{  
   "statusCode":0,
   "totalCount":1,
   "contacts":[  
      {  
         "id":"8e41fc673289420fab522724f62cb0f4",
         "uri":"http://127.0.0.1:8080/api/v2/contacts/8e41fc673289420fab522724f62cb0f4",
         "name":"User C",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"+16501234567",
               "description":""
            }
         ],
         "userName":"Robert.Lab@genesys.com",
         "firstName":"Robert",
         "lastName":"Lab",
         "employeeId":"Robert.Lab@genesys.com",
         "businessUnits":[  
            {  
               "name":"Agent Group 2"
            }
         ]
      }
   ]
}

Using the includeBusinessUnits filter with a * wildcard, you can get a list of all business units that match the filter.

Request

GET http://localhost:8080/api/v2/contacts?type=BusinessUnit&includeBusinessUnits=*Group*

HTTP Response

{
 "statusCode": 0,
 "totalCount": 2,
 "contacts": [
 {
 "id": "2-731fd0f2-ea61-4985-85e6-86a211e26c31",
 "name": "Agent Group 1",
 "type": "BusinessUnit",
 "uri": "http://localhost:8080/api/v2/objects/2-731fd0f2-ea61-4985-85e6-86a211e26c31",
 "path": "/objects/2-731fd0f2-ea61-4985-85e6-86a211e26c31"
 },
 {
 "id": "2-731fd0f2-ea61-4985-85e6-86a211e26c32",
 "name": "Agent Group 2",
 "type": "BusinessUnit",
 "uri": "http://localhost:8080/api/v2/objects/2-731fd0f2-ea61-4985-85e6-86a211e26c32",
 "path": "/objects/2-731fd0f2-ea61-4985-85e6-86a211e26c32"
 }
 ]
}

Using the includeBusinessUnitsExactMatch or the excludeBusinessUnitsExactMatch filter, you can get a list of all business units that either match or do not match the filter.

Request

GET api/v2/contacts?type=BusinessUnit&excludeBusinessUnitsExactMatch=Agent%20Group%201

HTTP Response

{ 
  "statusCode": 0, 
  "totalCount": 1, 
  "contacts": [ 
    { 
      "id": "2-731fd0f2-ea61-4985-85e6-86a211e26c31", 
      name": "Agent Group 2", 
      "type": "BusinessUnit", 
      "uri": "http://localhost:8080/api/v2/objects/2-731fd0f2-ea61-4985-85e6-86a211e26c31", 
      "path": "/objects/2-731fd0f2-ea61-4985-85e6-86a211e26c31" 
    } 
    ] 
}


Using the roles filter

Request

GET /api/v2/contacts?roles=ROLE_AGENT

HTTP Response

{  
   "statusCode":0,
   "totalCount":4,
   "contacts":[  
      {  
         "id":"754e11130cde4c51b8de389e3a615920",
         "name":"JoshW",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"15002",
               "description":""
            }
         ],
         "userName":"JoshW",
         "firstName":"Josh",
         "lastName":"Williams",
         "employeeId":"dU4REwzeTFG43jieOmFZIA==.acme",
         "emailAddress":"",
         "businessUnits":[  

         ],
         "roles":[  
            "ROLE_AGENT"
         ],
         "uri":"http://dev-ip9-187.gws.genesys.com:8090/api/v2/contacts/754e11130cde4c51b8de389e3a615920",
         "path":"/contacts/754e11130cde4c51b8de389e3a615920"
      },
      {  
         "id":"844b7a0e30ce46a5b364797a39f8a81f",
         "name":"WillardC",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"15000",
               "description":""
            }
         ],
         "userName":"WillardC",
         "firstName":"Willard",
         "lastName":"Clinton",
         "employeeId":"hEt6DjDORqWzZHl6OfioHw==.acme",
         "emailAddress":"",
         "availability":{  
            "channels":[  
               {  
                  "channel":"voice",
                  "available":true,
                  "phoneNumber":"15000",
                  "userActivity":"Idle",
                  "userState":{  
                     "id":"9430250E-0A1B-421F-B372-F29E69366DED",
                     "displayName":"Ready",
                     "state":"Ready"
                  }
               }
            ]
         },
         "businessUnits":[  

         ],
         "roles":[  
            "ROLE_AGENT"
         ],
         "uri":"http://dev-ip9-187.gws.genesys.com:8090/api/v2/contacts/844b7a0e30ce46a5b364797a39f8a81f",
         "path":"/contacts/844b7a0e30ce46a5b364797a39f8a81f"
      },
      {  
         "id":"916912be76d44c92ad95d402dacfed80",
         "name":"EmilyJ",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"15001",
               "description":""
            }
         ],
         "userName":"EmilyJ",
         "firstName":"Emily",
         "lastName":"Johnson",
         "employeeId":"kWkSvnbUTJKtldQC2s/tgA==.acme",
         "emailAddress":"",
         "availability":{  
            "channels":[  
               {  
                  "channel":"voice",
                  "available":true,
                  "phoneNumber":"15001",
                  "userActivity":"Idle",
                  "userState":{  
                     "id":"9430250E-0A1B-421F-B372-F29E69366DED",
                     "displayName":"Ready",
                     "state":"Ready"
                  }
               }
            ]
         },
         "businessUnits":[  

         ],
         "roles":[  
            "ROLE_AGENT"
         ],
         "uri":"http://dev-ip9-187.gws.genesys.com:8090/api/v2/contacts/916912be76d44c92ad95d402dacfed80",
         "path":"/contacts/916912be76d44c92ad95d402dacfed80"
      },
      {  
         "id":"2c2ba86206504bb99fef7fc60eb848f8",
         "name":"HannahJ",
         "type":"User",
         "phoneNumbers":[  
            {  
               "phoneNumber":"15005",
               "description":""
            }
         ],
         "userName":"HannahJ",
         "firstName":"Hannah",
         "lastName":"Jones",
         "employeeId":"LCuoYgZQS7mf73/GDrhI+A==.acme",
         "emailAddress":"",
         "businessUnits":[  

         ],
         "roles":[  
            "ROLE_AGENT",
            "ROLE_SUPERVISOR"
         ],
         "uri":"http://dev-ip9-187.gws.genesys.com:8090/api/v2/contacts/2c2ba86206504bb99fef7fc60eb848f8",
         "path":"/contacts/2c2ba86206504bb99fef7fc60eb848f8"
      }
   ]
}

Using the type filter

Use this filter to specify the type of contact to retrieve: User, Queue, or Custom.

Request

GET /api/v2/contacts?type=Custom

HTTP Response

{  
   "statusCode":0,
   "totalCount":1,
   "contacts":[  
      {  
         "id":"bd1d8e7a-306d-4fd2-ac5b-f61bfb4e2d84",
         "name":"My Custom Contact",
         "type":"Custom",
         "phoneNumber":"123-456-7899",
         "uri":"http://dev-ip9-187.gws.genesys.com:8090/api/v2/contacts/bd1d8e7a-306d-4fd2-ac5b-f61bfb4e2d84",
         "path":"/contacts/bd1d8e7a-306d-4fd2-ac5b-f61bfb4e2d84"
      }
   ]
}
This page was last edited on August 31, 2018, at 18:21.
Comments or questions about this documentation? Contact us for support!