AtlasCustomer portalAPI DocumentationGo to Atlas
Help Center›Integrations Setup (For Admins)›How to connect the Segment integration
Table of contents
  • Overview
  • Key Features
  • What Segment sends to Atlas
  • How to connect Segment to Atlas
  • Part 1: Create a Segment key in Atlas
  • Part 2: Build the destination function in Segment
  • Part 3: Test it and create the function
  • Part 4: See the result in Atlas
  • How to revoke a Segment key
  • FAQs & Troubleshooting
  • Do I need a developer?
  • What is the App ID on the Segment page?
  • Why don't I see the customer in Atlas?
  • Can I choose where Segment events appear?

    • How to connect the Segment integration

    Last updated October 23, 2026

    Who can use this feature?
    Admins only.

    Overview

    Segment is a tool many companies use to collect what customers do in their product. Connecting it to Atlas means your agents see that activity without asking the customer.

    Think of it like this:

    1. An user, let's say Alex Lee signs up in your app. Segment sends an "Identify" event. Atlas creates Alex as a customer.
    2. Alex completes a purchase. Segment sends a "Track" event. Atlas adds it to Alex's timeline.
    3. Alex writes to support. Your agent opens the ticket and already sees who Alex is and what Alex just did.

    To make this work, you create a key in Atlas and paste a ready-made script in Segment. You don't need to write code.

    Related articles:
    •  How to manage custom events: Choose where events appear in Atlas.
    •  How to use the Atlas API: Send data to Atlas without Segment.
    •  API keys in Atlas: Create keys for the Atlas API.

    Key Features

    • No coding needed: Copy a ready-made Atlas script into Segment and add your key.
    • Customers created automatically: Customers identified in Segment are created or updated in Atlas.
    • Accounts from Segment: Companies sent from Segment are created or updated as Atlas accounts.
    • Activity in the timeline: Product events and page views appear in the customer's timeline, also inside their tickets.
    • Test before going live: Send sample events from Segment and check the result in Atlas.
    • Key control: Revoke a key at any time to stop Segment from sending data.

    What Segment sends to Atlas

    When Segment sends…ExampleWhat you see in Atlas
    IdentifyAlex signs up or logs inA new or updated customer, shown as "Customer created via Developer API" in the timeline. The "User ID" is the ID from your product
    TrackAlex completes a checkoutAn entry in the customer's timeline with the event's title, for example "Checkout Completed"
    PageAlex views your pricing pageA "Page Viewed" entry in the customer's timeline
    GroupAlex's company is setA new or updated account
    Important:
    Atlas only receives events that include a userId, the ID your product gives each customer. Events from anonymous visitors are skipped.

    How to connect Segment to Atlas

    Requirements:
    You need permission to create functions in your Segment workspace.

    Part 1: Create a Segment key in Atlas

    1. In Atlas, click the main menu button and select  "App Configuration" .
    2. Click "Integrations" and select "Segment".
    3. Under "Segment API Keys", click "Add Key".
    4. Copy the key, check "I have copied the key" and click "Save".
    Important:
    Atlas shows the key only once. Keep it somewhere safe until you paste it in Segment.

    Part 2: Build the destination function in Segment

    1. In Atlas, click "Connect Segment". Your Segment workspace opens.
    2. In Segment, go to "Connections > Catalog" and open the "Functions" tab.
    3. Click "Create Function", select "Destination" and click "Next: Build Function".
    4. Delete the sample code in the editor and paste the Atlas script below.
    5. In the third line, paste your key between the quotes: const SEGMENT_TO_ATLAS_TOKEN = 'your key';

    This is the Atlas script you copy. Scroll inside the box to see all of it, and copy it from the first line to the last. It's the same for every workspace: copy it as it is and only add your key. The script tells Segment what to do with each event: create customers (onIdentify), add events to the timeline (onTrack and onPage) and create accounts (onGroup).

    // Atlas destination function for Segment
    // Paste your key from Atlas (App Configuration > Integrations > Segment > Segment API Keys > Add Key)
    const SEGMENT_TO_ATLAS_TOKEN = '';
    const BASE_URL = 'https://api.atlas.so';
    const API_VERSION = 'v1';
     
    async function onIdentify(event, settings) {
      const endpoint = `${BASE_URL}/${API_VERSION}/customers/upsert`;
      let response;
      if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
      }
      if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
      }
      let firstName;
      let lastName;
      let fullName = event.traits.name;
      if (fullName) {
        firstName = fullName.split(' ')[0];
        lastName = fullName.substring(firstName.length).trim()
      } else {
        firstName = event.traits.firstName || event.traits.first_name
        lastName = event.traits.lastName || event.traits.last_name
      }
      const payload = {
        userId: event.userId,
        email: event.traits.email,
        firstName: firstName,
        lastName: lastName,
      };
      if (event.traits.phone) {
        payload['phoneNumber'] = event.traits.phone
      }
      if (event.traits.company) {
        payload['account'] = {
          name: event.traits.company.name,
          website: event.traits.company.domain,
          externalId: event.traits.company.id,
        };
      }
      try {
        response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
        });
        if (response.status >= 300) {
          throw new RetryError(`Failed with ${response.status}`);
        }
      } catch (error) {
        throw new RetryError(error.message);
      }
    }
     
    async function onTrack(event, settings) {
      const endpoint = `${BASE_URL}/${API_VERSION}/events`;
      let response;
      if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
      }
      if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
      }
      const atlasEvent = {
        objectType: 'CUSTOMER',
        objectId: event.userId,
        name: 'Event Tracked',
        description: event.properties.title || '',
        payload: { ...event.context, ...event.properties }
      };
      try {
        response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(atlasEvent)
        });
        if (response.status >= 500 || response.status === 429) {
          throw new RetryError(`Failed with ${response.status}`);
        }
      } catch (error) {
        throw new RetryError(error.message);
      }
    }
     
    async function onPage(event, settings) {
      const endpoint = `${BASE_URL}/${API_VERSION}/events`;
      let response;
      if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
      }
      if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
      }
      const atlasEvent = {
        objectType: 'CUSTOMER',
        objectId: event.userId,
        name: 'Page Viewed',
        description: event.properties.title || '',
        payload: { ...event.context, ...event.properties }
      };
      try {
        response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(atlasEvent)
        });
        if (response.status >= 500 || response.status === 429) {
          throw new RetryError(`Failed with ${response.status}`);
        }
      } catch (error) {
        throw new RetryError(error.message);
      }
    }
     
    async function onGroup(event, settings) {
      const endpoint = `${BASE_URL}/${API_VERSION}/accounts/upsert`;
      let response;
      if (!event.userId) {
        throw new EventNotSupported('Mandatory parameters are missing');
      }
      if (!SEGMENT_TO_ATLAS_TOKEN) {
        console.log('Bad Configuration - SEGMENT_TO_ATLAS_TOKEN - missing');
        return;
      }
      const payload = {
        externalId: event.groupId,
        name: event.traits.name,
        email: event.traits.email,
      };
      try {
        response = await fetch(endpoint, {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${SEGMENT_TO_ATLAS_TOKEN}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
        });
        if (response.status >= 300) {
          throw new RetryError(`Failed with ${response.status}`);
        }
      } catch (error) {
        throw new RetryError(error.message);
      }
    }

    Part 3: Test it and create the function

    1. In the test panel, click "customize the event yourself".
    2. Paste this sample Identify event and click "Run":
    3. Paste this sample Track event and click "Run" again:
    {
      "type": "identify",
      "userId": "test-001",
      "traits": {
        "name": "Alex Test",
        "email": "alex.segment@example.com"
      }
    }
    {
      "type": "track",
      "userId": "test-001",
      "event": "Checkout Completed",
      "properties": {
        "title": "Checkout Completed"
      }
    }
    1. When the output shows "Success" for both events, click "Next: Configure & Create".
    2. Name the function, for example "Atlas", add a short description and click "Create Function".

    Then connect the function to the Segment source that collects your product's data, so real events start flowing to Atlas.

    Part 4: See the result in Atlas

    1. In Atlas, open  "Customers"  and select the test customer, for example alex.segment@example.com.
    2. The timeline shows "Customer created via Developer API" (from the Identify event) and "Checkout Completed" (from the Track event).

    How to revoke a Segment key

    Revoke a key when you stop using it or if someone saw it. Segment can't send data with a revoked key.

    1. In Atlas, go to "App Configuration > Integrations > Segment".
    2. Open the key's actions menu and click "Revoke", then confirm.
    3. To see revoked keys, turn on "Show revoked".
    Important:
    If you revoke the key your function uses, create a new key and paste it in the function's code.

    FAQs & Troubleshooting

    Do I need a developer?

    Not to connect it. You copy a key and paste a script. Your developers already send events to Segment; this setup only forwards them to Atlas.

    What is the App ID on the Segment page?

    It identifies your Atlas workspace. It's the same app ID used in the install snippet. You don't need it for the destination function.

    Why don't I see the customer in Atlas?

    Check the following:

    • The event has a userId.
    • The key is pasted correctly in the script and isn't revoked.
    • The function's test output shows "Success".
    • The function is connected to your Segment source.

    Can I choose where Segment events appear?

    Yes. In  "App Configuration > Data > Custom events" , turn "Show in Timeline" and "Show in Session Recording" on or off for each event. Read How to manage custom events.

    Was this article helpful?