openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations User Properties 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: User Properties
  description: Operations for managing user properties
paths:
  /api/2/taxonomy/user-property:
    get:
      operationId: listUserProperties
      summary: Amplitude List All User Properties
      description: Retrieve all user properties in the project. Optionally include deleted user properties.
      tags:
      - User Properties
      parameters:
      - name: showDeleted
        in: query
        description: When true, include deleted user properties in the response.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPropertyListResponse'
              examples:
                listUserProperties200Example:
                  summary: Default listUserProperties 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - example_value
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createUserProperty
      summary: Amplitude Create a User Property
      description: Create a new user property in the tracking plan.
      tags:
      - User Properties
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - user_property
              properties:
                user_property:
                  type: string
                  description: The name of the user property.
                description:
                  type: string
                  description: A description of the user property.
                type:
                  type: string
                  description: The data type of the property.
                  enum:
                  - string
                  - number
                  - boolean
                  - enum
                  - any
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                createUserProperty200Example:
                  summary: Default createUserProperty 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '409':
          description: User property already exists
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/2/taxonomy/user-property/{user_property}:
    get:
      operationId: getUserProperty
      summary: Amplitude Get a User Property
      description: Retrieve a single user property by its name.
      tags:
      - User Properties
      parameters:
      - name: user_property
        in: path
        required: true
        description: The name of the user property.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProperty'
              examples:
                getUserProperty200Example:
                  summary: Default getUserProperty 200 response
                  x-microcks-default: true
                  value:
                    user_property: example_value
                    description: Example description text
                    type: standard
        '401':
          description: Unauthorized
        '404':
          description: User property not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateUserProperty
      summary: Amplitude Update a User Property
      description: Update an existing user property's metadata.
      tags:
      - User Properties
      parameters:
      - name: user_property
        in: path
        required: true
        description: The name of the user property to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: An updated description of the user property.
                new_user_property:
                  type: string
                  description: A new name for the user property.
                type:
                  type: string
                  description: The data type of the property.
                  enum:
                  - string
                  - number
                  - boolean
                  - enum
                  - any
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                updateUserProperty200Example:
                  summary: Default updateUserProperty 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '401':
          description: Unauthorized
        '404':
          description: User property not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteUserProperty
      summary: Amplitude Delete a User Property
      description: Delete a planned user property. This is intended for properties that have not yet received data.
      tags:
      - User Properties
      parameters:
      - name: user_property
        in: path
        required: true
        description: The name of the user property to delete.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                deleteUserProperty200Example:
                  summary: Default deleteUserProperty 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '401':
          description: Unauthorized
        '404':
          description: User property not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    UserPropertyListResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of user properties.
          items:
            $ref: '#/components/schemas/UserProperty'
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
    UserProperty:
      type: object
      properties:
        user_property:
          type: string
          description: The name of the user property.
        description:
          type: string
          description: A description of the user property.
        type:
          type: string
          description: The data type of the property.
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution