Users API

Use these APIs to to perform actions related to your users (members).

The id and auth_id are two different fields and are not interchangeable.

When using our Loyalty API, if you want to take an action on a user’s account, you need to use the auth_id.

The auth_id can be set by you if you register users using our Loyalty API. So, for example, you could set it to the primary key you have for the user in your own systems. This saves you the trouble of creating another column to map users in your system to the user profile with qiibee.

However, if you prefer qiibee that generates a new unique identifier for every new user registration, simply leave the auth_id field empty and we will generate a UUID-v4 and return it to you so you can save it in your system. The user_id shown in the Loyalty Whitelabel App (LWA) frontend is different from the auth_id and is used exclusively for the LWA frontend.

Create User

POST /users

Only the email field is mandatory. The email will be validated, failing which, will return a 400.

We recommend you send a unique UUID-v4 auth_id for every new user registration so you can map each user to your internal system. If you do not send this field we will generate a UUID-v4 and return it to you.

Please save the auth_id and use it for all actions on a user's account.

eg.

{
    "user": {
        "id": "3r2esf3423r",
        "email": "[e-mail]",
        "auth_id": "e24c962d-c81c-4a01-b0cd-57dd233553f1",
        "first_name": "John",
        "second_name": "Doe",
        "language": "en",
        "country_ISO": "usa",
        "metadata": {
        "opts_newsletter": true | false
      }
    }
}

Responses

• Created: HTTP 201 with the user object

• Bad data: HTTP 400 with error message

  • eg. duplicate auth_id

Update User details

PUT /users/:auth_id || PATCH /users/:auth_id

You can update every field besides the auth_id

eg.

{
    "user": {
        "id": "3r2esf3423r",
        "email": "[e-mail]",
        "first_name": "John",
        "second_name": "Smith",
        "language": "it",
        "country_ISO": "usa",
        "metadata": {
            "opts_newsletter": true | false
        }
    }
}

Responses

• Update: HTTP 200 with the user object

• Not found: HTTP 404 with error message

Get List of Users

GET /users/

This request returns a paginated list of users. By default, it returns the last 100 users associated with your brand, along with the total count of the users.

You can query transactions using the following query parameters:

• limit: (optional) sets the required limit of users history to be requested.

  • Defaults: 100

  • Maximum: 100

• offset: (optional) number of users to offset when getting the remaining users.

  • Default: 0

• email_like: (optional) a partial or complete email address of registered users.

• from_time: (optional) queries for transactions that begin from the specified datetime.

  • Defaults: The datetime at which the brand was created in the qiibee database.

• to_time: (optional) queries for transactions until the specified datetime.

  • Defaults: The current datetime.

The params, limit and offset, work exactly as they’re used in SQL.

Please be sure to encode the query parameters. In the time parameters, the date and time must be expressed according to ISO 8601.

eg: The datetime for 06 June 2022 at 11:23:23 AM will be expressed as 2022-06-01T11:23:23Z

Responses

• Success: HTTP 200 with the user object:

  • {
        "data": {
            "users": <list_of_users>,
            "offset": 0,
            "limit": 100,
            "total_count": <total_count_of_users>
        }
    }

• Bad data: HTTP 404 with error message

  • eg. not found

Get User Details

GET /users/:auth_id

Responses

• Success: HTTP 200 with the user object:

  • {
        "data": {
            "id": "3r2esf3423r",
            "email": "[e-mail]",
            "auth_id": "e24c962d-c81c-4a01-b0cd-57dd233553f1",
            "first_name": "John",
            "second_name": "Doe",
            "language": "en",
            "country_ISO": "usa",
            "metadata": null | {
                "opts_newsletter": true | false
               }
          }
    }

• Bad data: HTTP 404 with error message

  • eg. not found

Create User Membership

POST /users/:auth_id/memberships

All fields are mandatory.

Each user can have 1 membership per exchange provider. You can override the membership number in specific requests - for example, when exchanging points to miles you can provide a new membership number specifically for that request.

brand_id can be one of:

• your brand's id (in this case, the membership number will be your user's auth_id)

• etihad

• miles_and_more

• alaska

The membership number will be validated. If you want to know how you can validate the numbers yourself please reach out to us and we will provide the algorithms for each exchange provider.

eg.

{
    "membership": {
        "brand_id": "etihad" | "miles_and_more",
        "membership_number": "xxxx....xxx"
    }
}

Responses

• Created: HTTP 201 with the user object

• Not found: HTTP 404

  • user not found

• Bad data: HTTP 400 with error message

  • invalid format for the membership number

  • invalid exchange provider

Update User Membership

Same as Create User Membership.

Get User Memberships

GET /users/:auth_id/memberships

This will return all the memberships for a user. If no memberships exist for the user this will be an empty array.

eg.

{
    "data": [
        {
            "membership_number": "xxx...xxxx",
            "brand": {
                "name": "Miles and More",
                "id": "miles_and_more",
                "locations": [],
                "brand_config": null
            }
        },
        {
            "membership_number": "yyy...yyyy",
            "brand": {
                "name": "Etihad",
                "id": "etihad",
                "locations": [],
                "brand_config": null
            }
        }
    ]
}

Get User Membership

GET /users/:auth_id/memberships/:implementation_name

Returns the membership information for a user for a particular exchange provider implementation, if found, 404 and empty object otherwise.

eg.

{
  "data": {
    "membership_number": "xxx...xxx",
    "brand": {
      "id": "etihad",
      "name": "Etihad",
      "locations": [],
      "brand_config": null
    }
  }
}

Responses

• Success: HTTP 200 with membership

• Not found: HTTP 404 if user or membership not found

Delete User Membership

DELETE /users/:auth_id/memberships/:implementation_name

Deletes the membership information for a user if it exists. Returns 404 if user or membership not found.

eg.

{
  "data": {
    "membership_number": "xxx...xxx",
    "brand": {
      "id": "etihad",
      "name": "Etihad"
    }
  }
}

Responses

• Success: HTTP 204

• Not found: HTTP 404 if user or membership not found

• Bad request: HTTP 400 if the implementation does not exist