BlackBerry Directory Lookup Service API User Guide

BlackBerry Directory Lookup Service API

FAQ

Frequently Asked Questions

• What is the Directory Lookup Service API?
  • The Directory Lookup Service API provides a service to retrieve specific attributes from Microsoft Active Directory and allows users to search for information efficiently.
• How can I enable contact lookup by phone number?
  • To enable contact lookup by phone number, specify the appropriate search key in the request JSON and set the SearchContacts property to true.
• What are the available user shapes for specifying attributes?
  • The available user shapes include FullName, DisplayName, GivenName, Surname, EmailAddress, and AlternativeEmailAddresses. These shapes allow users to customize the attributes returned in the search results.

What is the Directory Lookup Service API

The Directory Lookup Service REST API provides a service to retrieve specific attributes from Microsoft Active Directory.
You can also specify whether to search the personal contact folder when a directory lookup is performed.

REST Function

• Function: lookupuser
• REST call URI: http(s)://server/api/lookupuser
• Verb: POST
• Comments: Required request is JSON

The following table describes the request properties you can include in the REST function JSON file:

requestor.
SearchKey| String| This property specifies the search string to look for.
MaxNumber| Integer| This property specifies the maximum number of users or objects to return in the search query.

If the maximum number is less than or equal to zero, BEMS returns all the users with the search key.

SearchContacts| Boolean| This property specifies whether to search for users in the private contact folder in addition to the company directory.
UserShape| String Array| This property specifies the list of attributes to return in the search results. See the following table for a list of user shape options.

BEMS tries to match the user key against the following user data stored in the company directory (typically Microsoft Active Directory):

• Last Name
• Display Name
• Full Name
• Alias
• Email Address
• Phone number*
  • • To allow users to search for other users in the GAL using a phone number, see Searching for users by phone number.

If BEMS is configured to use Microsoft Graph, when users search Active Directory, the Home phone number and Photo are not returned in the results.

The following table describes the user shapes you can use when you specify the UserShape request property:

Name

|

Type

|

Example

| Alternative name
---|---|---|---
Full Name| String| “James Lambier”|
Display Name| String| “James Lambier”|
Given Name| String| “James”| FirstName
Surname| String| “Lambier”| Lastname
Email Address| String| “jlambier@example.com”| Email
Alternative Email Addresses String array|   [“x400:C=US;A= ;P=Example

Technology;O=SF Bay Area;S=Lambier;G=James;”,

“X400:C=US;A= ;P=BlackBerry Limited;O=SF Bay Area;S=Lambier;G=James;”,

“EUM:7910;phone-context=SVL Dial Plan.example.com”]

|
Physical Addresses| Object array| [{“Street”:”3001 Bishop Dr”,

“City”:”San Ramon”, “State”:”CA”,”Country”:”United

States”}]

| Addresses
Phone Numbers| Object array| [{“Key”:”Business”,

“Value”:”+1-519-555-0100″},

{“Key”:”Home”,

“Value”:”+1-519-555-0100″}]

|
Department| String| “Development”|
JobTitle| String| “KB Page Writer| Title
Company Name| String| “BlackBerry”| Company
Office Location| String| “SANRAMON”| Location, Office
Has Photo| Bool| True| HasPicture
Photo| Base64 string| “dG9tIGp1bmp1biBsaXUncyBwaG90bw==”| Picture
Alias| String| “jsmith”|
SMIME Certificate| Base64 string| “dG9tIGp1bmp1biBsaXUncyBwaG90bw==”|
Manager Display Name| String| “Jeff Holleran”| ManagerName
ManagerEmailAddress| String| “jholleran@example.com”| ManagerEmail
---|---|---|---
DirectReports| Object array| [{“Name”: “James Lambier”, “Email”: “jlambier@example.com”},

{“Name”: “Paul Morley”, [“Email”:”pmorley@example.com”}]](mailto:pmorley@example.com)

|

Searching for users by phone number

