segment Links API

openapi: 3.2.0
info:
  title: Segment Profile Links API
  description: The Segment Profile API provides endpoints to read user-level and account-level customer data from Segment Unify. Developers can query the entire user or account object programmatically, including external IDs, traits, and events that make up a user's journey. The API uses basic authentication and typically delivers p95 response times under 200ms for the traits endpoint. It is commonly used for real-time personalization and customer data retrieval.
  version: 1.0.0
  contact:
    name: Segment Support
    url: https://segment.com/help/
  termsOfService: https://segment.com/legal/terms/
servers:
- url: https://profiles.segment.com/v1/spaces/{spaceId}
  description: Production Server
  variables:
    spaceId:
      description: The ID of the Segment Unify space.
      default: ''
security:
- basicAuth: []
tags:
- name: Links
  description: Operations for retrieving linked profiles and relationships.
paths:
  /collections/users/profiles/{externalId}/links:
    get:
      operationId: getUserLinks
      summary: Get user links
      description: Returns the linked profiles for a user, such as account-level profiles that the user belongs to.
      tags:
      - Links
      parameters:
      - $ref: '#/components/parameters/ExternalId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: User links retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        to_collection:
                          type: string
                          description: The collection the link points to.
                        external_ids:
                          type: array
                          items:
                            $ref: '#/components/schemas/ExternalId'
                          description: External IDs of the linked profile.
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    NotFound:
      description: The requested profile was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code.
                  message:
                    type: string
                    description: A human-readable error message.
    RateLimited:
      description: Too many requests. The Profile API enforces rate limits per space.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code.
                  message:
                    type: string
                    description: A human-readable error message.
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code.
                  message:
                    type: string
                    description: A human-readable error message.
  parameters:
    ExternalId:
      name: externalId
      in: path
      required: true
      description: The external ID used to look up the profile. Format is type:value, such as user_id:abc123, email:user@example.com, or anonymous_id:xyz789.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: The maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 100
    Next:
      name: next
      in: query
      description: Pagination cursor to retrieve the next page of results.
      schema:
        type: string
  schemas:
    ExternalId:
      type: object
      properties:
        id:
          type: string
          description: The value of the external ID.
        type:
          type: string
          description: The type of external ID.
          enum:
          - user_id
          - anonymous_id
          - email
          - phone
          - cross_domain_id
          - android.id
          - android.idfa
          - ios.id
          - ios.idfa
        source_id:
          type: string
          description: The source that provided this external ID.
        collection:
          type: string
          description: The collection this external ID belongs to.
        created_at:
          type: string
          format: date-time
          description: When this external ID was first seen.
        encoding:
          type: string
          description: The encoding of the ID value.
    Cursor:
      type: object
      properties:
        url:
          type: string
          description: The URL to retrieve the next page.
        has_more:
          type: boolean
          description: Whether there are more results.
        next:
          type: string
          description: The cursor value for the next page.
        limit:
          type: integer
          description: The number of items per page.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the Profile API access token as the username and an empty password. Access tokens are generated in the Segment Unify space settings.
externalDocs:
  description: Segment Profile API Documentation
  url: https://segment.com/docs/unify/profile-api/