Namely

true if the token bearer has a role with permission to delete the comment; will always be true for one's own comment

content of the comment, displayed in markdown

content of the comment, displayed in HTML

true if the token bearer has liked this comment

the hour difference between UTC and the main office of the company

Event's Comments

true if the token bearer has a role with permission to comment on events on the home feed (will be same value on all events)

true if the token bearer has a role with permission to delete the event; will always be true for one's own announcement

true if the token bearer has a role with permission to like events on the home feed (will be same value on all events)

list of unique identifiers for each comment associated with the event; 0 to many

content of the post, displayed in markdown; null for anything but type: announcement

unique identifiers of a file associated with the event (photo, document, etc.); zero to one; null for anything but type: announcement

content of the post, displayed in HTML; null for anything but type: announcement

true if the token bearer has liked this event

profile id of the profile related to the event; profile that created the announcement or profile associated with a birthday, anniversary, or recent_arrival

epoch time that the event was created/generated

true if the company has commenting enabled on the home feed; same as in meta

number of years related profile has been at the company; null for anything but: anniversary

Events

position of the folder on the UI; 0 is the top position

Folders

Job Tiers

id of the job tier associated with the job title

id of the job tier associated with the job title (when creating a job title, the key is "parent")

Job Title

list of the 'block' subsections within the section; can be empty

unique identifier of the profile field section

list of unique identifiers of each #endpoint:kxzfwAD7zrZ9CByGA located within the profile field section

label of the profile field section; only editable on through the API via the #endpoint:eoL989Gmn6vnfSPbE endpoint

Profile Field Sections

refers to the profile field 'block' in which the profile field is located (included in 'linked'); sequentially corresponds based the position of the block title; top position is 0

true if the profile field is able to be deleted

label of the profile field; editable on UI and through API

unique identifier of the #endpoint:66aqLXinWcyrR2aY2 in which the profile field is located

immutable name of the profile field; auto created based on label if using UI to create profile field

id of the profile field section in which you want the place the field

valid format information for passing data through the API for the profile field

Profile Fields

list of assets on the profile; blank if never provided or provided then deleted; valid values include Laptop, Cell Phone, Building Keys, Corporate Card, and Air Card

amount of the profile's dental plan; numbers only; cannot be null if any other dental keys provided

relationship of the profile's dental plan's beneficiary to the profile; valid values include Employee Only, Employee/Child, Employee/Spouse, Family, Not Applicable, and Waive; blank if never provided or provided then deleted; cannot be null if any other dental keys provided

currency type of the profile's dental plan amount; default USD

description of the profile's dental plan; null if never provided; blank if provided then deleted

departure date of the profile; format YYYY-MM-DD; blank if never provided or provided then deleted

date of birth of the profile; format YYYY-MM-DD; blank if never provided or provided then deleted

employee id of the profile; blank if never provided or provided then deleted

amount of the profile's healthcare plan; numbers only; cannot be null if any other healthcare keys provided

relationship of the profile's healthcare plan's beneficiary to the profile; valid values include Employee Only, Employee/Child, Employee/Spouse, Family, Not Applicable, and Waive; blank if never provided or provided then deleted; cannot be null if any other healthcare keys provided

currency type of the profile's healthcare plan amount; default USD

description of the profile's healthcare plan; null if never provided; blank if provided then deleted

"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

state of the home address; for US, must be the 2-digit code; for other countries, refer to the #docTextSection:7izuT4kPbi3FngZbD endpoints

only applies to companies using Namely Time

phone number associated with the office location

state of the office address; for US, must be the 2-digit code; for other countries, refer to the #docTextSection:7izuT4kPbi3FngZbD endpoints

preferred name of the profile; null if never provided; blank if provided then deleted

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 null if any other salary keys provided

currency of the profile's current salary; null if never provided or no current salary; cannot be null if any other salary keys provided

start date of the profile's current salary; null if never provided or no current salary; cannot be null if any other salary keys provided

unique identifier of the profile's current salary; null if never provided or no current salary; cannot be null if any other salary keys provided

true if the salary is hourly, and false if yearly; cannot be null if any other salary keys provided. Known as is_hourly elsewhere in the app.

unique identifier of the pay group associated with the profile's current salary; null if never provided or no current salary

The Payroll Company associated with this salary. Required if multiple Payroll Companies. "Company name" defaults to first Payroll Company.

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.

