Connecting and using the Atlas integration

This guide walks you through connecting Atlas to Refari, publishing Atlas projects to your Refari job board, managing them day to day, and checking that applications and candidate progress are moving between the two systems.

What the integration does

Atlas is your applicant tracking system (ATS), the system where you manage recruitment projects, people and applications. Atlas calls a job a project. Your public job board is the careers page on your website where anyone can browse and apply for your advertised roles.

Note: There is no Refari panel or job board partner section inside Atlas. Refari reads projects from the Atlas API. You do not configure webhooks or maintain a second copy of an advert in Refari.

Before you start

You will need:

• An Atlas administrator login, or permission to create an API key.
• The Refari Integrator connection link sent to you by Refari. Use it within 30 days. If it has expired, ask Refari Support for a new link.
• A list of the categories you want candidates to use when filtering your job board.

Step 1: Create the Job Board Category field

Refari reads this project custom field to place each advert in the right category filter on your job board. The exact name matters because Refari looks for that name when it imports a project.

1. In Atlas, open the settings used to manage custom fields or custom attributes for projects.
2. Create a project custom field named exactly Job Board Category.
3. Set it to the options (dropdown) type and allow one choice only.
4. Add the options that fit your team. For example: Accounting and Finance, Engineering, Information Technology, and Sales and Marketing.
5. Save the field, then make sure your team selects one option on every project intended for the job board.

Atlas may place project custom fields in a different part of the settings in your version. If you cannot find them, ask Atlas support where project custom attributes are managed.

Idea: Keep the list short and use candidate-friendly labels. A controlled dropdown avoids separate filters such as "IT", "I.T." and "Information Technology" appearing on the same board.

Refari also recognises the earlier field name Job Category, without regard to capital letters. If neither custom field has a value, Refari falls back to Atlas's built-in Job Function. The standard field name for new connections is Job Board Category.

Step 2: Create the Atlas API key

An API key is a secure credential that lets Refari read the Atlas information needed for your board and write candidate activity back to Atlas.

1. Sign in to Atlas with an administrator account.
2. Open the area where your Atlas account manages API keys, then create a new key.
3. Give the key a clear name, such as Refari.
4. Use the table below as the complete permission list. Turn on only the permissions shown as Read and write. Leave every other permission switched off.

Atlas may place API key controls in a different part of the account settings in your version. If you cannot find them, ask Atlas support for the exact location.

5. Create the key and copy the full value while Atlas shows it.

Keep the API key private. Treat it like a password and paste it only into the Refari connection page. If it is exposed, revoke it in Atlas and ask Refari Support for a new connection link.

Step 3: Paste the key into Refari

1. Open the Refari Integrator connection link sent to you by Refari.
2. Select Atlas if the page asks you to choose your ATS.
3. Paste the full key into API Key. This is the only required Atlas credential. If you see Agency ID, leave it blank unless Refari has given you a value.
4. Select Connect Atlas.

Use the table in Step 2 as the full permissions guide for this connection. The reminder on this page that Campaigns and Finance are not needed covers two of the permissions that remain off. Meetings, Emails and anything else not listed for access remain off as well.

Connection complete: When you see Atlas Connected, Refari begins importing your Atlas users first, followed by eligible projects. There are no webhook settings to add.

Step 4: Publish your first project

A project appears on your Refari job board only when all three publishing rules are true:

• Public Job Advert is switched on.
• The project state is active.
• The project has not been deleted.

Protect confidential projects. An active Atlas project is not automatically a public advert. The Public Job Advert switch on the project's Job Description tab controls whether Refari may publish it. The switch is off by default. Turn it on only for a project intended for your public website.

The project must also contain the information Refari requires to build the advert:

• ☐ Title: Check that the project has a job title. Without one, Refari has no advert title and the project will not import.
• ☐ Owner: Check that the project has an owner and that the owner has an email address in Atlas. Without both, Refari cannot link the advert to the right recruiter and the project may not import.
• ☐ Job Board Category: Select a value in Job Board Category, or in Atlas's built-in Job Function field. Without either value, Refari cannot categorise the advert and the project will not import.
• ☐ Location: Check that the project has a location. Without one, Refari cannot assign the advert to a location and the project will not import.
• ☐ Work type: Check that the project has a contract type, which Refari uses as the work type. Without one, Refari cannot set the advert's work type and the project will not import.

