> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Mark an achievement as completed

> Mark an achievement as completed for a user.



## OpenAPI

````yaml https://api.trophy.so/v1/openapi post /achievements/{key}/complete
openapi: 3.1.0
info:
  title: Trophy
  version: 1.19.0
servers:
  - x-fern-server-name: Application API
    url: https://api.trophy.so/v1
    description: Application API
security: []
paths:
  /achievements/{key}/complete:
    servers:
      - url: https://api.trophy.so/v1
        description: Application API
    parameters:
      - $ref: '#/components/parameters/TenantId'
    post:
      tags:
        - Achievements
      summary: Mark an achievement as completed
      description: Mark an achievement as completed for a user.
      operationId: achievements_complete
      parameters:
        - name: key
          in: path
          description: Unique reference of the achievement as set when created.
          required: true
          schema:
            type: string
          example: finish-onboarding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/UpsertedUser'
                  description: The user that completed the achievement.
              required:
                - user
            examples:
              Successful operation:
                value:
                  user:
                    id: user-id
                    email: user@example.com
                    tz: Europe/London
                    subscribedToEmails: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AchievementCompletionResponse'
              examples:
                Successful operation:
                  value:
                    completionId: 0040fe51-6bce-4b44-b0ad-bddc4e123534
                    achievement:
                      id: 5100fe51-6bce-6j44-b0hs-bddc4e123682
                      trigger: api
                      name: Finish onboarding
                      description: Complete the onboarding process.
                      badgeUrl: https://example.com/badge.png
                      key: finish-onboarding
                      achievedAt: '2021-01-01T00:00:00Z'
                    points:
                      points-system-key:
                        id: 0040fe51-6bce-4b44-b0ad-bddc4e123534
                        name: XP
                        description: null
                        badgeUrl: null
                        total: 10
                        added: 10
                        awards:
                          - id: 0040fe51-6bce-4b44-b0ad-bddc4e123534
                            awarded: 10
                            date: '2021-01-01T00:00:00Z'
                            total: 10
                            trigger:
                              id: 0040fe51-6bce-4b44-b0ad-bddc4e123534
                              type: achievement
                              achievementName: Finish onboarding
                              points: 10
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Achievement Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Unprocessible Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: javascript
          source: >
            import { TrophyApiClient } from '@trophyso/node';


            const trophy = new TrophyApiClient({
              apiKey: 'YOUR_API_KEY'
            });


            const response = await
            trophy.achievements.complete("achievement-key", {
              user: {
                id: "user-id",
              }
            });
        - lang: python
          source: >
            from trophy import TrophyApi


            client = TrophyApi(api_key='YOUR_API_KEY')


            user = UpsertedUser(id="123")


            response = client.achievements.complete("achievement-key",
            user=user)
        - lang: go
          source: |
            import (
              "context"

              api "github.com/trophyso/trophy-go"
              trophyclient "github.com/trophyso/trophy-go/client"
              "github.com/trophyso/trophy-go/option"
            )

            client := trophyclient.NewClient(
              option.WithApiKey("YOUR_API_KEY"),
            )

            response, err := client.Achievements.Complete(
              context.TODO(),
              "achievement-key",
              &api.AchievementsCompleteRequest{
                User: &api.UpsertedUser{Id: "user-id"},
              },
            )
