d.vinci ATS Application Apply REST API documentation version 1.11

General usage

The d.vinci ATS Application Apply REST API uses JSON as content type for requests and responses with charset UTF-8. The Interface can be activated/deactived for each portal by an admin user of the d.vinci system.

Integration

It is recommended to get the apply URL for each job by calling the "d.vinci ATS Job Publication REST API" first.

{
  "id": 5,
  ...
  "applicationApplyApiURL": "https://myDvinciSystem.dvinci.de/jobs/5/applyApi",
  ...
}

Base Uri

Default portal

https://{customer}.dvinci.de

Custom portal

https://{customer}.dvinci.de/p/{portalName}

Authentication by HTTP Basic Authentication (mandatory)

Requests have to set the Authorization Request Header (see https://www.ietf.org/rfc/rfc2617.txt)

Authorization: Basic YXBpMjI6YXBp

CURL-Examples

curl -i -H "Content-Type: application/json" -H "Authorization: Basic YXBpMjI6YXBp" -X POST -d '{"language":"en","firstName":"John","lastName":"Doe"}' "https://{customer}.dvinci.de/jobs/{jobPublication.id}/applyApi"

curl -i -H "Content-Type: application/json" -H "Authorization: Basic YXBpMjI6YXBp" -X POST -d '{"language":"en","firstName":"John","lastName":"Doe"}' "https://{customer}.dvinci.de/p/{portalName}/jobs/{jobPublication.id}/applyApi"

HTTP Response Codes

200: OK: Everything was fine
401: Unauthorized: Incorrect username and/or password
403: Forbidden: Interface is not enabled for this portal
404: Requested resource not available or portal not exist
422: Unable to process request / internal server error

Changes

Changes for version 1.11

Added property privacyPolicy to /jobs/{id}/applyApi GET request. With this property, its possible to obtain privacy policy texts that are configured in the related questionnaire.
Reminder: Since version 1.8 its possible to submit screening questions answers. The configuration of screening questions is highly dynamical. Its best practice to performe a GET before a POST to /jobs/{id}/applyApi. This is necessary since the POST has to match the configuration represented by the GET request.

Changes for version 1.10

Added new property "partner" for d.vinci partners. With this property, detailed information about the application channel is provided in the system.
- Valid values are: "APPLYZ_TALKNJOB", "PITCHYOU_WHATSAPP" and "STEPSTONE_QUICKAPPLY"

Changes for version 1.9

Added new types for property "screeningQuestions"
- TEXT_4_120: accepts text inputs with minimum of 4 characters and maximum of 120
- TEXTAREA_MAX_1200: accepts text inputs with a maximum of 1200

Changes for version 1.8

Added property "screeningQuestions"
Introduced HTTP method GET to get details for an active job publication

Changes for version 1.7

Added property "hrServiceProviderEmail" that can be used by personnel service providers to add contact email address different from the applicants email address

Changes for version 1.6

Added property "trackingId" for displaying send applications with their current tracking status
A list of trackingIds with their status is available at a new endpoint

Changes for version 1.5

Introduced new salutation "MX" for person and dvinciUser

Changes for version 1.4

Property "sourceId" is no longer a required field

Changes for version 1.3

Added property "externalUseAccepted" for further use of personal data

Changes for version 1.2

Type of "sourceId" has changed from integer to string.
- Id of "sourceId" has been changed to the d.vinci field "Internal Name" of Source

Changes for version 1.1

Type of "degree" has changed from enum to string.
- "degree" can be modified, removed or added by an internal user by web ui in master data menu. All enum names were migrated to internalName for each master data entity.

Submit application

/jobs/{id}/applyApi post get

post

Submit an application on an active job publication.

get

Get an object with details for an active job publication.

Submit an application on an active job publication.

Request
Response

URI Parameters

id: required (number)
id of the job publication

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "trackingId": {
            "type": [
                "string",
                "null"
            ]
        },
        "salutation": {
            "enum": [
                "MR",
                "MS",
                "MX"
            ]
        },
        "title": {
            "type": [
                "string",
                "null"
            ]
        },
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "dateOfBirth": {
            "type": [
                "string",
                "null"
            ]
        },
        "address1": {
            "type": [
                "string",
                "null"
            ]
        },
        "address2": {
            "type": [
                "string",
                "null"
            ]
        },
        "address3": {
            "type": [
                "string",
                "null"
            ]
        },
        "address4": {
            "type": [
                "string",
                "null"
            ]
        },
        "address5": {
            "type": [
                "string",
                "null"
            ]
        },
        "usState": {
            "description": "Iso a2 abbr. of us states",
            "type": [
                "string",
                "null"
            ]
        },
        "zipCode": {
            "type": [
                "string",
                "null"
            ]
        },
        "city": {
            "type": [
                "string",
                "null"
            ]
        },
        "countryIsoA2": {
            "type": [
                "string",
                "null"
            ]
        },
        "email": {
            "type": [
                "string",
                "null"
            ]
        },
        "hrServiceProviderEmail": {
            "type": [
                "string",
                "null"
            ]
        },
        "telephone": {
            "type": [
                "string",
                "null"
            ]
        },
        "alternativeTelephone": {
            "type": [
                "string",
                "null"
            ]
        },
        "skypeName": {
            "type": [
                "string",
                "null"
            ]
        },
        "profileLink": {
            "type": [
                "string",
                "null"
            ]
        },
        "degree": {
            "description": "Only internalNames defined in master data set by internal user are allowed. New systems contains: NO_DEGREE, CERTIFICATE_OF_SECONDARY_EDUCATION, SECONDARY_SCHOOL_LEVEL, BUSINESS_STUDIES, BACCALAUREATE, ASSOCIATE_DEGREE, BACHELOR, MBA, DIPLOMA, MASTER, PROMOTION, OTHERS",
            "type": [
                "string",
                "null"
            ]
        },
        "education": {
            "type": [
                "string",
                "null"
            ]
        },
        "study": {
            "type": [
                "string",
                "null"
            ]
        },
        "lastPosition": {
            "type": [
                "string",
                "null"
            ]
        },
        "photoFile": {
            "description": "bytes encoded in Base64",
            "type": [
                "string",
                "null"
            ]
        },
        "language": {
            "type": "string"
        },
        "comment": {
            "type": [
                "string",
                "null"
            ]
        },
        "earliestStartingDate": {
            "type": [
                "string",
                "null"
            ]
        },
        "desiredSalary": {
            "type": [
                "string",
                "null"
            ]
        },
        "sourceId": {
            "type": [
                "string",
                "null"
            ]
        },
        "desiredLocationIds": {
            "type": "array",
            "items": [
                {
                    "type": "integer"
                }
            ]
        },
        "attachmentFiles": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "fileName": {
                        "type": "string"
                    },
                    "bytesAsBase64": {
                        "description": "bytesAsBase64 should be encoded in Base64",
                        "type": "string"
                    }
                },
                "required": [
                    "fileName",
                    "bytesAsBase64"
                ]
            }
        },
        "extendedUseAccepted": {
            "type": [
                "boolean",
                "null"
            ]
        },
        "screeningQuestions": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "description": "Only internalNames defined in screening question set by internal user are allowed.",
                        "type": "string"
                    },
                    "answer": {
                        "type": "string"
                    },
                    "answers": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "description": "Only internalNames defined in screening question answer set by internal user are allowed.",
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "partner": {
            "type": [
                "string",
                "null"
            ]
        }
    },
    "required": [
        "language",
        "firstName",
        "lastName"
    ]
}