On the project, open the Job Description tab and find the Public Job Advert switch among the advert details. It stays off until you switch it on. Turn it on only when the project is ready for your public website. If it is not on, Refari does not publish the advert: no switch, no advert.

Save the project, then check your Refari job board. Refari starts a job poll every 10 minutes and staggers connected accounts by up to about 2 minutes. In practice, allow about 10 to 12 minutes for a new project or edit to appear. It is not an instant update.

Your job sync is working when the project appears on the board with the correct title, category, location, work type and recruiter.

Using the integration day to day

Edit a live advert

Edit the project in Atlas and save it. Refari updates the existing advert on the next job poll. Do not maintain a separate version in Refari.

Take an advert down

For the quickest take-down, switch Public Job Advert off or close the project in Atlas. The board normally catches up within about 10 to 12 minutes. A deleted project is guaranteed to be found by the full reconciliation sweep, which runs every 6 hours. If the advert must come down promptly, switch Public Job Advert off before deleting the project.

Add another project

Create and maintain it in Atlas. Complete the five required items, make it active, then switch Public Job Advert on when it is ready for the public board.

Show the right recruiter

Atlas users are imported as Refari recruiters. Refari links an Atlas user to an existing recruiter by email address when needed. Every Atlas user who owns public projects should have a current email address on their user record. Without one, Refari cannot create that recruiter profile and their projects may not import correctly. Add the email in Atlas and save the user.

Enter salary text that Refari can read

Atlas stores salary as free text, so use a clear number or range and include the pay period. These formats parse cleanly:

• $120,000 - $140,000 per annum
• 90k-110k
• 150000 per annum

Words alone, such as Competitive or Negotiable, DOE, do not produce a salary figure. A bare hourly number below 100, such as $65 per hour, supplies the hourly period but not the numeric figure. Check the live advert after the next poll whenever the salary wording changes.

What happens when someone applies

For an application that includes a CV, Refari performs these actions in order:

1. Uploads the CV to Atlas as a resume file.
2. Creates an applicant on the relevant project using that CV, with the candidate's contact details and cover note.
3. Leaves the applicant pending in Atlas until a recruiter accepts them. Atlas then makes them a candidate in the project's pipeline.
4. Checks Atlas about every 10 minutes and sends the candidate's project stage back to Refari. A rejection is recorded as Rejected.

If your Refari application form allows applications without a CV, Refari creates or matches the person in Atlas and adds them directly to the project's candidate pipeline. A candidate registration creates or updates an Atlas person and attaches their CV. A referral creates or matches a person and adds the referral details as a note.

Candidate source: Atlas keeps the person's original source. If that person already existed from your own sourcing, Refari does not replace the source when their details are updated.

In Atlas, the recruiter will see a new applicant on the matching project. For an application with a CV, the entry arrives in a pending state with the person's contact details, cover note and CV or resume file. After the recruiter accepts the applicant, Atlas shows the person as a candidate in the project's pipeline.

Test the connection properly

1. Choose a public, active project that has all five required items.
2. Open the advert on your Refari job board and submit an application with a CV.
3. Confirm that the applicant appears on the matching Atlas project with the CV.
4. Accept the applicant in Atlas, move the candidate to another project stage, then allow about 10 to 12 minutes for Refari to receive the stage.
5. Repeat with a registration form if candidate registrations are part of your Refari set-up.

Do not test with a recruiter's work email address. That address already belongs to a user or recruiter record, so candidate matching can collide with it and make a healthy connection look broken. Use a personal address and a different address for each test candidate.

Troubleshooting

Final Notes

Keep Atlas as the source of truth for projects, project owners and candidate stages. If you still need help, raise a ticket through support.refari.co and include the Atlas project title, what you expected to happen, and the approximate time of your last test.

Other articles you might be interested in:  How to Re-send Applications or Registrations to Your Applicant Tracking System