Namely Profiles API

openapi: 3.2.0
info:
  version: ''
  title: Namely Profiles API
  description: Move your app forward with the Namely API Move your app forward with the Namely API
tags:
- name: Profiles
paths:
  /profiles:
    get:
      operationId: GET_profiles
      summary: Get all Profiles
      tags:
      - Profiles
      description: 'Returns all active and inactive employee profiles in the same format as the #endpoint:wn3pJ3WtCYWuuBL6r endpoint.


        Every client-created custom field (the token bearer has permission to see) will appear as key at the bottom of the profile object.


        As a note, the following fields will always be returned in the API response, regardless of user permissions:


        1. id

        2. email

        3. first_name

        4. last_name

        5. user_status

        6. updated_at

        7. created_at

        8. preferred_name

        9. full_name

        10. job_title



        These will NOT be exposed to the user in the UI if their permissions are set correctly.


        ### Important Note About the Endpoint


        Please ensure you''re paginating the response of the GET `/profiles` endpoint to ensure optimal performance avoid possible time-outs.


        **Examples:**

        1. `https://clientname.namely.com/api/v1/profiles.json?page=1&per_page=20&filter[user_status]=active`

        2. `https://clientname.namely.com/api/v1/profiles.json?page=2&per_page=20&filter[user_status]=active`

        3. `https://clientname.namely.com/api/v1/profiles.json?page=3&per_page=20&filter[user_status]=active`


        **Notes:**

        1. If you do not specify the `per_page` value, this will default to 30. The max possible is 50.

        2. If the response returns with less than the number of profiles requested (or none), the `count` in the `meta` object will be 0, and the `profiles` key will return an empty array.'
      parameters:
      - name: page
        in: query
        description: the page of information you'd like to receive.
        required: false
        schema:
          type: integer
      - name: per_page
        in: query
        description: the number of employees to retrieve when using pagination; default is 30 and the limit is 50.
        required: false
        schema:
          type: integer
      - name: profile_format
        in: query
        description: format of the profile object; only <code>short</code> is supported - returns a truncated version of the profile object
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: sort order of profiles; valid values - <code>first_name</code>, <code>last_name</code>, <code>created_at</code>, <code>updated_at</code>; prepend with a - (minus) sign to reverse the order
        required: false
        schema:
          type: string
      - name: filter[first_name]
        in: query
        description: returns only profiles with the defined first name
        required: false
        schema:
          type: string
      - name: filter[last_name]
        in: query
        description: returns only profiles with the defined last name
        required: false
        schema:
          type: string
      - name: filter[email]
        in: query
        description: returns only profiles with the defined (company) email
        required: false
        schema:
          type: string
      - name: filter[personal_email]
        in: query
        description: returns only profiles with the defined personal email
        required: false
        schema:
          type: string
      - name: filter[job_title]
        in: query
        description: returns only profiles with the defined job title; must be the job_title's <code>title</code>
        required: false
        schema:
          type: string
      - name: filter[reports_to]
        in: query
        description: <code>id</code> of the profile for whose direct reports you to view; returns only those profiles
        required: false
        schema:
          type: string
      - name: filter[user_status]
        in: query
        description: returns only profiles with the defined <code>user_status</code>; <code>active</code>, <code>pending</code>, and <code>inactive</code> are supported
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  meta:
                    $ref: '#/components/schemas/Profile_Meta'
                  links:
                    $ref: '#/components/schemas/Profile_Links'
                  linked:
                    type: object
                    properties:
                      job_titles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Job_Title'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/Group'
                      teams:
                        type: array
                        items:
                          $ref: '#/components/schemas/Team'
      security:
      - Authorization: []
    post:
      operationId: POST_profiles
      summary: Create a Profile
      tags:
      - Profiles
      description: "**Create a profile as a draft Onboarding session**\n\n1. Ensure that the Onboarding feature has been enabled for your company.\n2. In the body of the POST /profiles request, use \"pending\" as the value of the user_status field along with the other required fields found in the Request Body section below.\n\n*Sample Request:*\n```json\n{\n    \"profiles\": [\n        {\n            \"first_name\": \"John\",\n            \"last_name\": \"Smith\",\n            \"user_status\": \"pending\",\n            \"start_date\": \"2019-01-01\",\n            \"personal_email\": \"personal@email.com\",\n            \"email\": \"work@email.com\"\n        }\n    ]\n}\n```\n\n**Create a profile with a job title set**\n\n1. Retrieve the title or id of a  by making a GET request to the /job_titles or /job_titles/{id} endpoint (see the  section).\n2. In the body of the POST /profiles request, include the job_title field in addition to the other required fields found in the Request Body section below.\n3. The value of the job_title field should be set to an object containing the title (string) or id (guid) of an existing job title. Passing both values is also valid.\n\n*Sample Request:*\n```json\n{\n    \"profiles\": [\n        {\n            \"first_name\": \"John\",\n            \"last_name\": \"Smith\",\n            \"user_status\": \"active\",\n            \"start_date\": \"2019-01-01\",\n            \"personal_email\": \"personal@email.com\",\n            \"email\": \"work@email.com\",\n            \"job_title\": {\n            \t\"id\": \"a4d5783d-a447-4269-8724-b710d0267aa4\"\n            }\n        }\n    ]\n}\n```\n\n**Create a profile with an address set**\n\n1. Retrieve the country_id of an  by making a GET request to the /countries endpoint (see the  section).\n2. The state_id is the 2-letter abbreviation for a state in the United States.\n3. In the body of the POST /profiles request, include the home field and set its value equal to an object containing a valid street address as well as the country_id and state_id.\n4. Note that every field in the home object (address1, address2, city, state_id, country_id, or zip) is validated against an actual address. If any field in the address object is invalid, a 422 Unprocessable Entity error will be returned.\n\n*Sample Request:*\n```json\n{\n    \"profiles\": [\n        {\n            \"first_name\": \"John\",\n            \"last_name\": \"Smith\",\n            \"user_status\": \"active\",\n            \"start_date\": \"2019-01-01\",\n            \"personal_email\": \"personal@email.com\",\n            \"email\": \"work@email.com\",\n            \"home\": {\n                \"address1\": \"195 Broadway\",\n                \"address2\": \"\",\n                \"city\": \"New York\",\n                \"state_id\": \"NY\",\n                \"country_id\": \"US\",\n                \"zip\": \"10007\"\n            }\n        }\n    ]\n}\n```\n\n**Create a profile with a salary set**\n\n1. In the body of the POST /profiles request, include the salary field and set its value equal to an object containing a currency_type, a date representing the start date of the salary, and a yearly_amount.\n2. \"USD\" is currently the only valid value for currency_type.\n\n*Sample Request:*\n```json\n{\n    \"profiles\": [\n        {\n            \"first_name\": \"John\",\n            \"last_name\": \"Smith\",\n            \"user_status\": \"active\",\n            \"start_date\": \"2019-01-01\",\n            \"personal_email\": \"personal@email.com\",\n            \"email\": \"work@email.com\",\n            \"salary\": {\n                \"currency_type\": \"USD\",\n                \"date\": \"2019-01-10\",\n                \"yearly_amount\": 100000\n            }\n        }\n    ]\n}\n```"
      responses:
        '201':
          description: Created Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  meta:
                    $ref: '#/components/schemas/Profile_Meta'
                  links:
                    $ref: '#/components/schemas/Profile_Links'
                  linked:
                    type: object
                    properties:
                      job_titles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Job_Title'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/Group'
                      teams:
                        type: array
                        items:
                          $ref: '#/components/schemas/Team'
      security:
      - Authorization: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Create_Profile'
  /profiles/{id}:
    parameters:
    - name: id
      in: path
      description: id of the profile you want to view
      required: true
      schema:
        type: string
    get:
      operationId: GET_profiles-id
      summary: Get a Profile
      tags:
      - Profiles
      description: 'Returns same information about the profile as in the #endpoint:E2y2tKYabriCCzTiJ endpoint but isolated.


        Every client-created custom field (the token bearer has permission to see) will appear as key at the bottom of the profile object.


        As a note, the following fields will always be returned in the API response, regardless of user permissions:


        1. id

        2. email

        3. first_name

        4. last_name

        5. user_status

        6. updated_at

        7. created_at

        8. preferred_name

        9. full_name

        10. job_title



        These will NOT be exposed to the user in the UI if their permissions are set correctly.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  meta:
                    $ref: '#/components/schemas/Profile_Meta'
                  links:
                    $ref: '#/components/schemas/Profile_Links'
                  linked:
                    type: object
                    properties:
                      job_titles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Job_Title'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/Group'
                      teams:
                        type: array
                        items:
                          $ref: '#/components/schemas/Team'
      security:
      - Authorization: []
    put:
      operationId: PUT_profiles-id
      summary: Update a Profile
      tags:
      - Profiles
      description: "Note: the only fields that need to be included in a PUT /profiles/{id} request are the ones that should be updated.\n\n**Update a profile with a new job title**\n\n1. Retrieve the `title` or `id` of a  #model:JcAXAf5CGXH22bS6Z by making a GET request to the /job_titles or /job_titles/{id} endpoint (see the #docTextSection:FwRLDxsBbevBbo8uz section).\n2. In the body of the PUT /profiles/{id} request, include the `job_title` field.\n3. The value of the `job_title` field should be set to an object containing the `title` (string) or `id` (guid) of an existing job title. Passing both values is also valid.\n\n_Sample Request:_\n```json\n{\n    \"profiles\": [\n        {\n            \"job_title\": {\n            \t\"id\": \"a4d5783d-a447-4269-8724-b710d0267aa4\"\n            }\n        }\n    ]\n}\n```\n\n**Update a profile with a new address**\n\n1. Retrieve the `country_id` of an #model:yq9tkBR24wuBhzizY by making a GET request to the /countries endpoint (see the #endpoint:ECuAqAqRDoaFMn9ZH section).\n2. The `state_id` is the 2-letter abbreviation for a state in the United States.\n3. In the body of the PUT /profiles/{id} request, include the `home` field and set its value equal to an object containing a valid street address as well as the `country_id` and `state_id`.\n4. Note that every field in the `home` object (`address1`, `address2`, `city`, `state_id`, `country_id`, or `zip`) is validated against an actual address. If any field in the address object is invalid, a 422 Unprocessable Entity error will be returned.\n\n_Sample Request:_\n```json\n{\n    \"profiles\": [\n        {\n            \"home\": {\n                \"address1\": \"195 Broadway\",\n                \"address2\": \"\",\n                \"city\": \"New York\",\n                \"state_id\": \"NY\",\n                \"country_id\": \"US\",\n                \"zip\": \"10007\"\n            }\n        }\n    ]\n}\n```\n\n**Update a profile with a new salary**\n\n1. In the body of the PUT /profiles/{id} request, include the `salary` field and set its value equal to an object containing a `currency_type`, a `date` representing the start date of the salary, and a `yearly_amount`.\n2. \"USD\" is currently the only valid value for `currency_type`.\n3. Note that the `date` is the start date of the new salary. When updating an employee's salary, the `date` value that's passed in must be at least 2 days after the `date` value of the preceding salary. This is because with each new salary, the previous salary is automatically end-dated with a date that must be at least 1 day after the start date of the previous salary. If a passed-in date is invalid, a 422 Unprocessable Entity error will be returned.\n\n_Sample Request:_\n```json\n{\n    \"profiles\": [\n        {\n            \"salary\": {\n                \"currency_type\": \"USD\",\n                \"date\": \"2019-01-10\",\n                \"yearly_amount\": 100000\n            }\n        }\n    ]\n}\n```"
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                      status:
                        type: integer
                  links:
                    type: object
                    items:
                      $ref: '#/components/schemas/Profile_Links'
                  linked:
                    type: object
                    properties:
                      job_titles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Job_Title'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/Group'
                      teams:
                        type: array
                        items:
                          $ref: '#/components/schemas/Team'
      security:
      - Authorization: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Update_Profile'
  /profiles/me:
    get:
      operationId: GET_profiles-me
      summary: Get Current User's Profile
      tags:
      - Profiles
      description: 'Returns same information about the profile as in the #endpoint:E2y2tKYabriCCzTiJ endpoint but isolated, and about the current user only (the profile that owns the access token used to access the API).


        Every client-created custom field (the token bearer has permission to see) will appear as key at the bottom of the profile object.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  meta:
                    $ref: '#/components/schemas/Profile_Meta'
                  links:
                    $ref: '#/components/schemas/Profile_Links'
                  linked:
                    type: object
                    properties:
                      job_titles:
                        type: array
                        items:
                          $ref: '#/components/schemas/Job_Title'
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/File'
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/Group'
                      teams:
                        type: array
                        items:
                          $ref: '#/components/schemas/Team'
      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.
    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
    Create_Profile:
      title: Create Profile
      required:
      - profiles
      type: object
      properties:
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Create_Profile_Payload'
    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'
    Update_Profile:
      title: Update Profile
      required:
      - profiles
      type: object
      properties:
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Update_Profile_Payload'
    Profile_Meta:
      title: Profile Meta
      type: object
      properties:
        count:
          type: integer
          description: number of profiles on the current page
        total_count:
          type: integer
          description: number of total profiles for the company
        status:
          type: integer
          description: HTTP response
    Group:
      title: Group
      type: object
      properties:
        id:
          type: string
          description: unique identifier of the group
        title:
          type: string
          description: name/label of the group
        type:
          type: string
          description: name of the group type to which the group belongs
        is_team:
          type: boolean
          description: true if the group is a team
        address:
          type: object
          $ref: '#/components/schemas/Address'
        count:
          type: integer
          description: number of profiles associated with this group
        links:
          type: object
          properties:
            group_type:
              type: string
              description: group type to which the group belongs
    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'
    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
    Update_Profile_Payload:
      title: Update Profile Payload
      type: object
      description: ''
      properties:
        email:
          type: string
          description: company email of the profile
        first_name:
          type: string
        last_name:
          type: string
        user_status:
          type: string
          description: valid values are <code>active</code> or <code>pending</code>
        start_date:
          type: string
          description: valid format is YYYY-MM-DD
        personal_email:
          type: string
          description: REQUIRED if <code>user_status</code> = <code>pending</code>
        reports_to:
          type: string
          description: <code>id</code>of the profile you'd like to assign as the manager of the profile you're creating
        job_title:
          type: string
          description: in addition to passing the <code>id</code> of the <code>job title</code>, you can also pass the <code>title</code>, however, it is case-sensitive
    Address:
      title: Address
      type: object
      properties:
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state_id:
          type: string
        zip:
          type: string
        state:
          type: string
        country:
          type: string
        country_id:
          type: string
        phone:
          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
    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_Links:
      title: Profile Links
      type: object
      properties:
        profiles.job_title:
          $ref: '#/components/schemas/Link'
        profiles.image:
          $ref: '#/components/schemas/Link'
        profiles.groups:
          $ref: '#/components/schemas/Link'
        profiles.teams:
          $ref: '#/components/schemas/Link'
    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

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/namely/refs/heads/main/openapi/namely-profiles-api-openapi.yml