Find members

GET/v1/members

Looks up members by an exact value. Send one of the three query parameters. There is no partial or fuzzy search. Use it when you have your own id or the guest's contact details but haven't stored the unPLUG id.

Permissions: Secret key with members:read.

Guide

Members and sign-in

Query parameters#

external_idstring
Your id for the guest.
emailstring (email)
Matched in lowercase.
phonestring
E.164. URL-encode the + as %2B.
limitinteger
See Pagination.
Min 1Max 100Default 25
cursorstring
See Pagination.

No match returns 200 with an empty data array, not a 404.

Response fields#

Returns 200 with list of Member

dataarray of Member
Show attributesMember
- idstring (uuid)
  unPLUG's id for the member. Store it next to your user record.
- external_idstringNullable
  Your id for the guest, up to 128 characters. null for a guest who has only earned at the register and isn't linked to your login yet.
  Max Length 128
- statusstring
  active. The member.deleted webhook carries deleted; after that, calls about the member return 410 member_deleted.
  One of active, deleted
- first_namestringNullable
- last_namestringNullable
- emailstring (email)Nullable
  Saved in lowercase.
- phonestringNullable
  E.164, for example +15125550142.
- phone_verifiedboolean
  true when you confirmed the guest owns the number, for example with an SMS code. Only verified phones link to existing members.
- birthdaystring (date)Nullable
  YYYY-MM-DD.
- points_balanceinteger
  Points the member has now. Never below zero.
- lifetime_pointsinteger
  All points ever earned, used for tiers. Spending doesn't lower it.
- tierTierRef
  id and name of the current tier.
  Show attributesTierRef
  - idstring (uuid)
  - namestring
- next_tierobjectNullable
  id, name and points_needed (lifetime points still to earn). null at the top tier.
  Show attributesHide attributes
  - idstring (uuid)
  - namestring
  - points_neededinteger
- communication_preferencesobject
  Marketing consent: email_marketing, sms_marketing, push_marketing. See communication preferences.
  Show attributesHide attributes
  - email_marketingboolean
  - sms_marketingboolean
  - push_marketingboolean
- metadataobject
  Your own string values. Up to 20 keys, 500 characters each. Don't put personal data here.
- linked_existingboolean
  Only on create: true when an existing member was linked by verified phone.
- enrolled_atstring (date-time)
  When the guest joined the program.
- created_atstring (date-time)
- updated_atstring (date-time)
has_moreboolean
True when another page exists.
next_cursorstringNullable
Pass as cursor to get the next page.

GET/v1/members

1
2curl "$UNPLUG_API/members?phone=%2B15125550142" \
  -H "Authorization: Bearer $UNPLUG_KEY"

1
2
3
4
5
6const response = await fetch(`${process.env.UNPLUG_API}/members?phone=%2B15125550142`, {
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
  },
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10import os
import requests

response = requests.get(
    f"{os.environ['UNPLUG_API']}/members?phone=%2B15125550142",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
)
data = response.json()

Response JSON200

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "data": [
    {
      "id": "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
      "external_id": "usr_10482",
      "status": "active",
      "first_name": "Maya",
      "last_name": "Lopez",
      "email": "maya@example.com",
      "phone": "+15125550142",
      "phone_verified": true,
      "birthday": "1994-03-18",
      "points_balance": 420,
      "lifetime_points": 1880,
      "tier": { "id": "2b9e4f7a-1c3d-4e6b-8a5f-9d0c2e7b4a13", "name": "Green" },
      "next_tier": { "id": "6f1a8c3d-9b2e-4d7a-b5c6-3e0f8a1d2b47", "name": "Gold", "points_needed": 120 },
      "communication_preferences": { "email_marketing": true, "sms_marketing": false, "push_marketing": true },
      "metadata": { "favorite_store": "south-congress" },
      "enrolled_at": "2025-06-14T15:02:44Z",
      "created_at": "2025-06-14T15:02:44Z",
      "updated_at": "2026-11-01T16:12:41Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Error descriptions#

400Bad request

missing_param

None of external_id, email or phone was sent.

400Bad request

invalid_param

The phone isn't E.164.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#missing_param",
  "title": "Bad request",
  "status": 400,
  "code": "missing_param",
  "detail": "None of external_id, email or phone was sent."
}