Print


You must log in to the AcceptIO site before you can use AcceptIO Contacts Fetcher. Look for the Login item in the site menu, and then return to this page.

Overview
Would you like to use your Google contacts as an address book for your email program? That's simple with an email app on your Android phone (as in the screenshot on the left, below) or when using gmail, but AcceptIO users can also do that with many desktop or web mail applications (as in the screenshot on the right, below). That's possible because we provide a bridge between Google's contact protocols and the standard LDAP protocol. LDAP ( Lightweight Directory Access Protocol ) is an industry standard for accessing address books, and it is an option for many popular email programs. LDAP can also be used by other types of applications. For example, some phone systems can use LDAP lookups to supply caller names to go with CallerID numbers, or to make calls by looking up names.

The sections of this page that you are currently viewing is for setting up the necessary access controls and permissions so that you can use AcceptIO Contacts Fetcher. This is mostly a one-time process:

  • Log in to the AcceptIO site
  • Give consent for AcceptIO to access some of your Google data
  • Use your Google data in your email program or other application (see the section Configure LDAP client apps)

You will be authorizing AcceptIO to access your Google contacts, as well as your own profile details tied to your Google account. (See the section Consent on Google.) We use the profile details to display your Google identity on this page so that you can be sure you've associated your AcceptIO identity with the appropriate Google identity (in case you have multiple Google accounts). In any case, AcceptIO only reads from that information and never modifies it in any way.

Repeating for clarity: AcceptIO does not add, delete, or modify any of your Google contacts or profile data.

There are a few other things you can do from tabs on this page:

  • Manually refresh our local copy of your Google contacts (see the section Refresh your data)
  • Share some of your Google contacts with other AcceptIO users or accept what they have shared to you (see the section Share contact groups)
  • Withdraw consent to access the Google data that you have previously granted. (see the section Consent on Google.)

If you are just getting started, go to the Consent on Google section, and then verify your identity match-up in the Your identities section.


Your identities
This section exists so that you can verify that you have associated the correct Google account with your AcceptIO account. It's easy to make a mistake if you have multiple Google accounts. If you are ever in doubt, you can always check it here.

If you have just arrived here after giving your consent on Google, you may wish to manually refresh our local copy of your contact data (see the section Refresh your data). That's optional, but it may make it easier to understand certain details.


  • Your AcceptIO user identity is unknown until you are logged in at AcceptIO.
  • Your Google identity is unknown until you are logged in at AcceptIO.

Refresh your data
AcceptIO Contacts Fetcher normally fetches Google contact data automatically, when you actually try to use it. However, for efficiency, we won't do that fetch if we have done so recently. In the meantime, we consult that previously-fetched data, which we say is "cached" locally. That means you might not see any recent additions or changes you've made to your Google contacts. You can use the button below to cause an immediate refresh of your Google contacts. That will replenish our local cache with your current Google contacts information.

You can do an incremental refresh (recommended), which will just fetch the differences since the last manual or automatic refresh. Or, you can do a full refresh, which will delete currently cached data and re-fetch everything. A full refresh takes longer, and we don't recommend it in general. However, a full refresh might be useful if you are seeing errors reported on this page or if you suspect something isn't quite right. (You should still report any errors, even if a full refresh resolves it for you.)

Don't be too concerned if the numbers reported by a refresh don't add up to exactly what you expect. There is some overlap, double counting, and rare items accounted in the short report. Still, it should be in general area of the numbers you expect.


You can't refresh your data until you are logged in at AcceptIO.

Share contact groups
You can share some or all of your Google contact information with one or more AcceptIO users. What that means is that when they use AcceptIO Contacts Fetcher, they will see not only their own Google contacts, but also any of yours that you have shared with them. You are still the owner of those shared contacts, and you can stop sharing at any time. In this section, you can see and edit which contacts you share and with whom.

On the Google contacts web page, you can create labels and attach those labels to any number of your contacts. All of your contacts that have the same particular label are called a "contact group". You can have as many labels as you would like, and you can attach any number of labels (including none) to any Google contact. (Google also defines a handful of "system" labels. For example, if you "star" a contact, Google attaches the label "Starred" to that contact, even though "Starred" does not show up in the list of labels on the Google web page. "Starred" will show up in your list of contact groups at AcceptIO.)

