Single use tokens

Single use tokens can be used for providing a pre-defined set of identifiers to be used as id's for new customers created in Custobar. You can create a single use token list in Custobar's settings, and upload the tokens there. If you need to assign the tokens to customers in another system, but use the Custobar's token list as the source, you can use the single-use-token API.

When you have created a single use token list in Custobar, you can see its api identifier in Custobar settings. Use this identifier to identify the list in API calls.

Getting single use token list state

To get the current state of single use token list with api identifier IDENTIFIER, make a GET request to:

https://COMPANY.custobar.com/api/single-use-tokens/IDENTIFIER/

This will return a JSON response with structure like this:

{
  "token_list": {
    "id": "IDENTIFIER",
    "name": "My list of customer ids",
    "reserved_token_count": 23261,
    "available_token_count": 196850
  }
}

Reserving a new token

To reserve a token from a single use token list, make a POST request to:

https://COMPANY.custobar.com/api/single-use-tokens/IDENTIFIER/reserve/

This will reserve one token from the list, and return it in a JSON reply:

{
  "token": "9111928389182"
}

You can test the api with a GET request, using additional `?peek=1 query string:

https://COMPANY.custobar.com/api/single-use-tokens/IDENTIFIER/reserve/?peek=1

This will return the next token, but does not reserve it, so repeated calls will return the same token. This should only used when testing the API.

If the token list is out of available tokens, reserve will reply with HTTP 404 error response.

Topping up a token list

To top up a single use token list with new tokens, make a POST request to:

https://COMPANY.custobar.com/api/single-use-tokens/IDENTIFIER/upload/

The request body should be a JSON object with the following structure:

{
  "tokens": ["991239012", "991239014", "991239020"]
}

Getting a list of available token lists

You can get a list of all of your single use token lists by sending a GET request to:

https://COMPANY.custobar.com/api/single-use-tokens/

This will yield a list of token lists states in a JSON object:

{
  "token_lists": [
    {
      "id": "IDENTIFIER",
      "name": "My list of customer ids",
      "reserved_token_count": 23261,
      "available_token_count": 196850
    }
  ]
}

Creating a new token list

You can create a new token list by sending a POST request to:

https://COMPANY.custobar.com/api/single-use-tokens/

The request body should be a JSON object specifying the new list's name, and optionally an initial list of tokens:

{
  "name": "Customer Card Numbers",
  "tokens": ["N123", "N333", "N555"]
}

The reply will be the state of the new token list:

{
  "token_list": {
    "id": "c8899ccj8jd",
    "name": "Customer Card Numbers",
    "reserved_token_count": 0,
    "available_token_count": 3
  }
}

Note that Custobar will assign an id to the newly created list. Use this id to refer to the list in future api requests.