How to add a Form to a Candidate

Introduction

Process

1. Retrieve formId:

• Link to the API documentation: Get Form Collection

• Use Postman to make a GET request for the Forms collection and obtain the formId from the received forms collection. Each received form has a property id which should be used as the formId when creating a candidate form.

2. Formulate the Relation:

• Combine the candidateId, formId, and required actions to create the candidateForm relation.

3. Create the Relation via API:

• Link to the API documentation: Create Candidate Form

• Endpoint: /candidate-forms

• Method: POST

• Request Body:

{
  "candidateId": "your_candidate_id",
  "formId": "your_form_id",
  "actions": [
    "complete",
    "download"
  ],
  "fileId": "your_file_id",
  "signatureId": "your_signature_id",
  "isMandatory": false,
  "isPreliminary": false
}

Important Details

Required Fields:

• candidateId: The unique identifier for the candidate.

• formId: The unique identifier for the form.

• actions: An array of actions to be performed on the form

Optional Fields:

• fileId: If the form type is a file you can replace original attachment with a personal one

• signatureId: Required if the form requires a signature process. The signatureId should be obtained from the signature flow documentation: Get Signature by ID. If the signature flow requires a candidate signature, you need to add the eSign action in actions.

• isMandatory: Boolean value to indicate if the form is mandatory for the candidate (default is false).

• isPreliminary: Boolean value to indicate if the form should be displayed first when the candidate opens the Filebox v2 (only one form can have isPreliminary set to true).

Actions Based on Form Type:

• Form actions: At least one action is required. The allowable actions depend on the type of the original form.
• Link to Form Types: Form Types
• Link to Actions: Form Actions

Form Types and Allowable Actions:

• File, Readonly, and Combo types:
• read
• eSign (only if the candidate is part of the signature flow)
• download

• Editable type:
• complete
• eSign (only if the candidate is part of the signature flow)
• download

Steps in Detail

Retrieve formId:

1. Open Postman or any other API client.

2. Make a GET request to the appropriate endpoint: Get Form Collection

3. Identify and note down the id of the desired form from the received forms collection, and use this id as the formId.

Create the Relation:

1. Ensure you have the candidateId for the candidate you want to assign the form to.

2. Combine candidateId, formId, actions, and any additional properties for the candidateForm relation.

API Request to Relate Form:

1. In Postman or any other API client, create a new POST request: Create Candidate Form

2. Set the endpoint to /candidate-forms.

3. In the request body, include the candidateId, formId, actions, and other properties as shown in the example above.

Add Multiple Forms:

• Repeat the POST request for each additional form you need to relate to the candidate.

Example Usage

Request Body for First Form:

{
  "candidateId": "d3ccc75a-7f76-41f8-9ddf-c61622c8e091",
  "formId": "d3ccc75a-7f76-41f8-9ddf-c61622c8e091",
  "actions": [
    "complete",
    "download"
  ],
  "isMandatory": true,
  "isPreliminary": true
}

Request Body for Second Form:

{
  "candidateId": "d3ccc75a-7f76-41f8-9ddf-c61622c8e091",
  "formId": "d3ccc75a-7f76-41f8-9ddf-c61622c8e092",
  "actions": [
    "read",
    "download"
  ],
  "fileId": "d3ccc75a-7f76-41f8-9ddf-c61622c8e092",
  "signatureId": "d3ccc75a-7f76-41f8-9ddf-c61622c8e093"
}

Additional Notes

• Ensure that the parameters candidateId and formId are correctly formatted and valid.

• Do not forget to include actions as it is a required field.

• The allowable actions depend on the form type. Refer to the form type and actions documentation links provided above.

• Use the fileId field if the form type is a file.

• Use the signatureId field if the form requires a signature process, and include the eSign action for the candidate to go through the signature process.

• Set isMandatory to true if the candidate must complete the form.

• Only one form can have isPreliminary set to true to ensure it is displayed first when the candidate opens the filebox.

• You can add as many forms as needed to the candidate entity by repeating the POST request with different formId values.