When a contact group is shared with you, you must explicitly opt-in if you want to accept it. You should not opt-in if you don't recognize the user sharing a contact group with you.

There is more information further below about how AcceptIO Contacts Fetcher does sharing.


We can't show your contact group sharing until you are logged in at AcceptIO.

At AcceptIO, sharing is based on contact groups that you create by using labels on the Google web page (or any of the pre-defined "system" contact groups that Google provides). For example, if AcceptIO user Alice has a contact group with the label "Ducks and Geese" that Alice wants to share with AcceptIO user Bob, Alice could do so simply by sharing that contact group with Bob on this page. If Alice does not already have a contact group with the right set of contacts for sharing with Bob, Alice could create a new Google label like "Contacts I want to share with Bob", and then Alice could share that new contact group with Bob on this page. (If you are adding new labels or otherwise rearranging your contact group memberships on the Google contacts page, you might have to manually refresh your data to get it show up here without a delay. See Refresh your data. An incremental refresh should be sufficient.)

There are a few things to know about your contact group sharing:

  • Unlike most other contacts-related data, your sharing information is strictly local. It is not obtained from Google. When you purge your data at AcceptIO by revoking your Google consent, the sharing information is not deleted. If you want to also delete your sharing information, use the edit button to remove all sharing.
  • You are sharing the contact group. If you add or remove contacts from that group, the users you are sharing with will automatically see those changes reflected in the group memberships.
  • Google allows you to change the value of a label that defines a contact group. That does not adversely affect the sharing of that contact group at AcceptIO. We will see the name change for the contact group and update things accordingly. In other words, you don't have to worry about it. It should work the way you want it to work.
  • We don't validate the AcceptIO user identities that you use in your sharing information. When it comes to actually sharing contact records, only AcceptIO users can use the AcceptIO Contacts Fetcher. That allows you to set up sharing a contact group with another AcceptIO user before they actually start using AcceptIO Contacts Fetcher. It's still up to you to enter their identities correctly.
  • When you start or stop sharing a contact group with another AcceptIO user, they don't receive any explicit notification about it. However, they will see it in the "shared by" part of the table when they view this page. You should notify them to avoid confusion.
  • The user you are sharing with might have a contact group with the same name as your contact group. In fact, that's guaranteed when it comes to "system" contacts groups. You don't have to worry about it. If Alice shares a contact group named "Friendly ghosts" with Bob, who also has a "Friendly ghosts" contact group, Bob will see entries from both groups when actually looking up contacts. Alice won't see entries from Bob's "Friendly ghosts" contact group unless Bob shares that group with Alice.

Configure LDAP client apps
This section describes how to configure your email or other application to use LDAP. Since you might be referring back to this section from time to time, we'll start off with a table summarizing the particulars specific to AcceptIO Contacts Fetcher. That's likely to be different in specifics from information you might be given for using some other LDAP server. Then, we'll provide some explanation of what those items are, and we'll describe how to configure a few actual clients as examples.

Here is that table of configuration items along with a generic image of a typical configuration screen.


LDAP client configuration for AcceptIO Contacts Fetcher
Name of the LDAP serverldap.acceptio.com
Secure LDAP port number636 (the default ldaps port)
Non-secure LDAP port numbernot available
Base DN for contactsou=contacts,o=gcontact
Base DN for contact groupsou=contactgroups,o=gcontact
Bind DN examplemail=This email address is being protected from spambots. You need JavaScript enabled to view it.,ou=users,dc=acceptio,dc=com
where This email address is being protected from spambots. You need JavaScript enabled to view it. is your usual user account at AcceptIO
Bind password********
Use the same password that you use for other things at AcceptIO
LDAP object class for contactsinetOrgPerson
LDAP object class for contact groupsgroupOfUniqueNames

