Factorial is an advanced HRIS solution that's engineered to optimize and automate critical HR tasks such as employee data management, time tracking, and benefits administration. The platform also incorporates an API, empowering developers to extract vital employee data into their own systems or applications for personalized management and reporting.

To help you get employees from Factorial using Python, we'll cover every step you need to follow below.

Authentication configuration

Before you can pull data from the Factorial API, you need to set up OAuth 2.0 authentication. This integration uses the authorization code grant type.

Firstly, direct your users to the authorization URL <code class="blog_inline-code">https://api.factorialhr.com/oauth/authorize</code> to start the OAuth flow. Once the user completes the authorization flow, the Factorial API will redirect the user to the redirect URL that you provided. The redirect URL will include the authorization code as a query parameter, <code class="blog_inline-code">code</code>, which you will then use to request an access token.

To request the access token, you need to hit the token URL <code class="blog_inline-code">https://api.factorialhr.com/oauth/token</code> using your client ID and secret provided by Factorial. Include these credentials, along with other required parameters, in the URL as query parameters.

The request header should follow this format: <code class="blog_inline-code">Authorization: Bearer {ACCESS-TOKEN}</code>.

Here's where to find important information in the token URL response:

• The <code class="blog_inline-code">access token</code> is in the access_token key.
• The <code class="blog_inline-code">expires_in</code> value tells you how long the token will last.
• The refresh token is in the <code class="blog_inline-code">refresh_token</code> key.

How to get employees from Factorial

The code below will help you pull employee data from the Factorial API by setting up an OAuth flow, getting an access token and using it to make an authorized request to the Factorial API.

First, define your client ID, client secret, and redirect URL:

client_id = 'your-client-id'
client_secret = 'your-client-secret'
redirect_url = 'your-redirect-url'

Then establish the authorization URL and token URL:

auth_url = 'https://api.factorialhr.com/oauth/authorize'
token_url = 'https://api.factorialhr.com/oauth/token'

Once the user navigates to the authorization URL and authorizes, they're sent to the redirect URL with code as a query parameter. Get the authorization code from the query parameter:

auth_code = 'auth-code-from-query-param'

Request the access token:

payload = {
    'client_id': client_id,
    'client_secret': client_secret,
    'code': auth_code,
    'redirect_uri': redirect_url,
    'grant_type': 'authorization_code'
}
response = requests.post(token_url, data=payload)
token_response = response.json()

Get the access token and refresh token from the response:

access_token = token_response['access_token']
refresh_token = token_response['refresh_token']

Use the access token to make authorized API requests:

headers = {'Authorization': 'Bearer ' + access_token}
response = requests.get('https://api.factorialhr.com/api/v1/employees', headers=headers)

Print the response:

print(response.json())

Remember to replace <code class="blog_inline-code">'your-client-id'</code>, <code class="blog_inline-code">'your-client-secret'</code>, <code class="blog_inline-code">'your-redirect-url'</code>, and <code class="blog_inline-code">'auth-code-from-query-param'</code> with your actual Client ID, Client Secret, Redirect URL, and Authorization code respectively.

You should see the list of employees from Factorial as the output.

[
    {
        "id": 101,
        "birthday_on": "1990-01-01",
        "manager_id": 201,
        "timeoff_manager_id": 301,
        "regular_access_starts_on": "2022-01-01",
        "avatar": "https://example.com/avatar.jpg",
        "identifier": "EMP101",
        "identifier_type": "Employee ID",
        "phone_number": "+1-555-555-5555",
        "gender": "Male",
        "nationality": "American",
        "bank_number": "1234567890",
        "country": "United States",
        "city": "New York",
        "state": "New York",
        "postal_code": "10001",
        "address_line_1": "123 5th Avenue",
        "address_line_2": "Suite 101",
        "social_security_number": "123-45-6789",
        "email": "employee101@example.com",
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "role": "Software Engineer",
        "start_date": "2022-01-01",
        "hiring": {
            "base_compensation_amount_in_cents": 7000000,
            "base_compensation_type": "Salary"
        },
        "location_id": 401,
        "team_ids": [
            501,
            502,
            503
        ],
        "company_holiday_ids": [
            601,
            602
        ]
    }
]

Final thoughts

It’s worth remembering that your clients might be using other HRIS solutions, whether that’s Workday, Namely, UKG, etc.

You can offer customer-facing integrations with all of the HRIS solutions your clients use by connecting to Merge's HRIS Unified API.

Learn more about Merge’s Ticketing Unified API, along with the other features and capabilities provided by the platform, by scheduling a demo with one of our integration experts.