Documentation :: User IDs & Namespaces

User IDs

Face.com supports tagging, training, and recognition of users of known social networks as well as private user databases. All user IDs used in the calls and responses follow this syntax:

user_id[@namespace]

e.g.:

  • 571756321@facebook.com (our CEO's ID on facebook)
  • facedotcom@twitter.com (face.com's uid on twitter)
  • myuserid@mynamespace.com (any uid in a private namespace)

Shorthand Notation

You may also use the shorthand notation of user IDs by omitting the @namespace, and providing it once in the namespace parameter instead.

User access restrictions

Access to facebook and twitter user IDs is controlled based on valid user credentials. See Auth for more information. In addition, you can't access the user information of another developer account's namespace.

Private Namespaces

When you want to build your own set of recognizable users (e.g. your own site's user space, a test group, non-public profiles, etc.), you can go ahead and create a namespace.

Users in a private namespaces are added implicitly through calls to tags.save with your own user IDs, and become recognizable after the first faces.train is called for them. You can also obtain the current list of users within a namespace through a call to account.users.

A couple of things worth noting about private namespaces:

  • The index information in a private namespace can be shared across all applications of the account creating the namespace. This means that applications outside the account cannot access this information.
  • As with all namespaces, tags.get results include only tags saved by the calling application.
  • There is no user-level access control to the information in a private namespace - how you obtain and manage access to your information is entirely up to you.
  • The default accounts are limited to 1,000 users across all namespaces in the account. Read more about limits here.

Namespace can be defined with various of share modes:

  • Private - Only accessible from api keys of the owner.
  • Public Read-Only - Accessible to everyone for recognition, and tags.get. Write operations such as save, train or delete are only accessible for the owner.
  • Public - Accessible to every one, to read and to write (save/train/delete).

You can check which namespaces are available to use by your api_key using the method account.namespaces.

User Lists

We provide special user lists to reduce call overhead, and focus recognitions on relevant groups of users:

  • friends@facebook.com - facebook friends of the currently logged-in user
  • all@namespace.com - all-users in a private namespace
  • *<user>@namespace - all users tagged-by <user> - this is a great way to automatically keep the recognition search list focused only on what was used by the current user. For this to work with private namespaces, you can use the extended form of tags.save to specify the 'tagger ID' (ID of the user performing the tagging).