If this is your first exposure to LDAP, you might be surprised to learn how many applications support it as a mechanism for accessing address book information. (It's also used for many other purposes.) The technical details of LDAP are complex, and the jargon is not especially intuitive to the average user. As so often happens, many application authors try to make things friendlier by describing LDAP concepts with alternative terminology. That's well-intentioned, but it leads to inconsistencies among applications. Even if you consider yourself to be a fairly technical person, there is no shame in being confused by an application's LDAP configuration screen.

Here is a brief description of the things you may have to configure for an application. You will see many similarities to things you are used to for browsing web pages, but there are some important differences.

  • Server and port. You will be contacting a particular server where LDAP is running. You will also be using a specific TCP/IP port number, though there are default port numbers for non-secure and secure LDAP connections.
  • Secure or non-secure. Connections to LDAP servers may be encrypted or unencrypted, just as is the case for web pages. Consult the table to see which connection type or types is available for AcceptIO Contacts Fetcher.

    An application may refer to secure connections as "ldaps", "encrypted", "secure", or some other term entirely. (Note: If your application asks if you want to use "StartTLS", you should know that AcceptIO Contacts Fetcher does not support that security option.) The default port number for secure LDAP connections is 636. The default port number for non-secure LDAP connections is 389. AcceptIO Contacts Fetcher might have been configured to use different port numbers.

    If AcceptIO Contacts Fetcher has been configured to give you a choice between secure and non-secure connections, you should choose to use secure connections. You will be sending login and password information over the connection, and you want to protect it.

  • Contacts and groups. You can use AcceptIO Contacts Fetcher to look up individual contacts or groups of contacts. (You can find more explanation of contact groups in the Share contact groups section.) It's less common for applications to understand how to use groups than individual contacts, but some certainly do.

    The information in an LDAP directory is arranged hierarchically. You would not be far wrong in thinking about it the same way you think about nested folders on your local computer. When your application sends a request to the LDAP server, it has to tell the server where to start looking. The LDAP terminology for that is "base distinguished name" or Base DN. There are different Base DNs for the set of individual contacts and for the set of contact groups. Your application might refer to the starting point as "Base DN", "directory context", or some other term.

  • Login credentials. LDAP refers to the process of logging in (authenticating) as "binding". For technical reasons that aren't that interesting, you can't just give your userid and password in the usual way. Instead, you must present your userid in the form of an LDAP distinguished name. And, because it's used to "bind" the user to a place in the LDAP server's information, it's called a "Bind DN". (Don't mistake it for the similar-sounding "Base DN" described earlier.) If you are not used to LDAP, the format shown in the table above might look quite peculiar. Your application might refer to this in one of many different ways, but you should in any case follow the format shown in the table when you enter your userid.

    The password is a more normal-seeming item. It need not be wrapped in any peculiar LDAP dressing, but it might be referred to as a "bind password". It might be the same as you use for other purposes at AcceptIO, or it might be different. There should be a note in the table to clarify that for you. Your application may offer to save it for you when you are doing the configuration, it may prompt you for it the first time you need to do an LDAP request, or it may ask you for it every time you do an LDAP request.

  • Object classes. LDAP can return information in various ways, and the LDAP terminology for the type of information returned is "object class". You will not normally have to provide this information when configuring your application, but the values are provided on the off chance that you are asked.

    There are different object classes for individual contacts and contact groups because the forms of information returned are different for each.


Here are a few examples of specific LDAP clients. Terminology can vary widely in LDAP clients, even for different releases of the same application, so what you actually see might be slightly different. Remember, these are only examples. Use the explanations at the top of this section to guide you in configuring the applications.

A Google contact can have more than one email address, phone number, street addresses, and similar things. AcceptIO Contacts Fetcher, likewise, has all that are defined in your Google contacts. Some LDAP clients, unfortunately, don't deal very well with multiple email addresses or phone numbers. They will usually pick one and ignore the others. In common cases, the one they pick is the first one listed in the LDAP response from the server. Google will let you designate an email address or phone number as the default or primary choice for a contact. In the Google Contacts app on Android, you can select the email or phone number and choose "Set default". We haven't found a way to designate the default item in the Google Contacts web application, but we have noticed that the first item in the list seems to be used as the default. (That is, if you designate a default in the phone app, you will soon see it moved to the top of the list in the web app.) AcceptIO Contacts Fetcher can't force an LDAP client to pick the default item out of a list, but it does make sure that the default item is the first item in the list in the LDAP server response. That usually does exactly what's needed.