Example:

{
    "trackingId": "TRACKING-ID-1",
    "salutation": "MS",
    "title": "Dr.",
    "firstName": "firstName",
    "lastName": "lastName",
    "dateOfBirth": "1999-07-20",
    "address1": "address line 1",
    "address2": "address line 2",
    "address3": "address line 3",
    "address4": "address line 4",
    "address5": "address line 5",
    "usState": "AK",
    "zipCode": "20097",
    "city": "Hamburg",
    "countryIsoA2": "DE",
    "email": "my.email@address.com",
    "hrServiceProviderEmail": "service.provider.email@address.com",
    "telephone": "+49 (0)40 37479970",
    "alternativeTelephone": "alternativeTelephone",
    "skypeName": "skypeName",
    "profileLink": "https://www.dvinci.de",
    "degree": "BACCALAUREATE",
    "education": "education",
    "study": "MSc Informatics",
    "lastPosition": "Last position of applicant",
    "photoFile": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
    "language": "en",
    "comment": "This is a comment field.\nWith multi lines.",
    "earliestStartingDate": "In 3 months",
    "desiredSalary": "1.000€ / month",
    "sourceId": "HOMEPAGE",
    "partner": "STEPSTONE_QUICKAPPLY",
    "desiredLocationIds": [1, 2],
    "attachmentFiles": [
        {
            "fileName": "cv.pdf",
            "bytesAsBase64": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="
        },
        {
            "fileName": "certificate.doc",
            "bytesAsBase64": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs="
        }
    ],
    "extendedUseAccepted": true,
    "screeningQuestions": [
        {
            "id": "GRAILS",
            "answer": "4"
        },
        {
            "id": "OFFICE_SKILLS_MULTI",
            "answers": [
                {
                    "id": "OFFICE_SKILLS_MULTI_CHOICE_0"
                },
                {
                    "id": "OFFICE_SKILLS_MULTI_CHOICE_2"
                }
            ]
        },
        {
            "id": "MOTIVATION",
            "answer": "My motivation ..."
        },
        {
            "id": "EU_CITIZEN",
            "answer": "0"
        },
        {
            "id": "SEVERELY_DISABLED",
            "answer": "NOT_SPECIFIED"
        },
        {
            "id": "RELIGION",
            "answer": "My religion ..."
        },
        {
            "id": "PROFESSION",
            "answer": "My Profession ..."
        },
        {
            "id": "ABSTRACT",
            "answer": "My Introduction to Myself ..."
        }
    ]
}