BEMS supports users searching for other users in the GAL by phone number.
To allow BEMS to support this feature, your environment must meet the following requirements:

• The Microsoft Active Directory phone attributes must be indexed and enabled for ANR
• The phone number must be in one of the following formats:
  • +1 (555) 123 4567
  • +1.555.123.4567
  • +1-555-123-4567
  • 15551234567
  • 555.123.4567
  • +1 5551234567

By default, the phone attribute is disabled for GAL search.

Enable contact lookup by phone number

To allow users in your environment to lookup contacts using their phone number, use the Microsoft Active Directory schema MMC snap-in to index and enable ANR for the applicable phone attributes.
Before you begin: The phone number must be in a supported format. For a list of supported formats, see Searching for users by phone number.

1. Click the Attributes folder in the snap-in.
2. In the right panel, right-click the desired attribute, and then click Properties.
3. Select the Index this attribute check box.
4. Select the Ambiguous Name Resolution (ANR) check box.
5. Click OK.
6. If you have multiple phone attributes, repeat steps 2 to 5 for each attribute.

Codes Information

HTTP response codes

token verification.

Note: It is possible for the server to return a 200 code and an empty user list in the response body at the same time. This indicates that the service runs, but it can’t find any user with the given search key.

500| Internal server error.

Code example

Device submit a HTTP POST request to BEMS.
[Http Header]

Contains the auth information.

The following are the headers of an example request:

[POST body]

• “testuser@example.com“

[Response Header]

[Response Body]

If the device requests any property not yet understood by the BEMS server (for example,”WeddingAnniversary”), BEMS will retrieve as many properties as possible and include only those properties that are found, understandable, and supported in the JSON response. If an unexpected error occurred during the lookup handling, BEMS returns a non 200 HTTP response code.

Legal notice

©2023 BlackBerry Limited. Trademarks, including but not limited to BLACKBERRY, BBM, BES, EMBLEM Design, ATHOC, CYLANCE and SECUSMART are the trademarks or registered trademarks of BlackBerry Limited, its subsidiaries and/or affiliates, used under license, and the exclusive rights to such trademarks are expressly reserved. All other trademarks are the property of their respective owners.

Patents, as applicable, identified at: www.blackberry.com/patents.

This documentation including all documentation incorporated by reference herein such as documentation provided or made available on the BlackBerry website provided or made accessible “AS IS” and “AS AVAILABLE” and without condition, endorsement, guarantee, representation, or warranty of any kind by BlackBerry Limited and its affiliated companies (“BlackBerry”) and BlackBerry assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect BlackBerry proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of BlackBerry technology in generalized terms. BlackBerry reserves the right to periodically change information that is contained in this documentation; however, BlackBerry makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party websites (collectively the “Third Party Products and Services”). BlackBerry does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by BlackBerry of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL BLACKBERRY BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE,
OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH BLACKBERRY PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF BLACKBERRY PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF BLACKBERRY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, BLACKBERRY SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO BLACKBERRY AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED BLACKBERRY DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF BLACKBERRY OR ANY AFFILIATES OF BLACKBERRY HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with BlackBerry’s products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them.

You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with BlackBerry’s products and services are provided as a convenience to you and are provided “AS IS” with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by BlackBerry and BlackBerry assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with BlackBerry.

The terms of use of any BlackBerry product or service are set out in a separate license or other agreement with BlackBerry applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY BLACKBERRY FOR PORTIONS OF ANY BLACKBERRY PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.
BlackBerry Enterprise Software incorporates certain third-party software. The license and copyright information associated with this software is available at http://worldwide.blackberry.com/legal/thirdpartysoftware.jsp.

BlackBerry Limited

• 2200 University Avenue East Waterloo, Ontario
• Canada N2K 0A7

BlackBerry UK Limited

• Ground Floor, The Pearce Building, West Street, Maidenhead, Berkshire SL6 1RL
• United Kingdom

Published in Canada

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>