One final note: Some applications will have options for adding or editing contacts or modifying contact group memberships. Regardless of what the application user interface says, AcceptIO Contacts Fetcher does not provide any way to modify any of the data. That's intentional, and any changes must be made via a Google web page or app.


Roundcube

Roundcube is a popular open source software package for providing browser-based access to email. It is philosophically similar to Gmail and other webmail interfaces, but it is not a service you can sign up for. Instead, it is a software package that you can install to provide access to an existing email server. We're not suggesting that you download Roundcube and install it, though you certainly might choose to do so if you already operate an email server.

Whoever administers the Roundcube server would be responsible for configuring access to any LDAP directories. We're not showing the configuration since it's simply a text file with appropriate information supplied. We're showing Roundcube as an example of a client application because it has a fairly complete LDAP client implementation.

In addition to searching for individual users in AcceptIO Contacts Fetcher, it is one of the few email clients we've seen that will let you search for a contact group and use it to address a message to all of the members of that group. In the screenshot, you can see an example of selecting the user's "authors" contact group. The user interface expands to show the members of that group. When addressing an email message, the expanded list of individuals would be added to the TO:, CC:, or BCC: line. No special support is needed by the email server. That's very handy if there is a group of people you regularly exchange email with.


Thunderbird

Thunderbird is a popular open source, cross-platform (Windows, Mac, and Linux) email application. Since you install it on your local computer, it's up to you to configure it to use AcceptIO Contacts Fetcher as an address book.

The configuration screen you see in the screenshot is fairly typical for an LDAP client application. You are asked a few questions, but most low-level nitty-gritty details are pushed off to an "advanced" screen. You probably do not ever need to worry about the "advanced" screen, since Thunderbird, like most LDAP client applications, uses common settings and conventions that work well with AcceptIO Contacts Fetcher.

Thunderbird's LDAP client implementation has a few limitations.

  • Although you can define as many LDAP address books as you want, only one of them can be active at any given time (that's in addition to the local address book built into Thunderbird).
  • You can set up an LDAP configuration for searching for contact groups, but Thunderbird doesn't know what to do with the results. It treats them like malformed individual contacts, so it's not useful.
  • Finally, Thunderbird is one of those LDAP clients that does not expect a contact to have more than one email address. See the information above about such clients.

Phone number to name

You are probably familiar with the CallerID feature that can tell you the phone number of the calling party. Most modern phone equipment can also show you the name of that caller. Many people don't know that the name comes from a completely unrelated feature called CNAM that is not part of CallerID. When someone calls you, the number is supplied by their phone company. The name is provided by your phone company. Your phone company uses the CallerID to look for the name in a database. The bad news is that databases of names is woefully incomplete, so your phone company often cannot provide a number's matching name. That's why you often see just the name of a city or a generic term like "cellular caller" or even "unavailable" instead of the caller's name.

If you have the right kind of phone system on your end, you can ask it look up the caller's information instead of relying on what your phone company does. The technique is the same: you start with the CallerID number and look for the name. If your phone system will let you do an LDAP look-up, you can tell it to search in AcceptIO Contacts Fetcher. If it's one of your contacts calling you, the name will be found. Your phone might also display other information from the contact record.

In this screenshot, you see the configuration screen of a digital telephone set. It's the web configuration for a Grandstream GXV-3240 VoIP phone, but there are many other brands that have similar features. (If you have a digital phone system in a company, the configuration is probably done centrally by an administrator.) Since this is just an example, we won't explain all the fields and syntax in detail. It would be better to consult the specific equipment's manual. You should be able to see that most things are simple variations of the generic configuration options given at the top of this page. Since this particular phone is also able to send email and text messages, it offers a few different ways of looking things up. It also lets you spell out a name and then provides a button to dial the number returned by LDAP.


AcceptIO Contacts Fetcher is powered in whole or in part by software from the open source gcontact project.
Local operation of AcceptIO Contacts Fetcher is the responsibility of the AcceptIO support contacts.