Document Exports

Go to examples:

Get File Types

1. Placement Search

2. Get Export References

3. Get File ID(s)

4. Get File Metadata

5. Download File(s)

6. Mark Placement Records 'Exported'

Candidate CVs:

- Get CV ID(s)

- Get CV File Metadata

- Download CV(s)

Identifying RecordIDs for Other Related Records:

- Search for an Application ID by CandidateID/VacancyID

- Search for a CompanyID/ContactID by VacancyID

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:

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. Placement Search

The process begins by identifying Placements 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 Placements that have been marked for export but have not had documents exported yet.

If no new starter export is running, the Placement Search must use alternative criteria similar to a new starter export. For details, refer to the 'Placement Search' example in the Eploy RESTful API: New Starter Exports guide.

The example below illustrates how to identify Placements 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 Placements 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 Placement. 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")
The Record IDs associated with the files (these could be PlacementIDs, CandidateIDs, or VacancyIDs from the Placement 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

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

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.

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.

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.

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.

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.

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 Placement but is associated with both a CandidateID and a VacancyID. By using the CandidateIDs and VacancyIDs from the Placement 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
}

Search

Welcome to the Eploy Knowledge Base

Document Exports

Get File Types

API ENDPOINT

HEADERS

EXAMPLE RESPONSE

1. Placement Search

API ENDPOINT

HEADERS

BODY

EXAMPLE RESPONSE

2. Get Export References

API ENDPOINT

HEADERS

BODY

EXAMPLE RESPONSE

3. Get File ID(s)

API ENDPOINT

HEADERS

BODY

EXAMPLE RESPONSE

4. Get File Metadata

API ENDPOINT

HEADERS

EXAMPLE RESPONSE

5. Download File(s)

API ENDPOINT

HEADERS

6. Mark Placement Records 'Exported'

API ENDPOINT

HEADERS

BODY

Candidate CVs

Get CV ID(s)

API ENDPOINT

HEADERS

BODY

EXAMPLE RESPONSE

Get CV File Metadata

API ENDPOINT

HEADERS

EXAMPLE RESPONSE

Download CV(s)

API ENDPOINT

HEADERS

Identifying RecordIDs for Other Related Records

Search for an Application ID by CandidateID/VacancyID

API ENDPOINT

HEADERS

BODY

EXAMPLE RESPONSE

Search for a CompanyID/ContactID by VacancyID

API ENDPOINT

HEADERS

BODY

EXAMPLE RESPONSE