Check User Segment Membership

Use the Check User Segment Membership API to find out, in real time, whether a user belongs to one or more segments. Send one user identifier and a list of segment IDs, and Insider One returns true or false for each segment ID you send.

The API checks membership only. It doesn't return the other segments the user belongs to, and it doesn't return any profile data.

Use cases

• Show or hide a banner on page load: Check whether the visitor is in a target segment before the page renders, and show the banner only to members.

• Gate a pop-up or an offer: Show a pop-up, an offer, or a piece of content only to users in an eligible segment, using your own front end or back end.

• Feed media retargeting: Check membership on page load and pass the result to your retargeting or audience partners.

• Let an AI agent check before it acts: For example, an agent can check whether a user is in your VIP or churn-risk segment before it responds or takes an action.

Before you start

You need the following before your first call:

• Segment IDs: Copy them from each segment's detail page in the InOne panel. The API supports both dynamic and static segments. See Find your segment IDs.

• A credential: Use your API authentication token or an OAuth 2.0 credential. See Authenticate.

Only users with the Administrator permission can generate OAuth 2.0 credentials.

Find your segment IDs

Open the segment in the InOne panel. Its ID appears on the segment detail page. Send that value in segment_ids as a number.

You can check dynamic and static segments, and mix both types in the same request.

Authenticate

You can authenticate in one of two ways. Both return the same result, so pick the one that fits your setup.

Keep your credentials private

Whichever method you use, call this API from your back end so your credentials stay private to your team. See Best practices.

Option 1: API authentication token

Send your partner name and API authentication token in the headers, the same way you do for the Upsert User Data API.

POST https://unification.useinsider.com/api/user/v1/segment/membership

The token must belong to the partner in X-PARTNER-NAME.

Option 2: OAuth 2.0

POST https://gw.useinsider.com/api/cdp/v1/segment/membership

The gateway identifies your account from the token, so the request doesn't need a partner name.

OAuth 2.0 enablement

OAuth 2.0 access to this API is turned off by default. Contact Insider One Support to enable it for your account. Until then, every OAuth 2.0 call returns 403.

Step 1: Create a credential

1. Click your username, then navigate to Settings > Inone Settings > Integration Settings.

2. Scroll to the OAuth 2.0 Credentials section and click Generate OAuth 2.0 Credential.

3. Under the UCD scopes, select UCD - Segment Membership. Then name the credential and set a token duration.

4. Authorize your trusted IP addresses, then click Authorize and Generate.

5. Copy the Client ID and Client Secret before you close the window. The InOne panel shows the secret only once.

For more details, see OAuth 2.0 Credentials.

Step 2: Get an access token

curl --location 'https://gw.useinsider.com/oauth2/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "{your-client-id}",
    "client_secret": "{your-client-secret}",
    "scopes": [
      "ucd-segment-membership"
    ]
  }'

Cache the token and reuse it until it's close to expiring. Don't request a new token for every call.

Body parameters

Send exactly one of insider_id or identifiers, plus segment_ids.

Identify the user

The identifiers object uses the same keys as the Upsert User Data API, so one integration can build both payloads. Send one identifier per request.

Every identifier value must be a non-empty string of 255 bytes or less.

Nest custom identifiers under custom

The API rejects a custom identifier sent outside custom with a 400 error. This applies to a bare key, such as "loyalty_card": "card-9", and to a prefixed key, such as "c_loyalty_card". This way, a typo never turns into a silent "not a member" answer.

Sample requests

The request body is the same for both authentication methods.

By email, with an API authentication token:

curl --location 'https://unification.useinsider.com/api/user/v1/segment/membership' \
  --header 'X-PARTNER-NAME: mybrand' \
  --header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
  --header 'Content-Type: application/json' \
  --data '{
    "identifiers": {
      "email": "jane@example.com"
    },
    "segment_ids": [
      2278903,
      2278904,
      2278905
    ]
  }'

By email, with OAuth 2.0:

curl --location 'https://gw.useinsider.com/api/cdp/v1/segment/membership' \
  --header 'Authorization: Bearer eyJhbGc...' \
  --header 'Content-Type: application/json' \
  --data '{
    "identifiers": {
      "email": "jane@example.com"
    },
    "segment_ids": [
      2278903,
      2278904,
      2278905
    ]
  }'

By Insider ID (request body):

{
  "insider_id": "{insider-id}",
  "segment_ids": [
    2278903
  ]
}

By custom identifier (request body):

{
  "identifiers": {
    "custom": {
      "loyalty_card": "card-9"
    }
  },
  "segment_ids": [
    2278903,
    2278904
  ]
}

Sample responses

200 OK

The response returns the identifier you sent (after normalization) and a segment_ids object with one entry per requested ID.

{
  "identifiers": {
    "email": "jane@example.com"
  },
  "segment_ids": {
    "2278903": true,
    "2278904": false,
    "2278905": true
  }
}

When the answer is false

A false value means the user isn't a member of that segment. You also get false, with a 200 status, in the following cases:

• The user doesn't exist on your account.

• The segment ID doesn't exist or doesn't belong to your account.

This behavior is by design. The API never confirms whether a user or a segment exists, and one outdated segment ID never fails the whole request. If an ID unexpectedly returns false, check it on the segment's detail page in the InOne panel.

400 Bad Request

The API returns 400 when the request body is invalid. The error field names the problem.

{
  "error": "segment_ids entries must be positive integers"
}

Error responses

Best practices

The Check User Segment Membership API is built for secure server-to-server use. Every call needs a credential issued for your account: either your API authentication token or an OAuth 2.0 token limited to this scope. Insider One also rate-limits every request, and the API never returns profile data or reveals whether a user exists.

To get the most out of these protections, follow these practices:

• Call the API from your back end. Keep your credentials on your server, not in a browser or mobile app, so they stay private to your team.

• Check only the segments your use case needs.

• Rotate your credentials regularly in Integration Settings.

Limits

• Read-only: The API doesn't change any data.

• Membership only: The API doesn't return profile data or any other segments.

• Segments per request: Up to 100 segment IDs.

• Users per request: One identifier.

• Rate limit: 120 requests per minute per account by default, with bursts of up to 10 requests per second. Contact Insider One Support if you need higher limits.

FAQ

Q: Why do I get false instead of 404 for an unknown user?

A: To protect your users' privacy, the API never reveals whether an identifier exists. An unknown user isn't a member of any segment, so the API returns false.

Q: Do I need to enable the API?

A: Not if you use an API authentication token, since it's available for every account. For OAuth 2.0, contact Insider One Support to enable access, then create an OAuth 2.0 credential with the UCD - Segment Membership scope.

Q: Which authentication method should I use?

A: Either one works, and the request body and response are the same. If your integration already sends data with your API authentication token, use that. If it already uses OAuth 2.0 with Insider One, use OAuth 2.0.

Q: Can I call the API directly from my website or app?

A: We recommend calling it from your back end and sending your page only the decision it needs (for example, "show the banner"). This keeps your credentials private to your team. See Best practices.

Q: How is the API protected?

A: Every call needs a credential issued for your account: your API authentication token or an OAuth 2.0 token limited to the Segment Membership scope. Insider One also rate limits every request.

Q: What data does the API return?

A: The API returns only true or false for each segment ID you send, plus the identifier you sent. It never returns profile data, other segments, or whether a user exists.

Q: How often should I rotate my credentials?

A: Rotate them regularly, following your own security policy. Generate a new credential in Integration Settings, update your integration, then stop using the old credential.

Q: Can I check many users in one request?

A: No. Each request checks one user against up to 100 segments.

Q: Can I get all the segments a user belongs to?

A: No. The API only returns results for the segment IDs you send.

Q: Where do I find segment IDs?

A: Open the segment in the InOne panel. The ID on its detail page is the value to send. Both dynamic and static segment IDs work.