/members

Overview

This endpoint retrieves a paginated list of members belonging to the authenticated business (tenant). Unlike member-specific endpoints, this endpoint operates at the business level and returns all members scoped to the x-api-key in use. Callers can filter results by a date range applied to either createdAt or updatedAt, and choose between receiving full member objects or only membership keys.

When to Use This Endpoint

Use this endpoint in the following cases:

• To synchronize or export the full member base for a business
• To generate reports on newly registered or recently updated members
• To perform bulk member data analysis or auditing
• To efficiently sync only membership keys in high-volume scenarios using returnType: "keysOnly"
• To paginate through all members of a business for data migration or BI purposes

Key Considerations

• The business scope is derived entirely from x-api-key — no locationId or similar body field is needed
• Results are sorted descending by the field specified in dateField (createdAt or updatedAt)
• fromDate and toDate are both optional; if neither is provided, no date filter is applied and all members within limit/offset are returned
• Use returnType: "keysOnly" for high-volume sync scenarios where only membership keys are needed to reduce payload size
• Pagination is controlled through limit (1–100, default 40) and offset (default 0)

Request Details

Method & URL

POST /v1/members

See API Servers for the base URL to use in place of {{server}}.

Headers

Header	Type	Required	Description
x-api-key	string	Yes	API key for authentication
x-source-type	string	Yes	Origin of the request (e.g., POS, Web)
x-source-name	string	Yes	Name of the client or integration system
x-pos-id	string	Yes	POS terminal identifier
x-branch-id	string	Yes	Branch or store location identifier

Request Body

Field	Type	Required	Default	Description
limit	integer	No	40	Maximum number of members to return (1–100)
offset	integer	No	0	Number of members to skip for pagination (≥ 0)
fromDate	string	No	—	Start of the date range filter (ISO 8601 format)
toDate	string	No	—	End of the date range filter (ISO 8601 format)
dateField	string	No	"createdAt"	Date field to filter by: "createdAt" or "updatedAt"
returnType	string	No	"full"	Response shape: "full" for complete member objects, "keysOnly" for an array of membership key strings

Request Example

curl --location --request POST 'https://{{server}}/v1/members' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: POS' \
--header 'x-source-name: pos_terminal_01' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--data-raw '{
  "limit": 40,
  "offset": 0,
  "fromDate": "2024-01-01T00:00:00.000Z",
  "toDate": "2024-12-31T23:59:59.999Z",
  "dateField": "createdAt",
  "returnType": "full"
}'

Success Response

returnType: "full"

{
  "status": "success",
  "members": [
    {
      "membershipKey": "uuid-...",
      "commonExtId": "uuid-...",
      "status": "Active",
      "firstName": "Jane",
      "lastName": "Doe",
      "phoneNumber": "+905001234567",
      "email": "jane@example.com",
      "cardNumber": "",
      "allowSMS": true,
      "allowEmail": false,
      "gdpr": true,
      "termsOfUse": true,
      "customFields": {
        "gender": "female"
      },
      "tags": [],
      "birthday": null,
      "regSourceName": "MyPOS",
      "regSourceType": "POS",
      "assets": [
        {
          "assetKey": "ABC12ABC12ABC12ABC12",
          "campaignId": "694fd00c3c10fef81fb6aced",
          "assignDate": "2024-01-01T00:00:00.000Z",
          "punches": []
        }
      ],
      "visit": 2,
      "totalSpent": 450,
      "pointsBalance": { "monetary": 100, "nonMonetary": 0 },
      "creditBalance": { "monetary": 0, "nonMonetary": 0 },
      "createdAt": "2024-03-15T10:22:00.000Z",
      "updatedAt": "2024-11-01T08:45:00.000Z"
    }
  ]
}

returnType: "keysOnly"

{
  "status": "success",
  "members": [
    "uuid-aaa-...",
    "uuid-bbb-..."
  ]
}

Response Fields (returnType: "full")

Field	Type	Description
status	string	Request status indicator ("success")
members	array	Array of member objects or membership key strings
membershipKey	string	Unique membership identifier for the member
commonExtId	string	Cross-brand external identifier
status	string	Member status (e.g., "Active", "Inactive")
firstName	string	Member's first name
lastName	string	Member's last name
phoneNumber	string	Member's phone number
email	string	Member's email address
cardNumber	string	Physical card number (empty string if not assigned)
allowSMS	boolean	SMS marketing consent
allowEmail	boolean	Email marketing consent
gdpr	boolean	GDPR consent flag
termsOfUse	boolean	Terms of use acceptance flag
customFields	object	Object containing custom key-value pairs defined by the business
tags	array	Member-level tags
birthday	string	Member's birthday (ISO 8601 or null)
regSourceName	string	Registration source name (from x-source-name)
regSourceType	string	Registration source type (from x-source-type)
assets	array	Array of Asset objects currently assigned to the member (see /member/assets endpoint for details)
visit	integer	Total number of visits/transactions
totalSpent	number	Cumulative spend amount
pointsBalance	object	Points balance broken down into monetary and nonMonetary
creditBalance	object	Credit balance broken down into monetary and nonMonetary
createdAt	string	ISO 8601 timestamp when the member was created
updatedAt	string	ISO 8601 timestamp when the member was last updated

Error Response Examples

Missing Required Header

{
  "statusCode": 500,
  "error": {
    "code": "101",
    "message": "Missing X-Api-Key header"
  }
}

Invalid Date Format

{
  "statusCode": 500,
  "error": {
    "code": "1002",
    "message": "Invalid fromDate format. Use ISO 8601 format"
  }
}

Invalid dateField Value

{
  "statusCode": 500,
  "error": {
    "code": "1007",
    "message": "Invalid dateField value. Must be 'createdAt' or 'updatedAt'"
  }
}

Invalid returnType Value

{
  "statusCode": 500,
  "error": {
    "code": "1008",
    "message": "Invalid returnType value. Must be 'full' or 'keysOnly'"
  }
}

Internal Server Error

{
  "statusCode": 500,
  "error": {
    "code": "1030",
    "message": "Internal server error while fetching members"
  }
}

Error Codes

Code	Description
101	Missing or invalid x-api-key header
102	Missing x-source-type header
103	Missing x-source-name header
104	Missing x-pos-id header
105	Missing x-branch-id header
1002	Invalid fromDate format — must be ISO 8601
1003	Invalid toDate format — must be ISO 8601
1007	Invalid dateField value — must be "createdAt" or "updatedAt"
1008	Invalid returnType value — must be "full" or "keysOnly"
1030	Internal server error while fetching members

Field Reference

Member Object

For detailed information about the member response fields, see the Member reference page.

Asset Object

The assets array in the member response contains Asset objects, which represent redeemable promotional items and benefits assigned to the member. Each asset includes:

• campaignId — Unique identifier of the issuing campaign
• assetKey — Unique identifier of this specific asset instance
• assignDate — When the asset was assigned to the member
• status — Asset status ("active" or "inactive")
• validFrom / validUntil — Validity date range (ISO 8601)
• assetDetails — Campaign metadata including name, description, and image

For comprehensive field documentation and examples, refer to the Asset reference page.

Related Use Cases

• Exporting the full member base for CRM or data warehouse integration
• Identifying newly registered members within a specific date range
• Monitoring member profile updates for change-data-capture pipelines
• Efficient bulk membership key sync to external systems using keysOnly
• Auditing member growth and activity across the business