Prerequisites
- Ensure you are an admin of your Avature account before starting.
- After logging into Avature, search for "REST API"
- If you can not see the below menu items, you are not an admin of your Avature account.
- If you do not see these menu item, figure out who your Avature Admin is and ask them to give your account sufficient permissions or to take over the integration process.
- Check that you have a REST API available:
- Search for REST APIs and open the page.
- Check that you have at least 1 available REST API.
- If none are available, contact Avature support to enable one before you continue. Avature charges for each REST API, so this can sometimes take a few days.
Overview
Estimated, overall setup time: 45-60 minutes.
Fundamentally, there are 3 main steps you have to complete to set up the integration:
Generate a REST API key.
Create a custom REST API and configure its endpoints, filters and fields.
Export the API documentation and upload it to the connection flow.You have to create a new integration system user and security group for that user.
Some sections are only needed depending on the data your provider requested. If a step doesn't appear in your connection flow, skip it.
Generate the API key
- In Avature, search for REST API Key Configuration and open the page.
- Turn on the REST API Key toggle and click Generate new.
- Expiration: don't set an expiration date. If the key expires, the integration stops syncing until it's reconnected with a new key.
- IP restrictions: leave this empty, unless you would like to configure access via static IPs to allowlist. If you do please reach out.
- Copy the key and paste it into the connection flow.
- Click the blue Save button in the bottom left corner.
⚠️ Already have a key? Generating a new key replaces the current one, and any other tool using it will stop working. Check with your team first. If a key is already in use, you can paste that one instead.
Create the REST API
In this step you create the custom REST API that we'll connect to. All the following steps add endpoints and fields to this API.
Create the API
- Click Create in the top right corner.
- Under General Information, enter:
-
- Name and Description: use the value shown in the connection flow (for example, "Acme API"). This helps your team recognize later what the API is for.
Share with: Don't share. This keeps other Avature users from editing the API and breaking the integration by accident.
Configure the API
- Mode: select the mode shown in the connection flow.
- Read only: we only read data from Avature.
- Read and write: we also create candidates and applications in Avature.
- Format: JSON.
- Status: Pre-live.
- Custom URL path: copy the value from the connection flow and paste it exactly as shown.
Copy the full API URL
- Avature builds the full URL from your domain and the custom path. [screenshot of where it appears]
Copy it and paste it into the Full API URL field in the connection flow.
Configure the endpoints
Next, you'll add the routes, filters and fields we need to access your REST API. Which ones you need depends on the data your provider requested, so follow the lists shown in the connection flow. This section explains how to do each action in Avature and everything happens in the Available Routes section. Routes are shown as a tree under your API URL, for example /people People or /jobs Jobs.
Add a route
Routes are the endpoints we read from and write to, for example candidates, jobs or candidate files.
- In Available Routes, find where the connection flow says to add the route:
- Directly under your API URL for a main route, such as Jobs.
- Under an existing route for a sub-route, such as Files under /people People.
- Click Add Item at that spot.
- Select the route named in the connection flow.
Add a filter
Filters let us fetch only what changed instead of downloading all your data on every sync.
- In Available Routes, click the route named in the connection flow and open the Filter tab.
- Scroll to Query String Parameters.
- For each filter in the connection flow:
- Data type - Source: select the source shown in the connection flow, for example Last update (in days).
- Parameter name: enter the name shown in the connection flow, for example updated_after.
- To add another filter, click the blue Add filter button and repeat step 3.
Add fields
Fields decide which data we can read (Read tab) and write (Write tab) on a route.
- In Available Routes, click the route named in the connection flow and open the Read or Write tab, as the connection flow says.
- Under Data model, click Add Item.
- Select every field listed in the connection flow. They're listed alphabetically, as they appear in Avature.
- Click the > in the middle to move them over.
- Click the blue Add N items button in the bottom left.
Some fields have to use a specific name so we can recognize them, for example ref_number or salary_expectations.
- In the route's Data model, find the field you added.
- Change its name to the exact name shown in the connection flow.
⚠️ Enter parameter and field names exactly as shown in the connection flow: lowercase, with underscores, and no quotes. If a name is different, the setup check at the end may fail, or we may not be able to use that data.
Optional steps
The connection flow may also show these. If you are not interested in this you can skip them and add them later.
- Record Export Filters (on /jobs): only sync jobs that match your criteria, for example only active jobs.
- Screening questions: show your Avature screening questions to candidates when they apply. You need a form picker field on your jobs first.
Save the API and upload the documentation
Last, you'll save your REST API and upload its documentation file. We use this file to check that everything is set up correctly before we connect.
- Click the blue Save button in the bottom left corner.
- Open the REST API again from the REST APIs page.
- Scroll to the API Documentation section.
- Click Download. This saves a file called openapi.yaml.
- In the connection flow, upload the openapi.yaml file you just downloaded.
- Click Continue.
We'll now check the file against everything the connection flow asked you to set up. If something is missing, you'll see a list of the items that failed, for example "First Email field was added to the /people endpoint's read fields". After fixing the issue you will need to re-generate the openapi.yaml file for us to validate things again.
Troubleshooting
The API URL in the file does not match the URL given in step 2!
The URL you entered in the connection flow is different from the one in your REST API. Check that the subdomain and the custom URL path match exactly. A trailing slash doesn't matter. Then go back to the Full API URL step and correct it.
We ran into issues parsing your file! Did you upload the correct openapi.yaml file?
The uploaded file isn't the API documentation. Download it again from the API Documentation section of your REST API and upload that file unchanged.