Touchpoint API

The Touchpoint API is the member-facing API used by TRIFFT mobile apps, web widgets, and other customer touchpoints. Unlike the server-to-server Trifft API (API keys / OAuth), Touchpoint endpoints authenticate end-users with JWT access tokens.

Base URL

https://touchpoint-api.trifftloyalty.com

Authentication

Touchpoint endpoints authenticate members with JWT access tokens (ROLE_USER). Login and token refresh are public; all other endpoints require a valid member JWT.

Login

Call POST /v1/user/login with the member username and password. Include X-Trifft-ProjectId so the API can resolve the project (member emails and phones are unique per project, not globally):

X-Trifft-ProjectId: <project_id>

The response includes a JWT token and refresh_token. Subsequent protected requests send:

Authorization: Bearer <token>

The access token includes a project claim. When that claim is present, protected Touchpoint calls do not need X-Trifft-ProjectId.

When the access token expires, call POST /v1/user/token/refresh with the refresh token. Refresh still needs X-Trifft-ProjectId because the refresh request does not send the access token.

Session tokens from the Member API

You can issue the same JWT from the server-to-server Get a Member Session Tokens endpoint (GET /v1/member/{member_id}/session-tokens on the Trifft API). Use that token as Authorization: Bearer <token> on Touchpoint. Because the project is already in the JWT, those requests do not need X-Trifft-ProjectId.

Sections

Section	Controllers / scope
Auth	Login, token refresh
User	Profile, registration, verification, addresses, identities
Cards	Physical/virtual cards, Apple/Google Wallet passes
Coupons	List, detail, redeem/activate, deactivate
Contests	Contest detail, tokens, draw, history
Consents	List, HTML text, sign
Notifications	Inbox list, mark read
Privacy	GDPR deletion / data export
Transactions	POS/receipt history
Wallet Transactions	Primary wallet point history
Params	Public custom-parameter definitions
Promo	Promo-event code redemption

Response envelope

Most JSON endpoints return:

{
  "status": 200,
  "success": true,
  "data": {}
}

Error responses typically use:

{
  "status": 400,
  "success": false,
  "error": {
    "code": 1002,
    "message": "Human-readable message",
    "exception": "ExceptionClassName"
  }
}

A few endpoints intentionally differ:

Endpoint	Notes
`POST /v1/user/login`	Returns `{ "token", "refresh_token" }`
`POST /v1/user/token/refresh`	Returns refreshed JWT tokens
`POST\|PATCH /v1/notification/{id}/read`	HTTP `202` empty body
Consent text `GET` routes	Return `text/html`
Apple Wallet pass	Returns `.pkpass` binary

Deprecated endpoints

Prefer the dedicated resources below:

Deprecated	Replacement
`POST /v1/user/wallet/transactions`	`POST /v1/wallet-transactions`
`POST /v1/user/receipts`	`POST /v1/transactions`
`GET /v1/user/receipt/{transactionId}`	`GET /v1/transaction/{transactionId}`
`GET /v1/{entity}/params`	`GET /v1/params`