How to integrate Ravio with Shapes

If Shapes is your HRIS (Human Resources Information System), you can keep Ravio up to date automatically over SFTP. Shapes has a dedicated Ravio integration with a self-serve setup wizard, so you control who the export covers and which columns it carries, without raising a ticket with anyone.

This guide covers both sides: the Ravio side first, then the Shapes wizard. It takes around 15 minutes.

📌 This is the dedicated Ravio integration in Shapes, not the generic Dynamic Export option. If you've been pointed at Dynamic Export, use the Ravio integration instead. It starts from a ready-made column set, so you're editing a working export rather than building one from scratch.

What is SFTP?

SFTP (Secure File Transfer Protocol) is a secure way to move files between two systems over the internet.

📮 Think of it like a locked post box. You drop a file in and lock it, and only someone with the right key can open it.

Once it's set up it behaves like a live integration. Shapes sends a fresh file every day, Ravio picks it up and processes it, and new joiners are mapped to Ravio positions and levels without you doing anything.

Before you start

You'll need:

Admin permissions in Shapes. If you don't have them, share this guide with your Shapes administrator, who can complete the export side for you.
Access to your Ravio integration setup flow. You'll find it under Manage my data > HR system.
About 15 minutes. Roughly ten minutes on the Ravio side, five in the Shapes wizard.

It's worth having your IT team on hand for the credentials step.

How the setup works

There are three stages:

Set up your SFTP connection in Ravio. This gives you the host, username, and credential details you'll need.
Run the Shapes setup wizard. Three steps: connect, choose who the export covers, and compose your columns.
Column mapping. Once your first file lands, Ravio maps the columns and puts the connection live.

Stage 1 – Set up your SFTP connection in Ravio Step 1 – Choose which data to share

The first screen asks which data should be available in this integration. You can switch off Gender and Date of birth, though Gender is required for Ravio's Pay Equity module.

Whatever you choose here, make the same choice in the Shapes wizard. Shapes decides what actually goes in the file, so leaving a column in Shapes that you've switched off in Ravio just means sending data Ravio won't use.

Step 2 – Choose your credential type

This is how Shapes proves who it is when it connects. Shapes generates an SSH (Secure Shell) public key for you, so choose RSA key pair.

Ravio also supports a password and a PEM certificate, but the key pair is the route the Shapes integration is built around. If you paste a private key in by mistake, treat it as compromised and ask Shapes to generate a new one.

Step 3 – Save your connection details

On the next screen Ravio gives you everything Shapes needs:

Host: sftp.kombo.dev
Port: 22
Directory: the root directory (/)
Username: unique to your company
SSH Key: this will be copied from Shapes

The host, port, and directory are the same for everyone. The username and key are specific to you.

⚠️ Copy these details somewhere safe before you move on. Your credentials are hidden once setup is complete, and you'll need them in Stage 2.

Stage 2 – Run the Shapes setup wizard

Step 4 – Connect

Shapes generates an SSH public key for the connection. Copy it and paste it into the credential field in your Ravio setup flow (Stage 1, Step 2), or send it to your Ravio contact to authorise.

Then enter the details from Stage 1:

The host (sftp.kombo.dev)
The username Ravio issued you
The port, which defaults to 22

Step 5 – Choose who the export covers

Set the employee scope. Scope the export to active employees, and include anyone on leave.

This matters more than it looks. Ravio fully overwrites your data on each run, so anyone missing from the file is treated as having left. That's how leavers drop out of Ravio automatically, and it's why the file shouldn't carry terminated employees.

Step 6 – Compose your columns

Shapes starts you off with 14 default columns. You can re-point any of them at a different field in Shapes, and add or remove columns as you like.

These are the defaults, in order:

#	Column	Format or values
1	Employee Unique ID	Your company-assigned employee number
2	Job Title	Free text
3	Work City	Free text
4	Work Country	ISO code in capitals, or the full country name
5	Team	Free text
6	Manager Unique ID	The manager's Employee Unique ID, so it matches column 1
7	Employment Type	Full Time, Part Time, Contractor, or Intern
8	Start Date	D/M/YYYY
9	Gender	As stored in Shapes
10	Date of birth	D/M/YYYY
11	Pay Currency	ISO-4217, for example USD or EUR
12	Pay Rate	Numeric, with symbols and separators stripped
13	Pay Period	MONTH or YEAR
14	FTE %	Decimal ratio, for example 1, 0.8, or 0.5

