Users guide

What this resource is for

Users represent the people taking part in your rewards programme. They connect your customer records with activity in Spendstream, such as purchases and rewards.

When to use it

• Create a user the first time a customer visits your rewards area.
• Look up an existing user before creating one.
• Update contact details when your customer changes them.
• Fetch a white-label SSO token when you send a customer to the hosted storefront.

Important implementation notes

• UID is required and is your own identifier for the customer. Name, email and phone are optional.
• Store the Spendstream user identifier alongside your own identifier.
• Tokens from getToken are scoped to your publisher, not to a user.
• White-label publishers receive a per-user SSO token field. Fetch it on every visit. See the white-label SSO guide for the redirect format.
• Do not send the internal whitelabel parameter.
• Most responses return HTTP 200 with the real status in the body field response. Always check the body.

First visit and returning visit

 
flowchart TD
    A[Customer arrives] --> B[Call getUsersList with UID]
    B --> C{User found}
    C -->|No| D[Call addNewUser]
    C -->|Yes| E[Use existing user]
    D --> F[Continue]
    E --> F

On a first visit, getUsersList?UID= returns HTTP 200 with total-users of 0 and an empty users-list. Create the user with addNewUser. On a later visit, getUsersList?UID= returns the existing user, so skip creation.

 
curl -G "https://staging-api.spendstream.io/v2/getUsersList" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "User-Agent: YourApp/1.0" \
  --data-urlencode "UID=YOUR_CUSTOMER_ID"

Common mistakes

• The duplicate addNewUser trap. Calling addNewUser for a UID that already exists returns HTTP 200 with {"users":{"message":"User already exists with UID","response":400}} and no token. A client that only checks the HTTP status will think it succeeded, and a white-label customer will be left without a login token. Look the user up first, and check the body response value.
• Treating an unknown UID in getUsersList as an error. It is a normal empty result.
• Reusing an SSO token from an earlier visit.
• Using your token as if it belonged to one user.

Related resources

• Transactions
• Gift Cards
• Payments

Endpoint reference

The v2 endpoints for this resource are getUsersList, addNewUser, updateUser, addUserLogs and submitRemind. Exact parameters, schemas and responses are in the API reference.