openapi: 3.2.0
info:
  version: ''
  title: Namely Events API
  description: Move your app forward with the Namely API Move your app forward with the Namely API
tags:
- name: Events
paths:
  /events:
    get:
      operationId: GET_events
      summary: Get all Events
      tags:
      - Events
      description: Returns all events, paginated. Linked to the event is an array of any profiles that commented on the event. Only events associated with the profiles of active employees are eligible to appear.
      parameters:
      - name: limit
        in: query
        description: Limit of records to be retrieved
        schema:
          type: integer
          default: ''
          maximum: 30
      - name: after
        in: query
        description: <code>id</code> of the first record BEFORE the events you want to retrieve
        schema:
          type: string
      - name: filter[type]
        in: query
        description: The type of event you want to retrieve; examples include `birthday`, `announcement`, `recent_arrival` or `anniversary`
        schema:
          type: string
      - name: profile_id
        in: query
        description: <code>id</code> of the profile that you wish to pull all associated events from
        schema:
          type: string
      - name: order
        in: query
        description: This parameter allows you to change how results are ordered. Valid values are `asc` and `desc` - It defaults to `desc`
        schema:
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  meta:
                    type: object
                    $ref: '#/components/schemas/Events_Meta'
                  links:
                    type: object
                    properties:
                      events.profile:
                        $ref: '#/components/schemas/Link'
                      events.comments:
                        $ref: '#/components/schemas/Link'
                      events.file:
                        $ref: '#/components/schemas/Link'
                      comments.profile:
                        $ref: '#/components/schemas/Link'
                      profile.image:
                        $ref: '#/components/schemas/Link'
                  linked:
                    type: object
                    properties:
                      profiles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Profile'
                      comments:
                        type: array
                        items:
                          $ref: '#/components/schemas/Comment'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
      security:
      - Authorization: []
    post:
      operationId: POST_events
      summary: Create an Announcement
      tags:
      - Events
      description: 'Creates an announcement. Other event types are auto-generated and cannot be manually created.


        The file parameters allow you to include a file which is located in the announcement. As with uploading a file to a profile, the file must be previously uploaded via the `file create` endpoint.'
      responses:
        '201':
          description: Create Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  meta:
                    type: object
                    $ref: '#/components/schemas/Events_Meta'
                  links:
                    type: object
                    properties:
                      events.profile:
                        $ref: '#/components/schemas/Link'
                      events.comments:
                        $ref: '#/components/schemas/Link'
                      events.file:
                        $ref: '#/components/schemas/Link'
                      comments.profile:
                        $ref: '#/components/schemas/Link'
                      profile.image:
                        $ref: '#/components/schemas/Link'
                  linked:
                    type: object
                    properties:
                      profiles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Profile'
                      comments:
                        type: array
                        items:
                          $ref: '#/components/schemas/Comment'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
      security:
      - Authorization: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Create_Event'
  /events/{id}:
    parameters:
    - name: id
      in: path
      description: id of event.
      required: true
      schema:
        type: string
    get:
      operationId: GET_events-id
      summary: Get an Event
      tags:
      - Events
      description: Returns information about a single event.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  meta:
                    type: object
                    $ref: '#/components/schemas/Events_Meta'
                  links:
                    type: object
                    properties:
                      events.profile:
                        $ref: '#/components/schemas/Link'
                      events.comments:
                        $ref: '#/components/schemas/Link'
                      events.file:
                        $ref: '#/components/schemas/Link'
                      comments.profile:
                        $ref: '#/components/schemas/Link'
                      profile.image:
                        $ref: '#/components/schemas/Link'
                  linked:
                    type: object
                    properties:
                      profiles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Linked_Profile'
                      comments:
                        type: array
                        items:
                          $ref: '#/components/schemas/Comment'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
      security:
      - Authorization: []
components:
  schemas:
    Salary:
      title: Salary
      type: object
      properties:
        currency_type:
          description: currency of the profile's <strong>current</strong> salary; <code>null</code> if never provided or no <strong>current</strong> salary; cannot be <code>null</code> if any other salary keys provided
          type: string
        date:
          description: start date of the profile's <strong>current</strong> salary; <code>null</code> if never provided or no <strong>current</strong> salary; cannot be <code>null</code> if any other salary keys provided
          type: string
        guid:
          description: unique identifier of the profile's <strong>current</strong> salary; <code>null</code> if never provided or no <strong>current</strong> salary; cannot be <code>null</code> if any other salary keys provided
          type: string
        pay_group_id:
          description: unique identifier of the pay group associated with the profile's <strong>current</strong> salary; <code>null</code> if never provided or no <strong>current</strong> salary
          type: integer
        payroll_job_id:
          description: unique identifier of the payroll job associated with the profile's <strong>current</strong> salary; <code>null</code> if never provided or no <strong>current</strong> salary
          type: string
        rate:
          description: rate of the profile's <strong>current</strong> salary; valid values include <code>annually</code>, <code>weekly</code>, <code>biweekly</code>, <code>bimonthly</code>, <code>semimonthly</code>, <code>monthly</code>, <code>quarterly</code>, <code>semiannually</code>, and <code>thirteen_monthly</code>; <code>null</code> if never provided; blank if provided then deleted; cannot be <code>null</code> if any other salary keys provided
          type: string
        yearly_amount:
          description: 'annualized amount ("amount_raw" * # of pay periods based on the "rate") of the profile''s <strong>current</strong> salary; all salaries are annualized; <code>null</code> if never provided; blank if provided then deleted; cannot be <code>null</code> if any other salary keys provided'
          type: integer
        hourly:
          description: true if the salary is hourly, and false if yearly; cannot be <code>null</code> if any other salary keys provided. Known as is_hourly elsewhere in the app.
          type: boolean
        amount_raw:
          description: returns the amount as it was inputted on the UI; if yearly, will be the amount per pay period; if hourly, will be the hourly rate; cannot be <code>null</code> if any other salary keys provided
          type: string
        payroll_company:
          type: string
          description: The Payroll Company associated with this salary. Required if multiple Payroll Companies. "Company name" defaults to first Payroll Company.
        payroll_job:
          type: string
          description: Name of the Payroll Job for this Salary. Required if multiple Payroll Companies. Value of "Job name" will take first Payroll Job from specified Payroll Company.
    Create_Event_Payload:
      title: Create Event Payload
      type: object
      properties:
        content:
          type: string
          description: 'the content of the announcement; formatted in markdown; to @mention a profile, use format: <code>[full_name](/people/{profile_id})</code> where {profile_id} is the <code>id</code> of the profile you want to mention'
        is_appreciation:
          type: boolean
          description: if <code>true</code>, any @mentioned profile will be appreciated
          default: 'false'
        file_id:
          type: string
        email_all:
          type: boolean
          description: if <code>true</code>, will send an email to all active profiles per their company email address; will only be successful is token bearer has the corresponding permissions
          default: 'false'
      required:
      - content
    Healthcare:
      title: Healthcare
      type: object
      properties:
        beneficiary:
          description: relationship of the profile's healthcare plan's beneficiary to the profile; valid values include <code>Employee Only</code>, <code>Employee/Child</code>, <code>Employee/Spouse</code>, <code>Family</code>, <code>Not Applicable</code>, and <code>Waive</code>; blank if never provided or provided then deleted; cannot be <code>null</code> if any other <code>healthcare</code> keys provided
          type: string
        amount:
          description: amount of the profile's healthcare plan; numbers only; cannot be <code>null</code> if any other <code>healthcare</code> keys provided
          type: string
        currency_type:
          description: currency type of the profile's healthcare plan amount; default <code>USD</code>
          type: string
    Image:
      title: Image
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the image
        filename:
          type: string
          description: image's file name
        mime_type:
          type: string
          description: image type
        original:
          type: string
          description: link of image with original resolution
        thumbs:
          $ref: '#/components/schemas/Thumb'
    Linked_Profile:
      title: Linked Profile
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        user_status:
          type: string
        updated_at:
          type: integer
        created_at:
          type: integer
        preferred_name:
          type: string
        image:
          type: object
          items:
            $ref: '#/components/schemas/Image'
        full_name:
          type: string
    File:
      title: File
      type: object
      properties:
        id:
          type: string
        filename:
          type: string
        mime_type:
          type: string
        original:
          type: string
        thumbs:
          type: array
          items:
            $ref: '#/components/schemas/Thumb'
    Comment:
      title: Comment
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the comment
        content:
          type: string
          description: content of the comment, displayed in markdown
        html_content:
          type: string
          description: content of the comment, displayed in HTML
        created_at:
          type: integer
          description: epoch time that the comment was created
        can_destroy:
          type: boolean
          description: <code>true</code> if the token bearer has a role with permission to delete the comment; will always be <code>true</code> for one's own comment
        links:
          type: object
          properties:
            profile:
              type: string
        utc_offset:
          type: integer
          description: the hour difference between UTC and the main office of the company
        likes_count:
          type: integer
          description: total number of likes on comment
        liked_by_current_profile:
          type: boolean
          description: <code>true</code> if the token bearer has liked this comment
    Dental:
      title: Dental
      type: object
      properties:
        beneficiary:
          description: relationship of the profile's dental plan's beneficiary to the profile; valid values include <code>Employee Only</code>, <code>Employee/Child</code>, <code>Employee/Spouse</code>, <code>Family</code>, <code>Not Applicable</code>, and <code>Waive</code>; blank if never provided or provided then deleted; cannot be <code>null</code> if any other <code>dental</code> keys provided
          type: string
        amount:
          description: amount of the profile's dental plan; numbers only; cannot be <code>null</code> if any other <code>dental</code> keys provided
          type: string
        currency_type:
          description: currency type of the profile's dental plan amount; default <code>USD</code>
          type: string
    Thumb:
      title: Thumb
      type: object
      description: different resolutions of the image
      properties:
        75x75:
          type: string
        75x75c:
          type: string
        150x150:
          type: string
        150x150c:
          type: string
        300x300:
          type: string
        300x300c:
          type: string
        450x450:
          type: string
        550x450c:
          type: string
        800x800:
          type: string
        800x800c:
          type: string
    Events_Meta:
      title: Events Meta
      type: object
      properties:
        response:
          description: HTTP response
          type: integer
        use_comments:
          description: <code>true</code> if the company has commenting enabled on the home feed; same on the <code>event</code> object
          type: boolean
        use_updates:
          description: <code>true</code> if the token bearer has a role with permission to post announcements on the home feed
          type: boolean
        use_mentions:
          description: <code>true</code> if the company has mentioning enabled on the home feed
          type: boolean
        use_appreciations:
          description: <code>true</code> if the company has appreciations enabled on the home feed
          type: boolean
        use_likes:
          description: <code>true</code> if the company has likes enabled on the home feed
          type: boolean
        count:
          description: number of events returned on the page
          type: integer
    Group_Link:
      title: Group Link
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the group
        name:
          type: string
          description: name/label of the group
    Home:
      title: Home
      type: object
      description: fields represent the entire home address
      properties:
        address1:
          type: string
          description: address line 1 of the home address
        address2:
          type: string
          description: address line 2 of the home address
        city:
          type: string
          description: city of the home address
        state_id:
          type: string
          description: 'state of the home address; for US, must be the 2-digit code; for other countries, refer to the #docTextSection:7izuT4kPbi3FngZbD endpoints'
        country_id:
          type: string
          description: '"US" for the US; must be the ISO Alpha-2 code; for other countries, refer to the #docTextSection:7izuT4kPbi3FngZbD endpoints or just use the ISO Alpha-2 code'
        zip:
          type: string
          description: zip or postal code of the home address
    Team_Link:
      title: Team Link
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the team
        name:
          type: string
          description: name/label of the team
    Office:
      title: Office
      type: object
      description: these fields represent the entire office address and are inherited from the "Office Location" group assigned to the profile
      properties:
        address1:
          type: string
          description: address line 1 of the office address
        address2:
          type: string
          description: address line 2 of the office address
        city:
          type: string
          description: city of the office address
        state_id:
          type: string
          description: 'state of the office address; for US, must be the 2-digit code; for other countries, refer to the #docTextSection:7izuT4kPbi3FngZbD endpoints'
        country_id:
          type: string
          description: '"US" for the US; must be the ISO Alpha-2 code; for other countries, refer to the #docTextSection:7izuT4kPbi3FngZbD endpoints or just use the ISO Alpha-2 code'
        zip:
          type: string
          description: zip or postal code of the office address
        phone:
          type: string
          description: phone number associated with the office location
    Profile:
      title: Profile
      type: object
      properties:
        id:
          description: unique identifier of the profile
          type: string
        email:
          description: company email of the profile
          type: string
        first_name:
          description: first name of the profile
          type: string
        last_name:
          description: last name of the profile
          type: string
        user_status:
          description: user status of the profile; valid values in the API are <code>active</code>, <code>pending</code>, and <code>inactive</code>
          type: string
        updated_at:
          description: epoch time that the profile was updated; equal to <code>create_at</code> if never updated
          type: integer
        created_at:
          description: epoch time that the profile was created
          type: integer
        preferred_name:
          description: preferred name of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        image:
          $ref: '#/components/schemas/Image'
        full_name:
          description: combination of <code>first_name</code> and <code>last_name</code>
          type: string
        job_title:
          $ref: '#/components/schemas/Job_Title_Link'
        reports_to:
          description: information regarding the profile to whom the profile of this object reports
          type: array
          items:
            type: object
            properties:
              id:
                description: unique identifier of the profile to whom the profile of this object reports; <code>no_guid</code> if null; cannot be <code>null</code> if any other <code>reports_to</code> keys provided
                type: string
              first_name:
                description: first name of the profile to whom the profile of this object reports; <code>Nobody</code> if null; cannot be <code>null</code> if any other <code>reports_to</code> keys provided
                type: string
              last_name:
                description: last name of the profile to whom the profile of this object reports; <code>Nobody</code> if null; cannot be <code>null</code> if any other <code>reports_to</code> keys provided
                type: string
              email:
                description: company email of the profile to whom the profile of this object reports; <code>None</code> if null; cannot be <code>null</code> if any other <code>reports_to</code> keys provided
                type: string
        employee_type:
          description: employee type of the profile; valid values include <code>Full Time</code>, <code>Part Time</code>, <code>Intern</code>, <code>Contractor</code>, <code>Freelance</code>
          type: object
          properties:
            title:
              type: string
        access_role:
          description: returns the type of access_role assigned to the profile
          type: string
        ethnicity:
          description: self described ethnicity of the profile; <code>null</code> if never provided
          type:
          - string
          - 'null'
        links:
          type: object
          properties:
            job_title:
              type: object
              $ref: '#/components/schemas/Job_Title_Link'
            groups:
              type: array
              items:
                $ref: '#/components/schemas/Group_Link'
            teams:
              type: array
              items:
                $ref: '#/components/schemas/Team_Link'
            ? ''
            : type: string
        middle_name:
          description: middle name of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        gender:
          description: gender of the profile; <code>null</code> if never provided; valid values include <code>Male</code> and <code>Female</code>
          type: string
        job_change_reason:
          description: job change reason of the profile; <code>null</code> if never provided; valid values include <code>New Hire</code>, <code>Salary Change</code>, <code>Promotion</code>, and <code>Transfer</code>
          type: string
        terminated_reason:
          description: terminated reason of the profile; <code>null</code> if never provided
          type: string
        start_date:
          description: start date of the profile; format <code>YYYY-MM-DD</code>
          type: string
        departure_date:
          description: departure date of the profile; format <code>YYYY-MM-DD</code>; blank if never provided or provided then deleted
          type: string
        employee_id:
          description: employee id of the profile; blank if never provided or provided then deleted
          type: string
        personal_email:
          description: employee id of the profile; blank if never provided or provided then deleted
          type: string
        dob:
          description: date of birth of the profile; format <code>YYYY-MM-DD</code>; blank if never provided or provided then deleted
          type: string
        ssn:
          description: ssn of the profile; blank if never provided or provided then deleted
          type: string
        marital_status:
          description: marital status of the profile; <code>null</code> if never provided; valid values include <code>Single</code>, <code>Married</code>, <code>Civil Partnership</code>, <code>Separated</code>, and <code>Divorced</code>
          type: string
        bio:
          description: bio of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        asset_management:
          description: list of assets on the profile; blank if never provided or provided then deleted; valid values include <code>Laptop</code>, <code>Cell Phone</code>, <code>Building Keys</code>, <code>Corporate Card</code>, and <code>Air Card</code>
          type: string
        laptop_asset_number:
          description: laptop asset number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        corporate_card_member:
          description: corporate card number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        key_tag_number:
          description: key tag number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        linkedin_url:
          description: linkedin_url of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        office_main_number:
          description: office main number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        office_direct_dial:
          description: office direct dial number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        office_phone:
          description: office phone number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        office_fax:
          description: office fax number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        office_company_mobile:
          description: office company mobile phone number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        home_phone:
          description: home phone number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        mobile_phone:
          description: mobile phone number of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        home:
          $ref: '#/components/schemas/Home'
        office:
          $ref: '#/components/schemas/Office'
        emergency_contact:
          description: name of the profile's emergency contact; <code>null</code> if never provided; blank if provided then deleted
          type: string
        emergency_contact_phone:
          description: phone number of the profile's emergency contact; <code>null</code> if never provided; blank if provided then deleted
          type: string
        resume:
          description: resume of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        current_job_description:
          description: current job description of of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        job_description:
          description: current job description of of the profile; <code>null</code> if never provided; blank if provided then deleted
          type: string
        salary:
          $ref: '#/components/schemas/Salary'
        healthcare:
          $ref: '#/components/schemas/Healthcare'
        healthcare_info:
          description: description of the profile's healthcare plan; <code>null</code> if never provided; blank if provided then deleted
          type: string
        dental:
          $ref: '#/components/schemas/Dental'
        dental_info:
          description: description of the profile's dental plan; <code>null</code> if never provided; blank if provided then deleted
          type: string
        vision_plan_info:
          description: description of the profile's vision plan; <code>null</code> if never provided; blank if provided then deleted
          type: string
        life_insurance_info:
          description: description of the profile's life insurance plan; <code>null</code> if never provided; blank if provided then deleted
          type: string
        namely_time_employee_role:
          description: only applies to companies using Namely Time
          type: string
        namely_time_manager_role:
          description: only applies to companies using Namely Time
          type: string
    Link:
      title: Link
      type: object
      properties:
        type:
          type: string
    Job_Title_Link:
      title: Job Title Link
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the job title
        title:
          type: string
          description: name/label of the job title
    Create_Event:
      title: Create Event
      required:
      - events
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Create_Event_Payload'
    Event:
      title: Event
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the event
        href:
          type: string
          description: a link to the event on the web
        type:
          type: string
          description: 'the type of event: <code>announcement</code> (posted by a profile) or <code>birthday</code>, <code>anniversary</code>, <code>recent_arrival</code> (auto-generated)'
        time:
          type: integer
          description: epoch time that the event was created/generated
        ufc_offset:
          type: integer
          description: the hour difference between UTC and the main office of the company
        content:
          type: string
          description: 'content of the post, displayed in markdown; null for anything but type: <code>announcement</code>'
        html_content:
          type: string
          description: 'content of the post, displayed in HTML; null for anything but type: <code>announcement</code>'
        years_at_company:
          type: integer
          description: 'number of years related profile has been at the company; null for anything but: <code>anniversary</code>'
        use_comments:
          type: boolean
          description: <code>true</code> if the company has commenting enabled on the home feed; same as in <code>meta</code>
        can_comment:
          type: boolean
          description: <code>true</code> if the token bearer has a role with permission to comment on events on the home feed (will be same value on all events)
        can_destroy:
          type: boolean
          description: <code>true</code> if the token bearer has a role with permission to delete the event; will always be <code>true</code> for one's own announcement
        links:
          type: object
          properties:
            profile:
              type: string
              description: profile id of the profile related to the event; profile that created the <code>announcement</code> or profile associated with a <code>birthday</code>, <code>anniversary</code>, or <code>recent_arrival
            comments:
              type: array
              description: list of unique identifiers for each comment associated with the event; 0 to many
              items:
                type: string
            file:
              type: string
              description: 'unique identifiers of a file associated with the event (photo, document, etc.); zero to one; null for anything but type: <code>announcement</code>'
            appreciations:
              type:
              - string
              - array
              description: '<code>id</code> of any profiles "appreciated" in the content of the event; all "mentioned" profiles in the content of an appreciation announcement will also be listed here; zero to many; null for anything but type: <code>announcement</code>; null if event is not an appreciation'
              items:
                type: string
        can_like:
          type: boolean
          description: <code>true</code> if the token bearer has a role with permission to like events on the home feed (will be same value on all events)
        likes_count:
          type: integer
          description: total number of likes on event
        liked_by_current_profile:
          type: boolean
          description: <code>true</code> if the token bearer has liked this event
  securitySchemes:
    Authorization:
      name: Authorization
      type: apiKey
      in: header