The defaults cover most of what Ravio needs. Four things are worth adding or checking before you finish:

First name, last name, and email. Add these if you want employees to appear by name in Ravio. Without them your integration runs anonymously and people appear by ID. Email is what lets Ravio match managers to their own teams, so managers only see their own people. Most customers share both.
Job Grade, Job Level, or Job Track. Add whichever your levelling framework uses, if you store it in Shapes. Ravio uses it to map your employees to your own framework. Without it, we level using job title, team, and reporting hierarchy instead.
Gender and Date of birth. Both are in the default set. Remove them here if you switched them off in Ravio at Stage 1. Gender is required for the Pay Equity module.
Anything else you think is relevant. If there are any other custom fields / dimensions you’d like to see in Ravio, make sure they are added at this step.

💡 Ravio's data requirements article lists every field we use and whether it's required or recommended. It's worth working through it as a checklist on this screen.

Step 7 – Save

That's the export live. Shapes now runs the sync daily, writing RAVIO_YYYY_MM.csv, one file per calendar month, refreshed in place on every run. The current month's file always reflects your latest data. 🎉

Stage 3 – Set this live in Ravio Step 8 – Copy SSH key from Shapes and set up integration

Copy over the SSH key generated by Shapes into the Ravio integration flow and click Set up integration.

This is the step that matters most, and the easiest one to miss. Clicking Set up integration adds your credentials to the SFTP server and starts Ravio listening for your file. Until you click it, nothing Shapes sends will be processed.

Stage 4 – Column mapping and going live

When your first file arrives, Ravio maps your Shapes column names to the fields in the app. This happens once.

The connection goes through a quality assurance check before it goes live, so there's a short gap between your first file landing and your data appearing.
No action is needed from you. We'll get in touch if anything is unclear, for example if a column name is ambiguous and we need your help interpreting it.
Once mapping is done, your data syncs automatically on every export.

After your file is processed you'll see an empty SFTP folder. That's expected. Files are moved to a processed folder as soon as they're picked up.

Troubleshooting

What you're seeing	What to do
You can't find Ravio in the Shapes integrations list	The dedicated Ravio integration is recent, so check you're looking at the current integrations catalogue rather than a cached page. If it still isn't there, contact Shapes support.
The sync runs in Shapes, but nothing appears in Ravio	Check you clicked Set up integration at the end of the Ravio flow. This is the most common cause.
Authentication is failing	Double-check the SSH public key was pasted in full with no line breaks lost, and that the username matches the one Ravio issued you. If it still fails, get in touch and we'll look at the server logs with you.
Employees appear as numbers rather than names	First name, last name, and email aren't in your column set. Add them at Step 8 and tell us, so we can map them.
Terminated employees are still showing in Ravio	Check the scope you set at Step 7. If the export covers your full employee tree rather than active employees only, leavers keep arriving in the file and Ravio keeps showing them.
Job levels look wrong, or employees are unlevelled	Add your Job Grade, Job Level, or Job Track column at Step 8, then tell us so we can map it.
You've lost your username or credentials	Credentials are hidden once setup is complete, so we can't retrieve them for you. Get in touch and we'll recreate the connection.

Keeping things running

Once it's live there's nothing to maintain. Shapes sends a new file daily and Ravio processes it automatically.

Two things worth remembering:

If you add or re-point a column in Shapes, tell us so we can map it.
If you rotate the SSH key, update it in both Shapes and Ravio.

Need a hand?

Our Integrations team is happy to help with any part of this, including deciding which columns to send.

Email integrations@ravio.com
Or book a call directly
You can also reach your CSM (Customer Success Manager) or use live chat in the Ravio app

For questions about the Shapes side of the connection, Shapes support is the fastest route.