unique identifier of the payroll job associated with the profile's current salary; null if never provided or no current salary

rate of the profile's current salary; valid values include annually, weekly, biweekly, bimonthly, semimonthly, monthly, quarterly, semiannually, and thirteen_monthly; null if never provided; blank if provided then deleted; cannot be null if any other salary keys provided

annualized amount ("amount_raw" * # of pay periods based on the "rate") of the profile's current salary; all salaries are annualized; null if never provided; blank if provided then deleted; cannot be null if any other salary keys provided

ssn of the profile; blank if never provided or provided then deleted

start date of the profile; format YYYY-MM-DD

epoch time that the profile was updated; equal to create_at if never updated

user status of the profile; valid values in the API are active, pending, and inactive

Profiles

columns within the report; note: position of the columns is important

this is technically an array of arrays without any keys 'sub'-arrays; each 'sub'-array represents a line in the report, and is a list of values, whose position on the list within '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

unique identifier of the report; identical to the id in the path parameters

describes the type of report (e.g. salary_history)

Reports

id of the folder in which the resource file sits; null if not in a folder

Resources

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.

Company Info

This endpoint returns a list of folders and their information.

Get all Folders

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

Create Folder

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

Get a Resource

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

Get Resources in a Folder

This endpoint deletes a specified resource.

Delete Resource

Get Resources not in a Folder

Update Folder

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

Delete 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.

Get all 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).

Get a Group

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).

Get all Group Types

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).

Get a Group Type

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

Get Groups from 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).

Get all Teams

Get a Team

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.

Get all Events

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.

Create an Announcement

Returns information about a single event.

Get an Event

Delete an Announcement

Returns all comments associated with a particular event.

Get an Event's Comments

Create an Event's Comment

Returns a list of profiles that liked a particular event.

Get an Event's Likes

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

Get an Event's Comment's Likes

Like a particular event simply by `POST`ing to the endpoint with its <code>id</code> in the path parameters.

Create an Event's Like

Like a particular comment simply by `POST`ing to the endpoint with its <code>id</code> in the path parameters.

Create an Event's Comment's Like

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

Delete an Event's Comment's Like

Delete an Event's Comment

Delete an Event's Like

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).

Get all Job Tiers

Create a Job Tier

Returns information about a single job tier.

Get a Job Tier

Updates the label of a job tier.

Use the #endpoint:3iHo6fSyKNs2dsaSC endpoint to get a list of job tiers, whose <code>id</code> is used in the path parameters.

Update a Job Tier

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 <code>title</code> or <code>id</code> of a <code>job_title</code>.

Get all Job Titles

Creates a job title.

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

Create a Job Title

Returns information about a single Job Title..

When using the #endpoint:K6iFb2x6z2yTM9jev endpoint, the API user must either use the <code>title</code> or <code>id</code> of a <code>job_title</code>.

Get 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 <code>id</code> is used to populate the value for the <code>parent</code> (job tier) key in the request body.

If not updating the <code>parent</code>, use the <code>id</code> of the current <code>parent</code> value; if not updating the <code>title</code>, use the current job title <code>title</code>.

Update a Job Title

Returns all valid countries in Namely. A country is universal and may not be modified.

Get all Countries

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

Get a Country

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)

<strong>There are also three "200" responses on this page</strong>. 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).

Get all Notifications

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)

<strong>There are also three "200" responses on this page</strong>. 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).

Get a Profile's Notifications

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.

Get all Profile Fields

Creates a profile field within a profile field section.

Create a Profile Field

Returns information about a single Profile Field.

Get a Profile Field

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

Update a Profile Field

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.

Get all Profile Field Sections

Returns information about a single Profile Field Section.

Get a Profile Field Section

Updates the name/label of a profile field section.

Update a Profile Field Section

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.

Get all Profiles

**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:*
```json
{
    "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:*
```json
{
    "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:*
```json
{
    "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:*
```json
{
    "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
            }
        }
    ]
}
```

Create a Profile

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.

Get a Profile

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:_
```json
{
    "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:_
```json
{
    "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:_
```json
{
    "profiles": [
        {
            "salary": {
                "currency_type": "USD",
                "date": "2019-01-10",
                "yearly_amount": 100000
            }
        }
    ]
}
```

Update a Profile

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.

Get Current User's Profile

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.

Namely API Integration Profile

Data Collections

Operations

Supercharge your product integrations today