Basket API User Lookup documentation draft.

API_DOC.rst

/news/lookup-user

method: GET
fields: token, or email and api-key
headers: x-api-key (instead of api-key parameter)
returns: { status: ok, user data } on success
         { status: error, desc: <desc> } on error
SSL required
token or API key required

Examples:

GET https://basket.example.com/news/lookup-user?token=<TOKEN>
GET https://basket.example.com/news/lookup-user?api-key=<KEY>&email=<email@example.com>

If user is not found, returns a 404 status and 'desc' is 'No such user'.

On success, response is a bunch of data about the user:

{
    'status': 'ok', # no errors talking to ET
    'status': 'error', # errors talking to ET, see next field
    'desc': 'error message' # details if status is error
    'email': 'email@address',
    'format': 'T'|'H',
    'country': country code,
    'lang': language code,
    'token': UUID,
    'created-date': date created,
    'newsletters': list of slugs of newsletters subscribed to,
    'confirmed': True if user has confirmed subscription (or was excepted),
    'pending': True if we're waiting for user to confirm subscription
    'master': True if we found them in the master subscribers table
}

Note that because this method always calls Exact Target one or more times, it can be slower than some other Basket APIs, and will fail if ET is down.

BASKET_CLIENT.rst

basket.lookup_user()

Usage:

import basket

try:
    user_data = basket.lookup_user(token='xxxxxx')
except basket.BasketException:
    log.exception('There was a problem')

# using email
user_data = basket.lookup_user(email='x@example.com', api_key='xxxxxx')

# or if using Django and the BASKET_API_KEY setting is defined
# you can leave off the api_key parameter. Note that using this method
# will require that your BASKET_URL setting start with 'https:'.

The return value for this function on success is a dict. On error it will raise a basket.BasketException with a status_code property indicating the HTTP response code. On success the resulting dict will be in the following form:

{
    'status': 'ok', # no errors talking to ET
    'email': 'email@address',
    'format': 'T'|'H',
    'country': country code,
    'lang': language code,
    'token': UUID,
    'created-date': date created,
    'newsletters': list of slugs of newsletters subscribed to,
    'confirmed': True if user has confirmed subscription (or was excepted),
    'pending': True if we're waiting for user to confirm subscription
    'master': True if we found them in the master subscribers table
}