openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations Users API
  description: The Amplitude Attribution API allows developers to send attribution campaign events to Amplitude from ad networks, attribution providers, or custom marketing tools. It associates users with the campaigns, channels, and creatives that drove their acquisition or re-engagement. This API is used to enrich Amplitude user profiles with marketing attribution data for campaign performance analysis and ROI measurement.
  version: '2'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
servers:
- url: https://api2.amplitude.com
  description: Amplitude US Production Server
- url: https://api.eu.amplitude.com
  description: Amplitude EU Production Server
security: []
tags:
- name: Users
  description: SCIM user provisioning operations
paths:
  /scim/1/Users:
    get:
      operationId: listScimUsers
      summary: Amplitude List SCIM Users
      description: Retrieve a paginated list of users provisioned in Amplitude. Supports SCIM filtering to search for specific users by attributes such as email or display name.
      tags:
      - Users
      parameters:
      - name: filter
        in: query
        description: A SCIM filter expression to narrow the results. For example, userName eq "user@example.com".
        schema:
          type: string
      - name: startIndex
        in: query
        description: The 1-based index of the first result in the current set of results. Default is 1.
        schema:
          type: integer
          default: 1
      - name: count
        in: query
        description: The number of results per page. Default varies by implementation.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUserListResponse'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createScimUser
      summary: Amplitude Create a SCIM User
      description: Provision a new user in Amplitude via SCIM. The user is created with the specified attributes and can be assigned to groups. Typically called by identity providers during automated provisioning.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: Bad request - invalid user data
        '401':
          description: Unauthorized
        '409':
          description: User already exists
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scim/1/Users/{user_id}:
    get:
      operationId: getScimUser
      summary: Amplitude Get a SCIM User
      description: Retrieve a single user by their SCIM user ID.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/scimUserId'
      responses:
        '200':
          description: Success
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '401':
          description: Unauthorized
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: replaceScimUser
      summary: Amplitude Replace a SCIM User
      description: Replace all attributes of an existing user with the provided values. Any attributes not included in the request body are reset to their default values.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/scimUserId'
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimUserRequest'
      responses:
        '200':
          description: Success
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateScimUser
      summary: Amplitude Update a SCIM User
      description: Partially update a user's attributes. Only the specified attributes are modified. Commonly used for activating or deactivating users.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/scimUserId'
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/ScimPatchRequest'
      responses:
        '200':
          description: Success
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteScimUser
      summary: Amplitude Delete a SCIM User
      description: Deactivate and remove a user from Amplitude. This is typically called by identity providers when a user is offboarded.
      tags:
      - Users
      parameters:
      - $ref: '#/components/parameters/scimUserId'
      responses:
        '204':
          description: User deleted
        '401':
          description: Unauthorized
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ScimUser:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: The SCIM schema URIs for this resource.
        id:
          type: string
          description: The SCIM unique identifier for the user.
        userName:
          type: string
          format: email
          description: The user's email address, used as the primary identifier.
        name:
          type: object
          description: The user's name components.
          properties:
            givenName:
              type: string
              description: The user's first name.
            familyName:
              type: string
              description: The user's last name.
        emails:
          type: array
          description: Array of email addresses for the user.
          items:
            type: object
            properties:
              value:
                type: string
                format: email
                description: The email address.
              primary:
                type: boolean
                description: Whether this is the primary email address.
              type:
                type: string
                description: The type of email address such as work or personal.
        active:
          type: boolean
          description: Whether the user account is active.
        groups:
          type: array
          description: Array of groups the user belongs to.
          items:
            type: object
            properties:
              value:
                type: string
                description: The group ID.
              display:
                type: string
                description: The group display name.
        meta:
          type: object
          description: SCIM metadata for the resource.
          properties:
            resourceType:
              type: string
              description: The type of SCIM resource.
            created:
              type: string
              format: date-time
              description: The date and time the resource was created.
            lastModified:
              type: string
              format: date-time
              description: The date and time the resource was last modified.
    ScimUserListResponse:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: The SCIM schema URIs for this response.
        totalResults:
          type: integer
          description: The total number of matching users.
        startIndex:
          type: integer
          description: The 1-based index of the first result.
        itemsPerPage:
          type: integer
          description: The number of results returned in this page.
        Resources:
          type: array
          description: Array of SCIM user resources.
          items:
            $ref: '#/components/schemas/ScimUser'
    ScimPatchRequest:
      type: object
      required:
      - schemas
      - Operations
      properties:
        schemas:
          type: array
          items:
            type: string
          description: The SCIM patch operation schema URI, typically urn:ietf:params:scim:api:messages:2.0:PatchOp.
        Operations:
          type: array
          description: Array of patch operations to apply.
          items:
            type: object
            properties:
              op:
                type: string
                description: The operation to perform.
                enum:
                - add
                - remove
                - replace
              path:
                type: string
                description: The attribute path to apply the operation to.
              value:
                description: The value to use for the operation.
    ScimUserRequest:
      type: object
      required:
      - schemas
      - userName
      properties:
        schemas:
          type: array
          items:
            type: string
          description: The SCIM schema URIs, typically urn:ietf:params:scim:schemas:core:2.0:User.
        userName:
          type: string
          format: email
          description: The user's email address.
        name:
          type: object
          properties:
            givenName:
              type: string
              description: The user's first name.
            familyName:
              type: string
              description: The user's last name.
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
                description: The email address.
              primary:
                type: boolean
                description: Whether this is the primary email.
              type:
                type: string
                description: The type of email.
        active:
          type: boolean
          description: Whether the user account should be active.
  parameters:
    scimUserId:
      name: user_id
      in: path
      required: true
      description: The SCIM user ID.
      schema:
        type: string
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution