This is the successful story about how our first distributed and asynchronous team managed to deliver their work efficiently.

The customer onboarding team at Remote was the first team inside engineering to have people across the entire globe, covering the full 24h clock. Our goal is to make it easy, fast, and delightful for prospects to sign up and use Remote to hire employees and pay contractors compliantly, all around the world. For now, we have people in America, Europe, and Oceania.

See also: Supercharged forms guide: Using JSON schema in forms

With people living in such different time zones, the challenge starts with time itself. If I say to Dino that I will deploy the change at lunchtime, what does it mean to him? Or if Matthew says to Martin, he will start at 9 a.m., again, what does it truly mean?

To avoid misunderstandings, when we share times, we make sure to do it using UTC (Coordinated Universal Time). It’s easy to calculate, it isn't affected by Daylight Savings Time, and we don’t need to ask people where they are. Using my examples, I would say to Dino that will deploy at 12 a.m. UTC, or Matthew would say to Martin that he will start at 1 p.m. UTC.

Another difference from other teams I have worked with in the past is that we don’t use SCRUM or any other Agile methodology. Since we work asynchronously, we can’t wait for people to assign work or to have a planning meeting to discuss the next big piece of work. Instead of following the traditional Agile methods, the Remote engineering team has its flow. The work tasks are displayed on a Kanban board. We have the autonomy to pick up whatever task is more important/beneficial for that moment. Our Kanban contains a list of issues ― what we call our tasks or tickets. Those issues usually contain a description of what needs to be done and a few labels. For example, we have one to categorize if the proposed work is for frontend or backend engineers. It helps us to identify and choose what task would have more impact and benefits for customers. The Remote flow allows us to work independently and asynchronously, as we don’t have to wait for the end of a sprint to achieve goals or to have a retro meeting to identify what went wrong or could be improved.

In general, engineering teams at Remote have, at least, one meeting per week for social catchup or to align the team within projects and to make decisions. For our team, however, it wasn’t possible to do this in the normal way.

First, we tried to adjust the meeting times, but it was never good for someone as it was either too early or too late for at least one of the team members. Quickly, we noticed achieving a reasonable time for all team members would be an impossible mission. In an attempt to improve team interaction, our team decided to break weekly meetings into two fortnightly meetings: one APAC (Asia-Pacific) meeting and one for EMEA (Europe, Middle East, and Africa).

In the beginning, it appeared to be working. Nobody needed, for example, to stay late to be part of the meeting. Nevertheless, the feeling that we were excluding the opposite time zone group from the decisions was still there. So, for instance, if the Europe/America team decided to release something important, the team based in the Pacific would only know about the decision later and couldn’t be included in the discussion. We felt a deeper change was required for the asynchronous work to be well established. So, we agreed to transform the team meetings into social team meetings. That way, we could use the time to get to know each other better. This is a marvelous opportunity to know more about different cultures, as we are based in different countries.

Daily work in a distributed and asynchronous team

But how do we make our decisions? How do we make sure all the teams are updated about the projects? How do we discuss some crucial development points?

All discussions, questions, and decisions happen in one or more of these tools: Gitlab, Slack, and Notion. In that way, we make sure all decisions are documented and all questions are answered transparently, making any discussion or decision searchable. We prefer to not assume that all our colleagues agreed with something or that everyone knows about a particular issue. We try to wait at least a few hours until everybody on the team is aware of what will happen and has a chance to participate in a discussion or take any action. We rely on all Remote values like ambition, ownership, and kindness to accomplish that.

Additionally, as part of our daily routine, we separate a few minutes during our day to ask questions to our team or Remote colleagues, even when they are offline. Questions and replies are part of the process to progress on the task and run projects smoothly. We try to keep this type of conversation in public channels, allowing everyone to know what is going on.

Sometimes, this cycle is interrupted. When it happens, there is a straightforward impact on the team's productivity. For example, in Australia and New Zealand, the weekend always comes first, before it does in Europe and America. We constantly joke that Martin, Andrew, and I live in the future. Due to this day's difference, we often leave comments, feedback, and questions to others who are still working. When we start working on Monday, we can read all the messages left to us and take action. If for any reason we don’t receive a reply during our weekend, then it means the answer will come to us only on Tuesday. This gap can cause frustration and delay work if not handled appropriately.

But what if the person doesn’t know the answer or needs more time to figure out what to do? In this case, we prefer to be transparent and say something like, “I don’t know the answer. I will ask someone else to see if I can identify why it’s happening.” For transparent and kind communication, it’s better to acknowledge we’ve received the question/message, even if we couldn’t reply to it, instead of saying nothing and leaving the other person in the dark.

We use a similar approach for merge requests on Gitlab. At Remote, developers rely on each other's code reviews to deploy code. When we send our code for review, it is important to have it reviewed as quickly as possible to avoid having the code sleep one or more nights due to the time difference. Usually, we tag one or two reviewers to look at the code. And when the reviewer can’t do it for some reason, that developer tends to write a message to say when it will happen or explain why they haven’t done it. As I said earlier, we like to be honest and transparent when something unexpected happens.

The team is always learning and improving its communication. A good example happened to me. I had done a deployment during my working hours. But during my night, Bridget contacted me to revert that code because it shouldn’t have been deployed just yet. Because I was sleeping, I didn't see the messages Bridget sent and was unable to act upon Bridget’s request.

Fortunately, she remembered the time zone difference and sent a message to Matthew, who is based in Canada. Matthew reverted that code, and all was well. Then, to avoid situations like this from occurring in the future, we began notifying people when we do deployments on Slack and Gitlab. We also leave notes on tickets to share when is a bad or good moment to release specific code in production.

A new addition to our process is recording videos to share the work and list important points. Those videos have been a really powerful tool and have been used by designers, product managers, developers, and others. Videos provide an easy and simple way to avoid confusion and misunderstanding. When associated with a good description in Slack, for example, a video is a robust way to start a new issue or project.

One positive side of working in a distributed team is we have 24-hour team coverage. When someone in the team is sleeping, someone else is awake. The frontend team may send an update to the backend team at the end of their working hours, and the Backend team can then pick up this update and make progress during their working hours. When they come back the next day, the frontend team’s developers can continue the work. This is a very positive approach, as the backend team avoids being blocked by any frontend work and vice versa. We can be very productive, with little downtime, without overworking to complete a task/project.

Despite all the work coordination, occasionally a synchronous deployment or catch-up is required. Although those moments are happening less often, as a distributed team, we need to be flexible to arrange synchronous catch-ups as every member has a different work routine. Remote is a company that respects its employees' time, and also works asynchronously. As such, we try to avoid this synchronous work as much as possible to avoid routine disruption.

When synchronous work is necessary, we coordinate a good time to sync with Google Calendar. A synchronous meeting that requires all team members is rare. Normally, synchronous work involves two or three developers, our team lead or project manager, and possibly a product designer. We always try to have an agenda and a clear intention about the synchronous meeting.

For instance, we can have a synchronous call to deploy frontend and backend work at one time. Both developers need to be prepared, which means the code is reviewed, updated, and prepared to be released. As part of our communication process, we share with the team what will happen. Following my example, we let engineers know we will do a synchronous deployment. When we conclude the deployment, we also let developers know that. If it is a design meeting or a product meeting, we share the conclusions of that meeting and the recording of the call.

Another type of sync communication are our 1:1 meetings, which are, in our case, regular Zoom calls between developers and team lead. It’s an opportunity to give the lead our feedback, keep each other in the loop, get help with our career growth — and a way to establish a deeper bond as work colleagues.

Async drives speed and flexibility at Remote

Our asynchronous work allows us to have a flexible routine. We can determine when to work and where we work. We can work from home in the morning and at a coffee shop in the afternoon. Some people prefer to work at night, and our asynchronous work allows that. This flexibility brings us such impressive independence!

We can work when we feel we are most comfortable and productive. This helps all of us avoid overworking and deal better with unexpected situations

 In my case, this flexibility also supports my health. I have suffered from chronic pain since 2018. A flexible work routine allows me to sleep more when I am tired, go to doctors and physiotherapy appointments, and have breaks during the day to do exercises and self-care activities. I do not need to lose a day of work anymore if I need just a bit more rest during the day.

As always, there is no silver bullet. Our team is still evolving and learning from its own mistakes and success. Our goal is to improve our communication even more by creating more opportunities to share the progress of our work. Adopting these processes can help us detect earlier avoidable bugs and prevent misunderstandings through good communication inside the Gitlab issues.

Working async as a truly global engineering team

def deps do
  [
    {:swoosh_gallery, "~> 0.1.0"}
  ]
end

2. Create a Gallery module, that will hold all the emails you want to preview, using a path and the module responsible for building the email:

defmodule MyApp.Mailer.Gallery do
  use Swoosh.Gallery

  preview "/welcome", MyApp.Mailer.WelcomeMailer
end

3. In you WelcomeMailer module, implement two new methods: preview/0 and preview_details/0. They are used to build your email struct and provide details such as title and description in the gallery page.

defmodule MyApp.Mailer.WelcomeMailer do
  # the expected Swoosh / Phoenix.Swoosh code that you already have to deliver emails
  use Phoenix.Swoosh, view: SampleWeb.WelcomeMailerView, layout: {MyApp.LayoutView, :email}

  def welcome(user) do
    new()
    |> from("noreply@sample.test")
    |> to({user.name, user.email})
    |> subject("Welcome to Sample App")
    |> render_body("welcome.html", user: user)
  end

  # `preview/0` function that builds your email using fixture data
  def preview do
    user = %{email: "user@sample.test", name: "Test User!"}
    welcome(user)
  end

  # `preview_details/0` with some useful metadata about your mailer
  def preview_details do
    [
      title: "Welcome to MyApp!",
      description: "First email to welcome users into the platform",
      tags: [step: "onboarding"]
    ]
  end
end


4. For the last step, mount the Gallery on your app’s router:

forward "/dev/gallery", MyApp.Mailer.Gallery

Now, if you access http://localhost:4000/dev/gallery in your browser, you should see the “Welcome” email above with all the information you need! Add more emails to the gallery, and now you have a single place for all your emails!

Another cool feature from the Swoosh Gallery is that you can generate static pages with it, so you can host it in GitHub Pages, Netlify, or Vercel, for example. In the root of your project, run the command below:

mix swoosh.gallery.html --gallery MyApp.Mailer.Gallery --path "_build/emails"

Now, open _build/emails/index.html and you should see the same page from the gallery above!

You can use this during development time to see how your email is being rendered without having to send it. There are cases in which sending an email requires a long setup of the app or creating a new account manually through the browser, but with the Swoosh Gallery, you just open the gallery and see it!

Swoosh Gallery is our new open source library that integrates with Swoosh to display and organize your emails in a single place without having to send manually. You can use it during development time, in production, or by sharing the gallery as static pages. This helps all stakeholders of the company know what is sent to customers and helps developers quickly see the changes done to the email.

At Remote, we send many kinds of emails to our customers: emails about new payments, invoices, approved time off, onboarding new employees, and so on. There are so many emails, we needed to make sure we did not lose count of all the emails we send! This is the story of how we solved that issue — and how it can help you, too!

We use Swoosh to build and send out our application’s emails. It is easy to use, and it has many adapters that you can choose. It also has a really cool feature in which you can see all the outgoing emails of your app during the development time. For instance, you could open a tab at http://localhost:4000/dev/mailbox, click the button of your app to send an email, and see the email you sent sent pop up there.

The Swoosh Mailbox is really handy, but there are a few gotchas:

If you want to see the preview of the email, first you have to make your app send it by going through the process of submitting a new invoice or inviting a new user to your team.

It’s a development-time-only thing. If you were to expose this in production, you would expose private data from all your emails.

What if we could see the email just like in the mailbox, but with fake data and without going through all the hoops to send it?

We came up with Swoosh Gallery, a library that displays all the Swoosh emails of your Elixir app into a single place.

With Swoosh Gallery, you can gather all your emails in a single place and see all the information you had in Swoosh’s Mailbox without the need of manually sending it. You can also reuse all the email setup you already have in place; you just need to provide some preview fake data.

