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:
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"
}
]
}