Help your customers onboard global talent using the Remote API

With the recent migration toward the remote, work-from-anywhere work model, global job listing sites are becoming increasingly popular. But how can your job site or applicant tracking system help employers take the next step of getting job candidates hired and onboarded in their country of residence? Enter the Remote API! 

With the Remote API, employers can complete the hiring process for successful candidates in more than 60 countries without leaving your platform. In this blog series, we will provide examples of the different levels of onboarding integrations you can achieve using the Remote API. 

This series begins in this post, where we provide instructions for the basic integration that allows employers to kick off employee onboarding with the click of a button in your platform, making the hiring process faster and smoother. Future posts in this series will give you the building blocks to create an even deeper employee onboarding integration. 

With that, let’s learn how to launch an integration with the Remote API!

Developing a lightweight integration

To launch an integration that improves the lives of your customers and requires minimal development effort — or if you just want to gauge customer interest before committing to a deeper integration — we recommend starting with a lightweight approach. 

In a lightweight integration with Remote, employers select the candidates they want to hire on your platform. With the click of a button, they are redirected to Remote, where they see the candidate already added to our system and ready to begin the international onboarding process. From here, the employer simply adds some contract details so Remote can generate an employment agreement, inviting the new hire to add their personal details. Remote takes care of the rest to ensure the new hire is compliantly hired in their country, registered for benefits, and set up for payroll.

Prerequisites

It’s important to note this lightweight integration has a few prerequisites:

1. The customer must already be a Remote customer. If they are not, they can easily and quickly create a Remote account online. Alternatively, your team can ask us about using the Create Company endpoint, which allows you to create a new Remote account for your customers.
2. The user must already be a Remote user. If they are not, they can ask their Remote company admin to add them to their company’s Remote account. Alternatively, your team can ask about our Company Managers endpoint, which you can use to create a company manager account in Remote for these situations. 

How to build your Remote API integration

You can build your integration with the Remote API in three easy steps:

1. Sign up as an API partner.
2. Build the consent flow.
3. Send the new hire’s basic details to Remote and redirect the user to Remote’s platform.

Let’s take a closer look at how each step works.

Sign up as an API partner

When you sign up as an API partner, Remote will:

1. Connect with you to discuss how to embed global employment solutions directly into your platform and approve your application.
2. Give you access to our detailed API documentation.
3. Set you up with client credentials to access the Remote API.
4. Provide access to a demo environment so you can test your integration.
5. Create your integration entity in Remote so any companies that use your integration are linked to your entity and you will be able to read and manage data for those customers.
6. Highlight your API integration in Remote’s UI to share information about your company and instructions on getting started for all of our customers to see. This is great visibility for your company, because all of Remote’s customers will see you here regardless of whether they are already signed up for your services!

Ready to start the journey to becoming an API partner now? Sign up now to learn more!

Build the consent flow

Remote has implemented an OAuth 2 Authorization Code Flow so our customers can consent to an API integration partner accessing and managing their resources in Remote. When a new user attempts to use your API integration for the first time, they will see what actions the integration can take and will be asked to provide consent. All operations performed through the integration are performed on behalf of the logged-in user.

Remote will work with your team to get the correct consent flow implemented for your integration. Once the consent flow has been implemented, the flow for a new user of the integration will be as follows:

1. The user attempts to perform an action in your platform that requires the integration (e.g. clicks the option to hire a new candidate using Remote’s EOR services).
2. Your application redirects the user to Remote’s authorization page. 
3. If the user is already logged in, they are sent directly to Remote’s authorization page. If the user isn’t currently logged in to Remote, we redirect them to the login page where they enter their Remote username and password and are redirected to Remote’s authorization page. Quick tip: you can skip the user login requirement by using /v1/sso-url, which will create an active session for the user. 
4. On the authorization page, the user sees the actions that the integration wants to perform on their behalf and can choose whether to allow or deny access.
5. Once a user has completed the consent flow, they are redirected back to your application using the callback URL you provide to Remote.
6. When the user is redirected back to your application, you receive an authorization code in the URL’s query string. You can exchange the authorization code to obtain a refresh token and a valid access token.
7. Your application will pass the access token in the authorization header for future API requests that perform an action on behalf of the user.
8. After the first company user has enabled the integration, all Admin users from that company can see in the Remote UI that the integration has been enabled. They can also see a list of users from their company that have consented to the integration. 
9. In the Remote UI, an Admin user also can disable the integration for their company or remove access to the integration for a specific user.

Detailed instructions and code examples for implementing the authorization code flow are available in the Remote API documentation.

Send the new hire’s basic details to Remote and redirect the user to Remote’s platform

When a user in your platform indicates they want to move forward with hiring a candidate, you can send the candidate’s details to Remote and, at the same time, redirect the user to Remote’s platform, where they will see the new hire’s profile and can move the new hire to the next stage of the onboarding flow. 

To send the candidate’s details to Remote, send a request to POST /v1/employments with the following required details:

1. company_id: The customer’s Remote ID. This value is returned in the refresh token response. It won’t change so feel free to store it for future reference. You can also get the company id by making a request to GET /v1/companies.
2. country_code: The country where the candidate will be hired. At the time of writing, Remote supports hiring in over 60 countries (and rapidly growing). If the user attempts to hire in an unsupported country, you will receive an error response from the API and can use this to alert your user.
3. The candidate’s full_name, job_title, personal_email, and provisional_start_date. These details will be used to create an employment agreement between Remote and the candidate on behalf of the customer.

When Remote receives the POST request, a new hire record is created. The new hire appears in Remote’s Onboarding page.

Redirect the user to Remote’s onboarding page so they can finish adding any additional details required by Remote and invite the employee to complete onboarding in Remote. There are two options for handling user logins when redirecting them to the Onboarding page:

1. Redirect the user to Remote’s login page, where they can either enter their username and password or sign in using SSO. If they already have an active session in Remote, they will bypass the login page.
2. Use GET /v1/sso_url to get a redirect URL for the user and bypass the login page. When choosing this option, you can pass the following parameters:

• user_id: The user’s ID in Remote. This value is returned in the refresh token response. It won’t change, so feel free to store it for future reference. You can also get the user’s ID by making a request to GET /v1/company-managers and matching against the user’s email address.
• action=redirect_to_onboarding&user_id=<user_id>: redirects the user to the onboarding page for their company

That’s it! You now have a delightful integration with Remote that helps your customers achieve their hiring goals faster, regardless of where in the world a candidate is located! 

Request access to the Remote API and start building today!

Hopefully this guide sparked new ideas on how you can use the Remote API to solve some of your customers’ top pains. We have only scratched the surface of how the API can be used to build streamlined customer flows. Stay tuned for more in this series, where we’ll be diving deeper into our API capabilities and exploring additional possibilities for building a comprehensive API integration with Remote!
At Remote, we believe in learning together, listening to feedback from our developer community, and continuously making improvements based on the feedback we receive. Our Remote API is now available, so request access to our developer documentation and share your feedback today!