Preview and display your Swoosh mailers to everyone with Swoosh Gallery, a new Elixir library from the engineering team at Remote!

Lucas Mazza

Vitor Cavalcanti

Introducing Swoosh Gallery

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!

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.

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

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.

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. 

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

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.

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

Connect with you to discuss how to embed global employment solutions directly into your platform and approve your application.

Give you access to our detailed API documentation.

Set you up with client credentials to access the Remote API.

Provide access to a demo environment so you can test your integration.

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.

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!

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:

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

Your application redirects the user to Remote’s authorization page. 

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. 

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.

Once a user has completed the consent flow, they are redirected back to your application using the callback URL you provide to Remote.

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.

Your application will pass the access token in the authorization header for future API requests that perform an action on behalf of the user.

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. 

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:

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.

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.

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:

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.

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!

Help your customers onboard global talent using the Remote API

The previous example renders a simple form, but JSON Schemas allow for much more complex definitions, such as having fields that depend on the value of some other field using “if,” “then,” and “else” keywords.

Engineers at Remote are working on adopting JSON Schemas for every country we support, resulting in a much smoother user experience, speeding up our onboarding times and reducing onboarding questions from users all around the globe.

For Remote API partners, we plan to launch an SDK that customers can embed on their websites to make the integration process with Remote much faster for their development teams. We will also be publishing two more interesting articles to go into detail about how we build and use JSON Schemas on our frontend and backend services.

If you have any questions, feel free to reach out to me on Twitter @csilva_antonio. I'm always happy to help!

Remote allows employers to hire employees all across the globe, and each country is different regarding the details and documents needed to hire. These details are not only specific to each country, but are also constantly changing due to new country-specific laws and other factors.

When Remote started, we used simple forms on the frontend, where a part of the input validation process happened. The other part happened in the backend. This became a problem for us, as the backend had different validations and input fields defined for each country. This problem was happening due to the nature of our business: country laws change often, and we need to adapt to those changes quickly.

With the launch of the Remote API, it was clear that we needed to build something both robust and simple to change to make all our services share the same requirements for every country.

We decided to use JSON Schema to address the challenge. JSON Schema allows for forms definition and data validation in the frontend and backend services, creating a single source of truth. This is defined (as the name implies) in JSON, so it can be read and updated by anyone. JSON Schema also has good documentation, so even a new joiner can make any necessary changes.