components:
  parameters:
    TenantId:
      name: Tenant-ID
      in: header
      description: >-
        The tenant identifier for multi-tenant organisations. Required when the
        organisation has multi-tenancy enabled. The value should be your
        internal ID for the tenant. Ignored for single-tenant organisations.
      required: false
      schema:
        type: string
      example: customer_12345
  schemas:
    UpsertedUser:
      title: Upserted User
      type: object
      description: An object with editable user fields.
      allOf:
        - $ref: '#/components/schemas/UpdatedUser'
        - type: object
          properties:
            id:
              type: string
              description: The ID of the user in your database. Must be a string.
              example: user-id
          required:
            - id
    AchievementCompletionResponse:
      title: AchievementCompletionResponse
      type: object
      properties:
        completionId:
          type: string
          description: The unique ID of the completion.
          example: 0040fe51-6bce-4b44-b0ad-bddc4e123534
        achievement:
          $ref: '#/components/schemas/UserAchievementResponse'
        points:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MetricEventPointsResponse'
          description: >-
            A map of points systems by key that were affected by this
            achievement completion.
      required:
        - completionId
        - achievement
        - points
    ErrorBody:
      title: ErrorBody
      type: object
      properties:
        error:
          type: string
      required:
        - error
    UpdatedUser:
      title: Updated User
      type: object
      description: An object with editable user fields.
      properties:
        email:
          type: string
          description: The user's email address. Required if subscribeToEmails is true.
          example: user@example.com
        name:
          type: string
          description: The name to refer to the user by in emails.
          example: User
        tz:
          type:
            - string
            - 'null'
          description: The user's timezone (used for email scheduling).
          example: Europe/London
        deviceTokens:
          type:
            - array
            - 'null'
          description: The user's device tokens, used for push notifications.
          items:
            type: string
            description: The device token.
          example:
            - token1
            - token2
        subscribeToEmails:
          type: boolean
          default: true
          description: >-
            Whether the user should receive Trophy-powered emails. If false,
            Trophy will not store the user's email address.
          example: true
        attributes:
          type: object
          additionalProperties:
            type: string
          description: >-
            User attributes as key-value pairs. Keys must match existing user
            attributes set up in the Trophy dashboard.
          example:
            department: engineering
            role: developer
    UserAchievementResponse:
      title: UserAchievementResponse
      type: object
      allOf:
        - $ref: '#/components/schemas/AchievementResponse'
        - type: object
          properties:
            achievedAt:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                The date and time the achievement was completed, in ISO 8601
                format. Null if the achievement has not been completed.
          required:
            - achievedAt
    MetricEventPointsResponse:
      title: MetricEventPointsResponse
      type: object
      description: Points system response for metric events and achievement completions.
      allOf:
        - $ref: '#/components/schemas/PointsResponse'
        - type: object
          properties:
            total:
              type: integer
              description: The user's total points
            level:
              description: >-
                The user's new level, included only when the level changed as a
                result of this event.
              oneOf:
                - $ref: '#/components/schemas/PointsLevel'
                - type: 'null'
            added:
              type: integer
              description: The points added by this event.
              example: 10
            awards:
              type: array
              description: Array of trigger awards that added points.
              items:
                $ref: '#/components/schemas/PointsAward'
          required:
            - total
            - added
            - awards
    AchievementResponse:
      title: AchievementResponse
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the achievement.
        name:
          type: string
          description: The name of this achievement.
        trigger:
          type: string
          enum:
            - metric
            - streak
            - api
            - achievement
          description: The trigger of the achievement.
        description:
          type:
            - string
            - 'null'
          description: The description of this achievement.
        badgeUrl:
          type:
            - string
            - 'null'
          description: >-
            The URL of the badge image for the achievement, if one has been
            uploaded.
        key:
          type: string
          description: >-
            The key used to reference this achievement in the API (only
            applicable if trigger = 'api')
        streakLength:
          type: integer
          description: >-
            The length of the streak required to complete the achievement (only
            applicable if trigger = 'streak')
        achievementIds:
          type: array
          items:
            type: string
          description: >-
            The IDs of the prerequisite achievements that must be completed to
            earn this achievement (only applicable if trigger = 'achievement')
        metricId:
          type: string
          description: >-
            The ID of the metric associated with this achievement (only
            applicable if trigger = 'metric')
        metricValue:
          type: number
          format: double
          description: >-
            The value of the metric required to complete the achievement (only
            applicable if trigger = 'metric')
        metricName:
          type: string
          description: >-
            The name of the metric associated with this achievement (only
            applicable if trigger = 'metric')
        userAttributes:
          type: array
          description: >-
            User attribute filters that must be met for this achievement to be
            completed.
          items:
            type: object
            properties:
              key:
                type: string
                description: The key of the user attribute.
                example: plan-type
              value:
                type: string
                description: The value of the user attribute.
                example: premium
            required:
              - key
              - value
        eventAttribute:
          type: object
          description: >-
            Deprecated. Event attribute filter that must be met for this
            achievement to be completed. Only present if the achievement has an
            event filter configured.
          deprecated: true
          properties:
            key:
              type: string
              description: The key of the event attribute.
              example: source
            value:
              type: string
              description: The value of the event attribute.
              example: mobile-app
          required:
            - key
            - value
        eventAttributes:
          type: array
          description: >-
            Event attribute filters that must be met for this achievement to be
            completed. Omitted for non-metric achievements.
          items:
            type: object
            properties:
              key:
                type: string
                description: The key of the event attribute.
                example: source
              value:
                type: string
                description: The value of the event attribute.
                example: mobile-app
            required:
              - key
              - value
      required:
        - id
        - name
        - trigger
        - description
        - badgeUrl
        - userAttributes
    PointsResponse:
      title: PointsResponse
      type: object
      description: Base points system fields shared across responses.
      properties:
        id:
          type: string
          description: The ID of the points system
        key:
          type: string
          description: The key of the points system
        name:
          type: string
          description: The name of the points system
        description:
          type:
            - string
            - 'null'
          description: The description of the points system
        badgeUrl:
          type:
            - string
            - 'null'
          description: The URL of the badge image for the points system
        maxPoints:
          type:
            - number
            - 'null'
          description: >-
            The maximum number of points a user can be awarded in this points
            system
      required:
        - id
        - key
        - name
        - description
        - badgeUrl
        - maxPoints
    PointsLevel:
      title: PointsLevel
      type: object
      description: A level within a points system.
      properties:
        id:
          type: string
          description: The ID of the level
        key:
          type: string
          description: The unique key of the level
        name:
          type: string
          description: The name of the level
        description:
          type: string
          description: The description of the level
        badgeUrl:
          type:
            - string
            - 'null'
          description: The URL of the badge image for the level
        points:
          type: integer
          description: The points threshold required to reach this level
      required:
        - id
        - key
        - name
        - description
        - badgeUrl
        - points
    PointsAward:
      title: PointsAward
      type: object
      properties:
        id:
          type: string
          description: The ID of the trigger award
        awarded:
          type: integer
          description: The points awarded by this trigger
        date:
          type: string
          description: The date these points were awarded, in ISO 8601 format.
        total:
          type: integer
          description: The user's total points after this award occurred.
        trigger:
          $ref: '#/components/schemas/PointsTrigger'
        boosts:
          type: array
          description: Array of points boosts that applied to this award.
          items:
            $ref: '#/components/schemas/PointsBoost'
    PointsTrigger:
      title: PointsTrigger
      type: object
      properties:
        id:
          type: string
          description: The ID of the trigger
        type:
          type: string
          description: The type of trigger
          enum:
            - metric
            - achievement
            - streak
            - time
            - user_creation
        points:
          type: integer
          description: The points awarded by this trigger.
        status:
          type: string
          enum:
            - active
            - inactive
            - archived
          description: The status of the trigger.
        achievementId:
          type: string
          description: >-
            The unique ID of the achievement associated with this trigger, if
            the trigger is an achievement.
        metricId:
          type: string
          description: >-
            The unique ID of the metric associated with this trigger, if the
            trigger is a metric.
        metricName:
          type: string
          description: If the trigger has type 'metric', the name of the metric
        metricThreshold:
          type: integer
          description: >-
            If the trigger has type 'metric', the threshold of the metric that
            triggers the points
        streakLengthThreshold:
          type: integer
          description: >-
            If the trigger has type 'streak', the threshold of the streak that
            triggers the points
        achievementName:
          type: string
          description: If the trigger has type 'achievement', the name of the achievement
        timeUnit:
          type: string
          enum:
            - hour
            - day
          description: >-
            If the trigger has type 'time', the unit of time after which to
            award points
        timeInterval:
          type: integer
          description: >-
            If the trigger has type 'time', the numer of units of timeUnit after
            which to award points
        userAttributes:
          type: array
          description: >-
            User attribute filters that must be met for this trigger to award
            points. Empty when the trigger has no user attribute filters
            configured.
          items:
            type: object
            properties:
              key:
                type: string
                description: The key of the user attribute.
                example: plan-type
              value:
                type: string
                description: The required value of the user attribute.
                example: premium
            required:
              - key
              - value
        eventAttribute:
          type: object
          description: >-
            Deprecated. Event attribute filter that must be met for this trigger
            to award points. Only present if the trigger has an event filter
            configured.
          deprecated: true
          properties:
            key:
              type: string
              description: The key of the event attribute.
              example: source
            value:
              type: string
              description: The required value of the event attribute.
              example: mobile-app
          required:
            - key
            - value
        eventAttributes:
          type: array
          description: >-
            If the trigger has type 'metric', the event attributes that must
            match for the trigger to award points. Empty when the trigger is
            metric-based and has no event attribute filters. Omitted for
            non-metric triggers.
          items:
            type: object
            properties:
              key:
                type: string
                description: The key of the event attribute.
                example: source
              value:
                type: string
                description: The required value of the event attribute.
                example: mobile-app
            required:
              - key
              - value
        created:
          type: string
          format: date-time
          description: The date and time the trigger was created, in ISO 8601 format.
        updated:
          type: string
          format: date-time
          description: The date and time the trigger was last updated, in ISO 8601 format.
      required:
        - id
        - type
        - points
        - status
        - userAttributes
        - created
        - updated
    PointsBoost:
      title: PointsBoost
      type: object
      properties:
        id:
          type: string
          description: The ID of the points boost
        name:
          type: string
          description: The name of the points boost
        status:
          type: string
          enum:
            - active
            - scheduled
            - finished
          description: The status of the points boost
        start:
          type: string
          description: The start date of the points boost
        end:
          type:
            - string
            - 'null'
          description: The end date of the points boost
        multiplier:
          type: number
          description: The multiplier of the points boost
        rounding:
          type: string
          enum:
            - down
            - up
            - nearest
          description: The rounding method of the points boost
      required:
        - id
        - name
        - status
        - start
        - end
        - multiplier
        - rounding
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````