Namely API

Get company related information. This includes authentication methods, name, permalink, and background image. Note: Authentication is not required for this endpoint because the data (company name, background image, etc.) are required for displaying the public home page of a Namely company. Mocked via Mockzilla.

This endpoint returns a list of folders and their information.

To create a folder, a title is required. An array of folders will be returned upon success, similar to folders index endpoint.

Specify the id of the resource to get a complete description. Please see "Download Resource" documentation to actually download a specific resource.

This method returns an array of resources, whose format and content will be the same as the show resource endpoint.

This endpoint deletes a specified resource. Available as a Mockzilla mock endpoint.

Updates the name of a folder.

You must pass in the folder id to delete a specific folder.

Returns an array of all groups. Every group must belong to one and only one group type. Each group type can have zero to many associated groups. Although not present in this endpoint, each group can also have zero to many associated profiles (i.e. people within groups). Office Locations and Departments are groups.

Returns same information about the group as in the #endpoint:Z6r47eQWjcuNA9mq5 endpoint, as well as linked any profiles associated with that group (zero to many).

Returns an array of all group types. Although not present in this endpoint, every group must belong to one and only one group type. Each group type can have zero to many associated groups. Each group type can also have zero to many associated profiles (i.e. people within groups that belong to those group types). Mockzilla mock: no signup, no API key.

Returns same information about the group as in the #endpoint:27wPhQbAeFhxwiHkp endpoint, as well as linked any profiles associated with that group type (zero to many).

Returns an array of all groups associated with the id of the group_type.

Returns an array of all teams as well as linked, a list of team categories. Every team can belong to zero to many team categories. Each team category can have zero to many associated teams. Although not present in this endpoint, each team can also have zero to many associated profiles (i.e. people within teams).

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.

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. Served by the Mockzilla mock runtime.

Returns information about a single event.

Delete a particular event.

Returns all comments associated with a particular event.

Returns a list of profiles that liked a particular event.

Returns a list of profiles that liked a particular comment on a particular event. Mocked via Mockzilla.

Creates a comment on a particular event.

Like a particular event simply by POSTing to the endpoint with its id in the path parameters.

Like a particular comment simply by POSTing to the endpoint with its id in the path parameters.

Delete your like from a particular comment. You can only delete your own like (from the profile related to the token).

Delete a particular comment on an event. Available as a Mockzilla mock endpoint.

Delete a particular like from an event.

Returns an array of all job tiers. Each job tier can have zero to many linked job titles (while each job title must have one and only one linked job tier).

Creates a job tier.

Returns information about a single job tier.

Updates the label of a job tier. Use the #endpoint:3iHo6fSyKNs2dsaSC endpoint to get a list of job tiers, whose id is used in the path parameters. Mockzilla mock: no signup, no API key.

Returns all job titles. Each job title must have one and only one linked job tier (and each job tier can have zero to many linked job titles). When using the #endpoint:K6iFb2x6z2yTM9jev endpoint, the API user must either use the title or id of a job_title.

Creates a job title. Use the #endpoint:xfyRRDnWE32d5PNBZ endpoint to get a list of job tiers, whose id is used to populate the value for the parent (job tier) key in the request body.

Returns information about a single Job Title.. When using the #endpoint:K6iFb2x6z2yTM9jev endpoint, the API user must either use the title or id of a job_title.

Updates the label and/or parent (job tier) of a job title. Use the #endpoint:xfyRRDnWE32d5PNBZ endpoint to get a list of job tiers, whose id is used to populate the value for the parent (job tier) key in the request body. If not updating the parent, use the id of the current parent value; if not updating the title, use the current job title title.

Returns all valid countries in Namely. A country is universal and may not be modified. Served by the Mockzilla mock runtime.

Returns one country, as well as a list of a country’s subdivisions (e.g. a list of its states or provinces).

Returns all notifications for the current API user/token bearer. There are three main types of notifications: 1. Time Off 2. Mentioned/Appreciated 3. Generic (All Other) There are also three "200" responses on this page. However, the actual notification response is a combination of all three responses (assuming the user has received all three types of notifications). Time Off and Mentioned/Appreciated have distinct "links" associated with the notification object. Certain keys will be present or absent based on the nature of notification (e.g. the "comment_id" key will only be present if you were mentioned in a comment).

Returns notifications for a profile in a paginated form. By default, there will be 30 notifications per page. At most, you can request 50 notifications per page. There are three main types of notifications: 1. Time Off 2. Mentioned/Appreciated 3. Generic (All Other) There are also three "200" responses on this page. However, the actual notification response is a combination of all three responses (assuming the user has received all three types of notifications). Time Off and Mentioned/Appreciated have distinct "links" associated with the notification object. Certain keys will be present or absent based on the nature of notification (e.g. the "comment_id" key will only be present if you were mentioned in a comment).

