Please note: This article only applies to standalone customers. This article does not apply to those who are integrated into the broader Paycor HCM platform

Our platform consists of a set of RESTful APIs that allow you to quickly and easily integrate the platform with your applications.

Registering a new Application

Before you get started, you'll have to register a new application. To register a new application, go to https://app.7geese.com/account/applications/.

You will need the following information:

Name: The name of your application
Authorization Grant Type: The method you want to allow to obtain an access token (https://tools.ietf.org/html/rfc6749#section-1.3)
Redirect URIs: Where the app will redirect to after the authentication flow is complete. You may have multiple URIs separated by spaces.

Implement OAuth2 Workflow and Obtain Access Token

You can use the OAuth 2 flow to obtain an access token for secure access to the app API. The OAuth 2 flow consists of the user authenticating with their app credentials.

Next, the user authorizes your app to connect to their 7Geese account. The end result is a token your app can use to interact with the 7Geese on behalf of the user. This is how you would obtain an access token for an application with a grant type of "Authorization code".

Obtaining an access token using the "Authorization code" grant type

Obtain a grant code:

Obtain a code that you can exchange for an access token:

GET https://app.7geese.com/o/authorize/?client_id={clientid}&response_type=code&scope={list_of_scopes}&redirect_uri={redirect uri}&state={state string}

Example:

GET https://app.7geese.com/o/authorize/?client_id=0Dn3qHXnFcqrXNqEGNo8O3TlJRjAqivGe4USfnEt&response_type=code&scope=all&redirect_uri=http%3A%2F%2Fwww.example.org%2Foauth2%2Fcallback%2F&state=my_state

If the user has authorized your grant request, the app will redirect the request to the redirect_uri with a code GET parameter:

GET http://example.org/oauth2/callback/?code=12Dsdc32&state=my_state

If the user has denied your grant request, the app will redirect the request to the redirect_uri with a error GET parameter:

GET http://example.org/oauth2/callback/?error=access_denied

2. Obtain your access token

You can use your code to obtain an access token that you can use to make requests to the the app API:

POST https://app.7geese.com/o/token/?grant_type=authorization_code&client_id={client_id}&code={code}&redirect_uri={redirect_uri}&state={state_string}

Example:

curl https://app.7geese.com/o/token/ -v --data "code=qAsBimvQAoUYTDoWQBewTAYsecj5YX&client_id=0Dn3qHXnFcqrXNqEGNo8O3TlJRjAqivGe4USfnEt&grant_type=authorization_code&state=my_state&redirect_uri=http%3A%2F%2Fwww.example.org%2Foauth2%2Fcallback%2F" -X POST

You should get a response similar to this:

{"access_token": "EFc75gT6x9O6khQJUviz15fiYGXxVG", "expires_in": 36000, "token_type": "Bearer", "state": "my_state", "scope": "all", "refresh_token": "CYiGLkPFqWhtRbfLemRB1J8HsXvrka"}

Obtain an Access Token using your email and password

If you create an application with a grant type of "Resource owner password-based", you can also skip the entire workflow and obtain an access token using your email and password:

curl -X POST -d "grant_type=password&username={email}&password={password}&scope={scope}" https://{client_id}:{client_secret}@app.7geese.com/o/token/

Example:

curl -X POST -d "grant_type=password&username=numan@7geese.com&password=1234password&scope=all" https://bnt5h2lnrn14bEtQmZkixSHW5035cefiXZq5azSi:xSCBVtKHYa0VEkt4KX5tKRCqeM@app.7geese.com/o/token/

You should get a response similar to this:

{"access_token": "g6Oud5ujc3kAZTzkwfqxpm9DSiV9gi", "token_type": "Bearer", "expires_in": 36000, "refresh_token": "Iw6OYoESmeB47BB8tkW9kT3vQY9EB6", "scope": "all"}

Scopes

The API supports a variety of scopes which you can choose from based on your applications needs.

all: Allows access to all API resources

userprofile: Access to user profile information

network: Access to network information and settings

department: Access to departments

recognition: Access to the Recognition feature

oneonone: Access to the 1-on-1s feature

feedback: Access to the feedback feature

privatenote: Access to private notes about other users that a user has written

objective: Access to the Objectives feature

review: Access to the Reviews feature

When using any of the scopes besides all, you must add a :read or :write suffix to the name above. For example, read-only access to user profile data would require the scope userprofile:read, while read/write access would require the scope userprofile:read userprofile:write. You can combine as many scopes together as you need in the scope parameter of your OAuth request. When a user is authorizing your application, the app will tell them what kind of information access your application is requesting.

Requesting API Resources

Once you got an access token by either of the above methods, you can request API endpoints that require authorization by sending a header like this:

Authorization: Bearer {access_token}

Example:

curl -H "Authorization: Bearer g6Oud5ujc3kAZTzkwfqxpm9DSiV9gi" https://app.7geese.com/api/v/2.0/objectives/

API Endpoints

Our new GraphQL API is documented in the next section.

A live overview of older API endpoints can be viewed at: https://app.7geese.com/api-docs/