Connect your loyalty program in Namely without researching its API, registering in a developer program, and getting your application approved. We take care of authentication, secure credentials storage, and token refreshes so you don't have to.

Namely

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)

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

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)

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

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.

White Label Loyalty + Namely integration

About Namely

Similar Integrations

BambooHR

HiBob

Sage HR

Isolved

Benefits of White Label Loyalty + Namely

Integrate now!

Automate desired actions with Namely