Returns all profiles fields as configured at your company with instructions on valid format for passing through the API. This includes custom fields, but exceptions can be found on the #endpoint:K6iFb2x6z2yTM9jev page.

Creates a profile field within a profile field section. Mocked via Mockzilla.

Returns information about a single Profile Field.

Updates a profile field within a profile field section. Supports changing the label and the profile field section in which it sits.

Returns all profiles field sections as configured at your company. Linked to this endpoint is a list of profile fields, including additional fields not necessarily included in the #endpoint:2PMjgBj4iCTtp4tJe endpoint, as not all are API transferrable.

Returns information about a single Profile Field Section.

Updates the name/label of a profile field section. Available as a Mockzilla mock endpoint.

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.

Create a profile as a draft Onboarding session 1. Ensure that the Onboarding feature has been enabled for your company. 2. 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. Sample Request: { "profiles": [ { "first_name": "John", "last_name": "Smith", "user_status": "pending", "start_date": "2019-01-01", "personal_email": "personal@email.com", "email": "work@email.com" } ] } Create a profile with a job title set 1. Retrieve the title or id of a by making a GET request to the /job_titles or /job_titles/{id} endpoint (see the section). 2. 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. 3. 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. Sample Request: { "profiles": [ { "first_name": "John", "last_name": "Smith", "user_status": "active", "start_date": "2019-01-01", "personal_email": "personal@email.com", "email": "work@email.com", "job_title": { "id": "a4d5783d-a447-4269-8724-b710d0267aa4" } } ] } Create a profile with an address set 1. Retrieve the country_id of an by making a GET request to the /countries endpoint (see the section). 2. The state_id is the 2-letter abbreviation for a state in the United States. 3. 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. 4. 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. Sample Request: { "profiles": [ { "first_name": "John", "last_name": "Smith", "user_status": "active", "start_date": "2019-01-01", "personal_email": "personal@email.com", "email": "work@email.com", "home": { "address1": "195 Broadway", "address2": "", "city": "New York", "state_id": "NY", "country_id": "US", "zip": "10007" } } ] } Create a profile with a salary set 1. 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. 2. "USD" is currently the only valid value for currency_type. Sample Request: { "profiles": [ { "first_name": "John", "last_name": "Smith", "user_status": "active", "start_date": "2019-01-01", "personal_email": "personal@email.com", "email": "work@email.com", "salary": { "currency_type": "USD", "date": "2019-01-10", "yearly_amount": 100000 } } ] }

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.

Note: the only fields that need to be included in a PUT /profiles/{id} request are the ones that should be updated. Update a profile with a new job title 1. 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). 2. In the body of the PUT /profiles/{id} request, include the job_title field. 3. 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. Sample Request: { "profiles": [ { "job_title": { "id": "a4d5783d-a447-4269-8724-b710d0267aa4" } } ] } Update a profile with a new address 1. Retrieve the country_id of an #model:yq9tkBR24wuBhzizY by making a GET request to the /countries endpoint (see the #endpoint:ECuAqAqRDoaFMn9ZH section). 2. The state_id is the 2-letter abbreviation for a state in the United States. 3. 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. 4. 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. Sample Request: { "profiles": [ { "home": { "address1": "195 Broadway", "address2": "", "city": "New York", "state_id": "NY", "country_id": "US", "zip": "10007" } } ] } Update a profile with a new salary 1. 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. 2. "USD" is currently the only valid value for currency_type. 3. 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. Sample Request: { "profiles": [ { "salary": { "currency_type": "USD", "date": "2019-01-10", "yearly_amount": 100000 } } ] }

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. Mockzilla mock: no signup, no API key.

This endpoint returns a JSON format version of a report created in Namely. These reports update instantly, so each new call to the API will provide the user with updated information. After information about the report itself, there is an array of objects that are the columns within the report. The position of the columns is important. After the columns is what is technically an array of arrays without any keys. Each "sub"-array represents a line in the report and is a list of values whose position on the list within each "sub"-array sequentially corresponds to the column. For example, if the second "column" is "last name", the second "value" in each "sub"-array is the value. The reports API does not technically have a limit to how many lines can be pulled through the API at once. However, we would suggest limiting it to around 200 lines. A user could likely pull more than that without any problems, but they will eventually run into a timeout. There is no hard limit, however. Do not have your integration rely on field 'labels' as they are dynamic. Please use the field 'name' instead.