HTTP status code 200

Application was saved

Body

Type: application/json

Example:

{"success":true}

HTTP status code 401

Authentification failed - Incorrect username and/or password.

HTTP status code 403

Apply interface is not enabled for this portal.

HTTP status code 404

The job publication is not available for submitting

Body

Type: application/json

Example:

{"errorMsg":"The requested publication is no longer available."}

HTTP status code 422

This error is caused by validation errors of the given data

mandatory: The property is mandatory
typeMismatch: The given value does not match the required format
maxSize: The string has exceeded the maximal allowed size
maxSize.exceeded: The string has exceeded the maximal allowed size
email.invalid: The string is not a valid email
valueNotPermitted: The given value is not accessible
dateInFuture: The given date can not be in future
dateTooEarly: The given date is too early
invalidPhoto: The submitted photo is not valid
invalidFile: The submitted file is not valid
fileSize: The submitted file is not valid
invalidSkypeName: The string is not a valid skype name

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "fieldErrors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "allowed": {
                        "type": "string"
                    },
                    "notAllowed": {
                        "type": "string"
                    },
                    "field": {
                        "type": "string"
                    },
                    "code": {
                        "type": "string"
                    }
                },
                "required": [
                    "field",
                    "code"
                ]
            }
        },
        "errorMsg": {
            "type": "string"
        }
    },
    "required": [
        "errorMsg"
    ]
}

Example:

{
    "fieldErrors": [
        {
            "field": "lastName",
            "code": "mandatory"
        },
        {
            "field": "sourceId",
            "code": "typeMismatch"
        },
        {
            "allowed": "255",
            "field": "firstName",
            "code": "maxSize.exceeded"
        },
        {
            "allowed": "255",
            "field": "lastName",
            "code": "maxSize.exceeded"
        },
        {
            "field": "email",
            "code": "email.invalid"
        },
        {
            "field": "dateOfBirth",
            "code": "dateInFuture"
        },
        {
            "field": "dateOfBirth",
            "code": "dateTooEarly"
        },
        {
            "field": "sourceId",
            "code": "valueNotPermitted"
        },
        {
            "field": "countryIsoA2",
            "code": "maxSize"
        },
        {
            "field": "photoFile",
            "code": "invalidPhoto"
        },
        {
            "field": "attachmentFiles.0.fileName",
            "code": "mandatory"
        },
        {
            "field": "attachmentFiles.0.bytesAsBase64",
            "code": "invalidFile"
        },
        {
            "field": "attachmentFiles.0.bytesAsBase64",
            "code": "fileSize"
        },
        {
            "field": "screeningQuestions",
            "code": "invalidAnswers: [screeningQuestion.INTERNAL_NAME: 'value', code: *]"
        },
        {
            "field": "partner",
            "code": "valueNotPermitted"
        }
    ],
    "errorMsg": "Entity not valid"
}

Get an object with details for an active job publication.

Request
Response

URI Parameters

id: required (number)
id of the job publication

HTTP status code 200

Object with details for an active job publication.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "screeningQuestions": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "question": {
                        "type": "string"
                    },
                    "mandatory": {
                        "type": [
                            "boolean",
                            "null"
                        ]
                    },
                    "type": {
                        "enum": [
                            "TEXT",
                            "TEXT_4_120",
                            "TEXTAREA",
                            "TEXTAREA_MAX_1200",
                            "FIVE_STAR_RATING",
                            "YES_NO",
                            "YES_NO_NOT_SPECIFIED",
                            "SINGLE_CHOICE",
                            "MULTI_CHOICE"
                        ]
                    },
                    "choices": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "answer": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "privacyPolicy": {
            "type": "object",
            "headline": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "body": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "additional": {
                "type": [
                    "string",
                    "null"
                ]
            }
        }
    }
}

Example:

{
    "screeningQuestions": [
        {
            "id": "GRAILS",
            "question": "Grails",
            "mandatory": true,
            "type": "FIVE_STAR_RATING",
            "choices": []
        },
        {
            "id": "OFFICE_SKILLS_MULTI",
            "question": "MS-Office-Kenntnisse",
            "mandatory": true,
            "type": "MULTI_CHOICE",
            "choices": [
                {
                    "id": "OFFICE_SKILLS_MULTI_CHOICE_0",
                    "answer": "Word"
                },
                {
                    "id": "OFFICE_SKILLS_MULTI_CHOICE_1",
                    "answer": "Excel"
                },
                {
                    "id": "OFFICE_SKILLS_MULTI_CHOICE_2",
                    "answer": "Access"
                }
            ]
        },
        {
            "id": "MOTIVATION",
            "question": "Motivation",
            "mandatory": true,
            "type": "TEXTAREA",
            "choices": []
        },
        {
            "id": "EU_CITIZEN",
            "question": "EU-Bürger?",
            "mandatory": false,
            "type": "YES_NO",
            "choices": []
        },
        {
            "id": "SEVERELY_DISABLED",
            "question": "Haben Sie eine Schwerbehinderung?",
            "mandatory": false,
            "type": "YES_NO_NOT_SPECIFIED",
            "choices": []
        },
        {
            "id": "MATH_SINGLE",
            "question": "Mathematik Note",
            "mandatory": false,
            "type": "SINGLE_CHOICE",
            "choices": [
                {
                    "id": "MATH_SINGLE_CHOICE_0",
                    "answer": "1"
                },
                {
                    "id": "MATH_SINGLE_CHOICE_1",
                    "answer": "2"
                },
                {
                    "id": "MATH_SINGLE_CHOICE_2",
                    "answer": "3"
                },
                {
                    "id": "MATH_SINGLE_CHOICE_3",
                    "answer": "4"
                },
                {
                    "id": "MATH_SINGLE_CHOICE_4",
                    "answer": "5"
                },
                {
                    "id": "MATH_SINGLE_CHOICE_5",
                    "answer": "6"
                }
            ]
        },
        {
            "id": "RELIGION",
            "question": "Religion",
            "mandatory": true,
            "type": "TEXT",
            "choices": []
        },
        {
            "id": "PROFESSION",
            "question": "Profession",
            "mandatory": true,
            "type": "TEXT_4_120",
            "choices": []
        },
        {
            "id": "ABSTRACT",
            "question": "Abstract",
            "mandatory": true,
            "type": "TEXTAREA_MAX_1200",
            "choices": []
        }
    ],
    "privacyPolicy": {
        "headline": "Einwilligung zum Datenschutz",
        "body": "Hier steht der eingetragene Datenschutztext.",
        "additional": "Ich habe die Datenschutzerklärung zur Kenntnis genommen und stimme der Verarbeitung zu."
    }
}

HTTP status code 401

Authentification failed - Incorrect username and/or password.

HTTP status code 403

Apply interface is not enabled for this portal.

Show tracked applications

/applications/tracking get

get

Show all applications with prior set trackingId, showing this trackingId and the current trackingStatus when set.

Request
Response

Query Parameters

lastStatusChangeDateOffset: (integer - default: 86400)
The list of tracked applications can be retrieved with a filter. The query parameter "lastStatusChangeDateOffset" defines when the last status change for tracked applications was and shows only applications within the given period. It must be a number and equals or less than '2147483647'.
Example:
```
* lastStatusChangeDateOffset=3600
* lastStatusChangeDateOffset=86400
```

HTTP status code 200

Tracked applications

Body

Type: application/json

Example:

[
  {
    "trackingId": "TRACKING-ID-1",
    "trackingStatus": "HIRED"
  },
  {
    "trackingId": "TRACKING-ID-2",
    "trackingStatus": null
  },
  {
    "trackingId": "TRACKING-ID-3",
    "trackingStatus": "REJECTED"
  }
]

HTTP status code 401

Authentification failed - Incorrect username and/or password.

HTTP status code 403

Interface is not enabled for this portal.

HTTP status code 422

This error is caused by REST call communication problems.

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errorMsg": {
      "type": "string"
    }
  },
  "required": [
    "errorMsg"
  ]
}

Example:

{
  "errorMsg": "An error has occurred when querying application tracking ids."
}

d.vinci ATS Application Apply REST API documentation version 1.11

Submit application

post /jobs/{id}/applyApi

URI Parameters

Body

HTTP status code 200

Body

HTTP status code 401

HTTP status code 403

HTTP status code 404

Body

HTTP status code 422

Body

get /jobs/{id}/applyApi

URI Parameters

HTTP status code 200

Body

HTTP status code 401

HTTP status code 403

Show tracked applications

get /applications/tracking

Query Parameters

HTTP status code 200

Body

HTTP status code 401

HTTP status code 403

HTTP status code 422

Body