Eploy enables Candidates and Users to upload various document types throughout the recruitment process. It can also generate documents, such as Contracts, for digital signing during Onboarding.
Documents are often required to be exported with a new starter export. For details on configuring a new starter export via the Eploy RESTful API, see the Eploy RESTful API: New Starter Exports guide.
This guide explains how to set up an interface to identify and extract relevant documents for each new employee.
The recommended process looks like this:
đ Note - throughout this guide, especially within example code, you'll see reference to Companies and Placements. These are historical terms which now refer to Organisations and Hires, respectfully, but are still known as Companies and Placements within the API code.
Get File Types
Understanding File Types in the Eploy system is essential for categorising documents for proper use and export. This GET request retrieves all File Types, allowing you to identify which to include in your interface. Each File Type has a unique Id for filtering during searches, and the Description indicates the type of file stored. Note that the Reference, ArchiveDate", and ParentId properties are irrelevant for File Types and can be disregarded.
You can either make the Get File Types request once while designing your document export integration, or incorporate it into the process to discover all File Types dynamically and create corresponding categories/folders in the target system.
API ENDPOINT
GET /api/options/dropdown/193
HEADERS
Authorization: Bearer (access_token)
EXAMPLE RESPONSE
{
"Values": [
{
"Id": "2",
"Description": "CV",
"Reference": "",
"ArchiveDate": null,
"ParentId": null
},
{
"Id": "3",
"Description": "General",
"Reference": "",
"ArchiveDate": null,
"ParentId": null
} ]
} (etc...)
1. Hire Search
The process begins by identifying Hires in Eploy ready for document export. If a new starter export is running and marking records with an export log, the search is straightforward: find Hires that have been marked for export but have not had documents exported yet.
If no new starter export is running, the Hire Search must use alternative criteria similar to a new starter export. For details, refer to the Hire Search example in the Eploy RESTful API: New Starter Exports guide.
The example below illustrates how to identify Hires marked by the new starter export but not yet exported by the document export. There should be two ExportPackages in Eploy: one for New Starter Export and another for Document Export.
API ENDPOINT
POST /api/placements/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Placement.HasBeenExportedBy",
"Value": 10,
"Operation": "Equals"
},
{
"Route": "Placement.HasBeenExportedBy",
"Value": 11,
"Operation": "NotEquals"
} ],
"ResponseBlocks":[
"PlacementID",
"Candidate",
"Vacancy", ]
}10 = The "New Starter Export" ExportPackageID
11 = The "Document Export" ExportPackageID
EXAMPLE RESPONSE
{
"Records": [
{
"PlacementId": 17,
"Vacancy":
{
"Id": 16,
"Url": "https://systemname.eploy.net/api/vacancies/16"
},
"Candidate":
{
"Id": 5023,
"Url": "https://systemname.eploy.net/api/candidates/5023"
}
},
{
"PlacementId": 35,
"Vacancy": {
"Id": 1003,
"Url": "https://systemname.eploy.net/api/vacancies/1003"
},
"Candidate": {
"Id": 1010,
"Url": "https://systemname.eploy.net/api/candidates/1010"
}
} ],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
2. Get Export References
Many New Starter Exports provide a unique identifier for each new starter when marking Hires with an export log in Eploy. This is done by setting the ExternalReference in the Export Log entry at the end of the New Starter Export process. These identifiers can then be accessed via the API, allowing easy linking of document files to the corresponding employee in an HR/Payroll system.
This process is optional and depends on whether a New Starter Export is configured to return the unique identifier. Some exports may store the identifiers differently, such as in a field or custom question for the Candidate or Hire. This guide does not cover data retrieval from these records; for that, please see the Eploy RESTful API: New Starter Exports guide.
API ENDPOINT
POST /api/export/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Export.ExportPackageId",
"Value": 10,
"Operation": "Equals"
},
{
"Route": "Export.Success",
"Value": true,
"Operation": "Equals"
},
{
"Route": "Placement.PlacementID",
"Value": [17,35],
"Operation": "Equals"
} ]
}
NEW STARTER EXPORT ExportPackageID
10= The "New Starter Export" ExportPackageID
17,35 = PlacementIDs returned from the Placement Search
EXAMPLE RESPONSE
{
"Records": [
{
"ExportPackageId": 7,
"ExternalId": "17",
"DateExported": "2024-01-05T09:45:53.063Z",
"Success": true,
"Placement":
{
"Id": 17,
"Url": "https://systemname.eploy.net/api/placements/17"
}
},
{
"ExportPackageId": 7,
"ExternalId": "35",
"DateExported": "2024-01-05T09:45:53.063Z",
"Success": true,
"Placement":
{
"Id": 35,
"Url": "https://systemname.eploy.net/api/placements/35"
}
} ],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
3. Get File ID(s)
To access document files via the API, you need to know the "FileIDs" for each file. This can be done by searching the files endpoint with the relevant ID(s) for:
The File Types required (see Get File Types, above)
The Record IDs associated with the files (these could be PlacementIDs, CandidateIDs, or VacancyIDs from the Hire Search, depending on the required File Types and their linked Record Types).
The Record Type linked to the files:
Placements RecordTypeID = 11
Candidates RecordTypeID = 3
Vacancies RecordTypeID = 4
Please note that you may need to perform multiple searches to identify FileIDs for each Record Type.
In some cases, it may be necessary to obtain documents associated to other RecordTypes that are not directly associated to the Placement, such as the Application, Company or Contact. This is still possible, but it would be necessary to perform an additional search request to discover the RecordIDs for these. Please see the section Identifying RecordIDs for Other Related Records, below, for more information.
Applications RecordTypeID = 18
Companies RecordTypeID = 1
Contacts RecordTypeID = 2
Also note, Candidate CVs are a special type of file in Eploy and these exist on a different endpoint to other File Types. If you need to extract Candidate CVs, please see the section Candidate CVs, below.
API ENDPOINT
POST /api/files/file/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters": [
{
"Operation": "Equals",
"Route": "File.StoredFileType",
"Value": [28,29]
},
{
"Operation": "Equals",
"Route": "File.RecordID",
"Value": [17,35]
},
{
"Operation": "Equals",
"Route": "File.RecordTypeID",
"Value": 11
} ],
"ResponseBlocks": [
"StoredFilePathId",
"Title",
"StoredFileType",
"Filename",
"Record",
"Download",
"RecordType"
]
}28, 29 = The FileType(s) required for each RecordType
17, 35 = Record IDs returned from the Placement Search. In this example, the PlacementIDs are being used, but these can be adpated to the Candidate or Vacancy IDs if searching for files against these Record Types
11 = The Record Type that the files relate to (Placements in this example)
EXAMPLE RESPONSE
{
"Records": [
{
"StoredFilePathId": 198,
"Title": "Offer Letter",
"StoredFileType":
{
"Id": "28",
"Description": "Offer Letter",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 193,
"Url": "https://systemname.eploy.net/api/options/dropdown/193",
"Description": "File Types",
"Type": "dropdown"
}
}
],
"TotalRecords": 5,
"CurrentPage": 1,
"TotalPages": 1
}
4. Get File Metadata
This optional step helps you gather more details about the identified files, including name, size, and extension. This information can be useful before downloading, as it may influence how the file is retrieved or if it should be retrieved at all. This GET call would need to be repeated for each file identified in the search described in the Get File ID(s) section, above.
API ENDPOINT
GET /api/files/file/198
198 = The StoredFilePathID returned from the File Search
HEADERS
Authorization: Bearer (access_token)
EXAMPLE RESPONSE
{
"StoredFilePathId": 198,
"Title": "Offer Letter",
"StoredFileType":
{
"Id": "28",
"Description": "Offer Letter",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 193,
"Url": "https://systemname.eploy.net/api/options/dropdown/193",
"Description": "File Types",
"Type": "dropdown"
}
},
"Record":
{
"Id": 17,
"Url": "https://systemname.eploy.net/api/placements/17"
},
"FileName": "Offer - Chris Ventura - 08 March 2018 13-48-08.docx",
"FileExtension": "docx",
"FileSize": 86216,
"DateCreated": "2018-03-08T00:00:00Z",
"DateLastModified": "2018-03-08T00:00:00Z",
"DateLastAccessed": "2018-03-08T00:00:00Z",
"SignatureCandidate": null,
"SignatureCandidateStatus": null,
"SignatureContact": null,
"SignatureContactStatus": null,
"Download": "https://systemname.eploy.net/api/files/file/download",
"Creator":
{
"Id": 1,
"Url": "https://systemname.eploy.net/api/users/1"
},
"Modifier": null,
"CreationDate": "2018-03-08T13:48:08.74Z",
"ModificationDate": "2020-05-12T16:50:24.827Z"
}
5. Download File(s)
Use the following call to download each of the document files. This GET call would need to be repeated for each file identified in the search described in the Get File ID(s) section, above.
API ENDPOINT
GET /api/files/file/198/download
198 = StoredFilePathID returned from the File Search
HEADERS
Authorization: Bearer (access_token)
(file returned in the response)
6. Mark Placement Records 'Exported'
Finally, after all the files have been successfully transferred, you can mark the Placements as exported using the ExportPackageId associated to the Document Export, so they drop from the list when you next perform the placement search. Marking the record also has other benefits; end users are able to see the export logs in Eploy and can build dashboards based on the export data, so they know which records were exported and when. Users with permission may also âclearâ an export flag to manually re-trigger it, if this is ever necessary.
API ENDPOINT
POST /api/export
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"ExportPackageId": 11,
"PlacementIDs":
[
{
"Id": 17,
"ExternalReference": "DOCUMENT EXPORT 123"
},
{
"Id": 35,
"ExternalReference": "DOCUMENT EXPORT 456"
}
]
}
11 = The "Document Export" ExportPackageID
17, 35 = Record IDs returned from the Placement Search and successfully processed
âExternalReferenceâ can be used to put additional information into the export log, e.g. a unique identifier.
Please note: there is no response body for this API call but a 200 response means that you have successfully marked the Placement(s) as exported.
Candidate CVs
As Candidate CVs are stored differently in Eploy, the search used to identify the File IDs and the GET calls to retrieve the CV file metadata and download the CV file are different to other file types, as described below.
Get CV ID(s)
To access CV files via the API, you need to know the FileIDs for each CV. This can be done by searching the CVs endpoint with the relevant Candidate IDs.
API ENDPOINT
POST /api/files/cv/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Candidate.CandidateID",
"Value": [5023,1010],
"Operation": "Equals"
}
],
"ResponseBlocks":
[
"Candidate",
"StoredFileType",
"StoredFileId",
"FileName",
"Download"
]
}5023, 1010 = CandidateIDs returned from the Placement Search
EXAMPLE RESPONSE
{
"Records":
[
{
"StoredFileId": 37,
"StoredFileType":
{
"Id": "2",
"Description": "CV",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 193,
"Url": "https://systemname.eploy.net/api/options/dropdown/193",
"Description": "File Types",
"Type": "dropdown"
}
},
"FileName": "John Taylor.doc",
"Download": "https://systemname.eploy.net/api/files/cv/37/download",
"Candidate":
{
"Id": 1010,
"Url": "https://systemname.eploy.net/api/candidates/1010"
}
},
{
"StoredFileId": 63,
"StoredFileType":
{
"Id": "2",
"Description": "CV",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 193,
"Url": "https://systemname.eploy.net/api/options/dropdown/193",
"Description": "File Types",
"Type": "dropdown"
}
},
"FileName": "Store9.doc",
"Download": "https://systemname.eploy.net/api/files/cv/63/download",
"Candidate":
{
"Id": 5023,
"Url": "https://systemname.eploy.net/api/candidates/5023"
}
}
],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
Get CV File Metadata
This optional step helps you gather more details about the identified CV files, including name, size, and extension. This information can be useful before downloading, as it may influence how the file is retrieved or if it should be retrieved at all. This GET call would need to be repeated for each file identified in the search described in the Get CV ID(s) section, above.
API ENDPOINT
GET /api/files/cv/37
37= The StoredFileID returned from the CV Search
HEADERS
Authorization: Bearer (access_token)
EXAMPLE RESPONSE
{
"StoredFileId": 37,
"StoredFileType":
{
"Id": "2",
"Description": "CV",
"Reference": null,
"ArchiveDate": null,
"ParentId": null,
"OptionType":
{
"Id": 193,
"Url": "https://systemname.eploy.net/api/options/dropdown/193",
"Description": "File Types",
"Type": "dropdown"
}
},
"FileName": "John Taylor.doc",
"FileExtension": "doc",
"FileSize": 86016,
"DateCreated": "2008-10-01T00:00:00Z",
"DateLastAccessed": "2008-10-01T00:00:00Z",
"DateLastModified": "2008-01-17T00:00:00Z",
"Download": "https://systemname.eploy.net/api/files/cv/37/download",
"Candidate":
{
"Id": 1010,
"Url": "https://systemname.eploy.net/api/candidates/1010"
},
"Creator":
{
"Id": 1,
"Url": "https://systemname.eploy.net/api/users/1"
},
"Modifier": null,
"CreationDate": "2008-01-17T10:10:16.28Z",
"ModificationDate": "2020-04-01T20:39:36.467Z"
}
Download CV(s)
Use the following call to download each of the CVs. This GET call would need to be repeated for each file identified in the search described in the Get CV ID(s) section, above.
API ENDPOINT
GET /api/files/cv/37/download
37= StoredFileID returned from the CV Search
HEADERS
Authorization: Bearer (access_token)
(file returned in the response)
Identifying RecordIDs for Other Related Records
Search for an Application ID by CandidateID/VacancyID
To extract files linked to a candidate's Application record, you must identify the Application IDs. The Application record is not directly tied to the Hire but is associated with both a CandidateID and a VacancyID. By using the CandidateIDs and VacancyIDs from the Hire Search, you can obtain the relevant Application IDs. Then, you can follow the Get File ID(s) process, setting File.RecordTypeID to 18 and filtering by the identified ApplicationIDs in File.RecordID.
API ENDPOINT
POST /api/applications/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Candidate.CandidateID",
"Value": [5023, 1010],
"Operation": "Equals"
},
{
"Route": "Vacancy.VacancyID",
"Value": [16, 1003],
"Operation": "Equals"
}
],
"ResponseBlocks":
[
"ApplicationID",
"Candidate",
"Vacancy"
]
}
5023, 1010 = CandidateIDs returned from the Placement Search
16, 1003 = VacancyIDs returned from the Placement Search
EXAMPLE RESPONSE
{
"Records":
[
{
"ApplicationId": 38,
"Vacancy":
{
"Id": 16,
"Url": "https://systemname.eploy.net/api/vacancies/16"
},
"Candidate":
{
"Id": 5023,
"Url": "https://systemname.eploy.net/api/candidates/5023"
}
},
{
"ApplicationId": 360,
"Vacancy":
{
"Id": 1003,
"Url": "https://systemname.eploy.net/api/vacancies/1003"
},
"Candidate":
{
"Id": 1010,
"Url": "https://systemname.eploy.net/api/candidates/1010"
}
}
],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}
Search for a CompanyID/ContactID by VacancyID
To extract files linked to the Company or Contact record associated to the Vacancy, you must identify the relevant IDs. The Company and Contact records are not directly tied to the Placement but is associated with the VacancyID. By using the VacancyIDs from the Placement Search, you can obtain the relevant Company and Contact IDs. Then, you can follow the Get File ID(s) process, setting File.RecordTypeID to 1 (for Company files) or 2 (for Contact files), and filtering by the identified Company/Contact record IDs in File.RecordID.
API ENDPOINT
POST /api/vacancies/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Paging":
{
"RecordsPerPage": 10,
"RequestedPage": 1
},
"Filters":
[
{
"Route": "Vacancy.VacancyID",
"Value": [16, 1003],
"Operation": "Equals"
}
],
"ResponseBlocks":
[
"Company",
"Contact"
]
}16, 1003 = VacancyIDs returned from the Placement Search
EXAMPLE RESPONSE
{
"Records":
[
{
"Company":
{
"Id": 15,
"Url": "https://systemname.eploy.net/api/companies/15"
},
"Contact":
{
"Id": 25,
"Url": "https://systemname.eploy.net/api/contacts/25"
}
},
{
"Company":
{
"Id": 18,
"Url": "https://systemname.eploy.net/api/companies/18"
},
"Contact":
{
"Id": 1,
"Url": "https://systemname.eploy.net/api/contacts/1"
}
}
],
"TotalRecords": 2,
"CurrentPage": 1,
"TotalPages": 1
}