These JSON Schemas are then parsed, and a form is rendered on the frontend according to the definition. On top of standard JSON Schema fields (such as “type," "title," "maxLength," etc.), we added metadata to each field to make the form render as we intended. One example is the “presentation" object, which contains fields like “position" that define where the position a certain field is displayed on the form. Another example is the “options” field: useful when the input type is a radio button or a selection from a dropdown, allowing us to define a label and a value (where the value must match one of the values defined in the “enum” array).

The following code block shows an example of a JSON Schema containing a single property (the number of accepted values was reduced to make the example shorter):

Learn how Remote uses the JSON Schema to build smooth onboarding processes for dozens of countries around the world.

How Remote builds onboarding for 60+ countries

In February 2022, Russia and its forces senselessly attacked Ukraine. The violence and the suffering inflicted on the people in Ukraine is very real. We want to help.

Introducing Devs For Ukraine, a free, online charity conference with the goal of raising funds and providing support to Ukraine.

On April 25th and 26th, join 17 speakers from around the globe to learn about career growth, team leadership, tech’s ability to create a more equitable world, and much more.

Our goal for the event is to raise $15,000 for these non-government organizations:

Coalition To Support Black People In Ukraine

The event will be free to attend and is run by volunteers, but we ask everyone to donate. All of the funds will be donated to the benefit of Ukraine.

If you’d like to help our cause, you can:

Share this event with your communities (click here to tweet)

We’re looking forward to seeing you at the event!

Cassidy Williams

Sara Vieira

Announcing the Devs For Ukraine Conference

Remote and hybrid work are here to stay. That evolution means new challenges for distributed teams — both for employers and the people they employ. This shift means software companies that support HR, payroll, and other related processes must now prepare to support international growth for their customers in addition to their current domestic offerings. 

Upgrading your product suite with a global employment option is a must to keep up with this shift, but navigating international compliance, legal, tax, and benefits channels yourself can be challenging. That’s why Remote makes it easier than ever for you to white label our employer of record (EOR) solution, empowering your customers to hire beyond their borders directly from your platform. 

We built our EOR solution with your customers in mind! We analyzed the problems employers face when scaling globally and developed our platform to simplify the process from end to end for HR teams and hiring managers.

Check out these common challenges we can help your customers solve:

1. Onboarding (and offboarding) globally distributed teams.

Remote and hybrid work became widespread thanks to pandemic-fueled necessity, but the world will never return to an office-only default. This means employers are now faced with onboarding (and offboarding) remote workers in numerous countries. What used to be a tried and true process now can get complex very quickly when it comes to managing local regulations, statutory health benefits, and taxes in multiple countries. Plus, HR teams still need to maintain a seamless and professional experience no matter where the employee is located. 

At Remote, we handle local payroll, taxes, benefits, and compliance, so your employees feel as safe and secure as your business does. Every employee receives a localized experience based on their country of residence, and our in-house experts monitor regulatory changes in every country we’re in, allowing us (and you!) to operate at maximum efficiency. What’s more, your customers can get the full Remote experience directly in your platform through our new API. It’s a win-win for everyone!

As remote work becomes more widespread, many organizations will need to have multi-disciplinary experts in every location who can understand the local regulations and compliance laws, as well as build processes to manage and administer benefits, time off, taxes, and more.

Remote operates as an EOR, taking on the legal responsibility for international workers and processing things like time off and benefits programs to ensure compliance with local regulations. We absorb the liability and responsibility for payroll, taxes, benefits, and more so HR and people teams can focus on talent acquisition and the employee experience rather than international compliance and labor laws. 

Through the Remote API, you can take the experience one step further and reduce HR headaches for your customers by automatically syncing things like time off requests with our global employment platform. Imagine how fast your customers can grow when they don’t have to worry about avoiding costly compliance mistakes!

3. Data silos, logins, and duplicate work…no more!

One of the top pains we hear from people leaders is that their HR tools don’t talk to each other. This can mean endless rework and logins to manage and update data across multiple systems. 

We help minimize complexity for people leaders. That’s why we created the Remote API — to help our software partners in the HR and payroll space build custom connections that eliminate duplicate data entry for their customers and show all of their people and payroll data where they need it. With the Remote API, you can help consolidate global employee data and streamline data maintenance for HR teams to eliminate duplicate work and reduce the number of logins your customers need to remember. That’s one nice-to-have we all want in our lives!

Ready to get started? This list of endpoints is just the beginning. There is no limit for developers who want to leverage our simple yet powerful API interface to build custom applications that create unique user experiences.

Customer Onboarding: Enable customers to sign up with Remote without leaving your platform.

Customer Updates: Sync customer details across platforms.

Employee Onboarding: Add employees to Remote and complete the onboarding process end to end within your platform.

Country Availability: Shows all countries supported and the form schema to start a new employment.

Employee Updates and Offboarding: Sync employee updates across platforms or initiate an employee offboarding.

Document Management: Upload, download, and share employee files across platforms.

Time Off: Create and sync time off requests across platforms.

Payslips: Search and show employee payslips within your platform.

Billing: Search and show billing statements for custom queries.

SSO: Enable single sign-on for users who need to access the Remote platform directly.

Whether an employer's need is vast or small, the Remote API can help plug those gaps while delighting users in a single platform. Layering the Remote API onto your system means you can offer a new product to your customers before they start looking elsewhere; reduce the number of logins customers need to remember; prevent data silos from forming across your tech stack by showing your people and payroll data in one place; and so much more!

Ready to start the journey to becoming an API partner? Request access today to learn more and view our developer documents.

Remote makes it easier than ever for you to white label our employer of record (EOR) solution, empowering your customers to hire beyond their borders directly from your platform. We built our EOR solution with your customers in mind!

How the Remote API solves employers’ most complex problems

In our opinion, if APIs are designed well, then developers will love them — and if developers love them, they will invest heavily and even become evangelists for that API. At Remote, excellence is one of our core values. We respect a developer’s time and the resources they risk by building on our platform. 

With the Remote API, we are enabling developers to utilize global employment endpoints we have created to white label and offer Remote’s employer of record (EOR) services easily through their HR and payroll platforms. Ultimately, it is our mission to provide the tools and resources needed to create a delightful developer experience and to create value for our partners and joint customers. 

I just mentioned that one of the Remote values is excellence. Excellence extends to everything we do. That includes the way we communicate and, even more importantly, the things we build, the code we write, and the way we treat our people. We are making hard, boring things easy. But because we deal with important matters, like employee data and payslips, we must do so perfectly.

We believe developing your own API style guide can’t completely save you from challenges or risks, but this type of guide will help you make decisions openly, honestly, and with clarity. In this post, we will describe our API design principles, as well as our process for how new APIs are specced, reviewed, and tested. By the end, you should have at least a few ideas that you can take back to your own team. 

Here is what we have learned from building the Remote API over the past year.

It is very easy and tempting to try to solve too many problems at once, hence boiling the ocean. Pick a specific use case to tackle first rather than trying to solve many issues simultaneously. That way, you can focus on a single design and keep your API clean from the start. 

Remember, it is easy to add new features to an API but hard to remove them. Also, narrowing the scope and solving for a specific use case gives you an opportunity to get your API out into the world sooner and get developer feedback quicker so you can continue to make refinements.

At Remote, we tackled our global employee capabilities of the API first. To stay focused, we saw this iteration as solving the most common problem employers face in today's world — which is how to hire and onboard international employees easily!

2. Make sure it is fast and easy to get started.

It is no use building an excellent API if developers cannot understand it or get started quickly. You want to ensure developers who are unfamiliar with your API can complete a “Hello world” exercise in a reasonable amount of time. One metric you can use to evaluate this is “Time to First Hello World.” 
At Remote, we ensured developers would have a fast and seamless experience with our API by focusing on clear, easy-to-use documentation with lots of real-world examples and sample coding. As a result, our time to create a new employee in Remote is less than a minute.

Ideally, your APIs are intuitively consistent. That should be reflected in your endpoint names, input parameters, and output responses. Developers should be able to guess parts of your API even without reading the documentation. This means it should work similar to what they already know.  

We see a couple of requirements with consistency:

Consistency with industry standards: We decided to go with a REST API, and we are applying the industry standard criteria for predictable and consistent interactions with the API. You should adhere as closely as possible to accepted best practices in the industry. 

Consistency with your product: Your chosen field names should be based on what you call them in your product. Always avoid abbreviations, acronyms, and jargon. Be transparent.

One of the best ways to achieve consistency is by making sure your opinions and communication around the API design are concrete and written down. There is always a different way to look at something, but it is imperative you pick a side and stick with it. At Remote, we wrote down comprehensive API design guidelines in Notion, making sure we defined the consistent practices and patterns that we follow for our API. Then, we distributed those guidelines to every team member who might be involved in building, reviewing, or using our API.

4. Make troubleshooting less troublesome.

Incorrect and unclear errors are incredibly frustrating and will negatively affect adoption of your API. Still, it is common for engineers to pay little attention to the errors returned by their APIs. The result is developers getting stuck and eventually abandoning the project. For a better developer experience, make sure you return error messages that are easy to understand and actionable for those building to your API. 

At Remote, we built a REST API and used the standard HTTP status codes so clients can easily understand whether a request succeeded or failed. 

Bad design can limit performance. While designing an API, you should ensure a couple of things: 

Rate limit your API. For rate limits, when you are in the early stages of developing a new API it is hard to know what limits to implement. That is why we are taking a try-and-see approach. At Remote, we have started with a limit that seems reasonable based on what others have done, and we plan to closely monitor that and seek feedback from partners to determine if the limits are appropriate. Based on that we can always make adjustments. Setting rate limits are important to protect the infrastructure while increasing reliability and availability of the application. 

Paginate big collections: Quite often, APIs need to handle large datasets. An API call might end up returning thousands of items. This can overload the web application backend and even slow down clients that can’t handle large datasets. For that reason, it is important to paginate any large result sets. Right now at Remote, we have a plan to add pagination once the API adoption picks up speed.  

What is a breaking change? Any change that can stop an existing app from functioning as it was before your change. 

We all live in fear of a new API update breaking a client’s code. Just thinking about it makes us break out into a cold sweat. This is the last thing any developer needs, am I right?

At Remote, we are only just starting to think about how we will handle breaking changes. It is a balance between not being a drag on the development and the evolution of our product by insisting other teams can't make changes, and protecting our partners and customers from breaking. A few thoughts here:

The entire engineering organization needs to be aware of the API and how it is being used; thoughtful about how their changes impact the API; and contributing to incorporating their product changes into the API with the least impact possible.

Keep a good log of minor changes and share it with developers.

When breaking changes are unavoidable, have a policy on when a new version of the API becomes necessary, how you will support end of life older versions, and how to communicate this policy so developers feel comfortable they won't find themselves stranded on an old version. 

The reality is, things don’t always break when you want them to. Be sure to have a solid communication plan at the ready, just in case you have to respond to a breaking change you didn’t anticipate and cannot roll back.

Let’s face it: creating excellent, intuitive, consistent, and easy-to-use APIs is really difficult. Hopefully, we covered enough of the API design principles we follow at Remote to give you a great starting point. It is also important to mention that at Remote, we believe in learning together, listening to feedback from our developer community, and continuously making improvements based on the feedback we receive. So, while all our tips are important to a good design process, we are always keeping ourselves flexible as we move through the process. 

As a bonus, here are our top takeaways when you are building an API: 

Spend time thinking about your API design up front 

Collect feedback from multiple stakeholders

The Remote API is now available, and you can request access to our developer documentation here! 

How we designed the Remote API for an excellent developer experience

At Code BEAM 2020, our CTO and co-founder Marcelo Lebre introduced Four Patterns to Save your Codebase and your Sanity.Remote has been utilizing these patterns for over a year now, and the results have been incredible! The speed at which we can build out new ideas and features while  maintaining a consistent structure throughout all parts of the codebase is truly remarkable.

The patterns outlined below have served us well, but they do come with a drawback: boilerplate.

phx_gen_solid aims to solve the boilerplate problem as well as educate and empower others to create with the building blocks described here.

The patterns from the talk build on a set of principles first introduced in Design Principles and Design Patterns by Robert Martin.

Single-responsibility principle: "There should never be more than one reason for a class to change." In other words, every class should have only one responsibility.

Open-closed principle: "Software entities...should be open for extension, but closed for modification."

Liskov substitution principle: "Functions that use pointers or references to base classes must be able to use objects of derived classes without knowing it.”

Interface segregation principle: "Many client-specific interfaces are better than one general-purpose interface.”

Dependency inversion principle: "Depend upon abstractions, [not] concretions.”

There’s no need to deep dive into each of these, but they are important to keep in mind as they are the reasons behind each of the following solutions.

These four patterns are the building blocks behind everything we build in our Phoenix app at Remote. Surprisingly, there is very little overlap between each, and features usually find a happy home in one of the following ideologies.

Finders fetch data. They don’t mutate nor write, only read and present.

Engineering

Working async as a truly global engineering team

Introducing Swoosh Gallery

Help your customers onboard global talent using the Remote API

How Remote builds onboarding for 60+ countries

Announcing the Devs For Ukraine Conference

Written by • Cassidy Williams and Sara Vieira

How the Remote API solves employers’ most complex problems

How we designed the Remote API for an excellent developer experience

Introducing phx_gen_solid

Introducing React URL Modal

Leading virtual engineering teams in times of hyper growth

Supercharged forms guide: Using JSON schema in forms

A library to help navigate Ecto Data models

Open API Specifications: Improving Documentation & Communication

Welcoming Elixir creator José Valim as an advisor to Remote

Practical tips to improve your Elixir codebase

How to structure your Sass codebase

How to add dark mode to your website

How to use current_user in Elixir's Phoenix Framework