PCRecruiter API
Search... K

Appearance

Change Tracking ​

Description ​

Occasionally there is a need to synchronize some PCRecruiter data. There are two major challenges that this presents:

  • Finding an efficient and reliable way to discover which records changed from one pull to the next.
  • Discovering which records have been deleted from one pull to the next.

This is where Change Tracking comes into play.

By simply adding a special Change Tracking header in an API request, almost all GET API calls will automatically return only records that have been changed since the previous call. Furthermore, you can specify whether you want to see only ADDS, EDITS, or DELETES... or ALL.

If there are DELETED records when ALL is requested, only the record's primary key will be returned, and it will have a minus (-) sign in front of it. This does not mean the primary key value is negative—it signifies that the record was deleted.

Headers ​

There are two headers that you can set to control Change Tracking within API calls:

  1. X-CHANGETRACKING
    This header is used for several functions:

    • Finding the current Change Tracking Version number.
    • Setting the Change Tracking Version automatically from the last pull.
    • Setting the Change Tracking Version manually with a number.

  2. X-CHANGETRACKING-OPERATION
    This header is used to specify which records to return based on whether they were inserted, updated, or deleted (I, U, and D respectively). If this header is omitted, all three types of operations are returned.

TIP

If only Deleted records are requested, the primary key value will NOT have a minus (-) sign in front of it, as there is no need to delineate between deleted and updated records.

Examples ​

Finding the Current Change Tracking Version ​

This API call is to the null endpoint and requests the current Change Tracking Version, which will be returned in an X-CHANGETRACKING header. This number can be used to manually set the Change Tracking Version by simply passing the value into the header on future API calls.

------------------ REQUEST ------------------ ​

GET /rest/api/null
Request header: X-CHANGETRACKING: GET

------------------ RESPONSE ------------------ ​

Response header: X-CHANGETRACKING: 1234567890

TIP

Keep in mind that Change Tracking is usually only retained for up to seven days.

Requesting Records Based on Change Tracking Version ​

This API call is to the candidates endpoint and requests all candidates with the first name "Fred" since Change Tracking Version 1234567890. In this case, two records are returned: one added and one deleted. The X-CHANGETRACKING version number in the response has been incremented by nine, indicating there have been nine database changes since version 1234567890. Only if one of those nine changes includes a deleted candidate record or a modified candidate record with the first name "Fred" will results be returned.

------------------ REQUEST ------------------ ​

GET /rest/api/candidates?query=firstname eq fred&fields=candidateid,firstname
Request header: X-CHANGETRACKING: 1234567890

------------------ RESPONSE ------------------ ​

Response header: X-CHANGETRACKING: 1234567899

Results: [
    {
        "CandidateId": -222222222222222
    },
    {
        "CandidateId": 333333333333333,
        "FirstName": "Fred"
    }
]

TIP

Deleted records skip the query because the field data is gone. Only the primary key will be returned for deleted records.

Automatic Change Tracking Version Handling by Application Name ​

In this example, an application named MyApp is used for automatic Change Tracking Version handling. The API keeps track of the last Change Tracking Version per application and per PCRecruiter user.

  1. Start Command The first request includes the START command after the application name, setting the proper Change Tracking Version while temporarily storing the current Change Tracking Version.

  2. Continuation The second request continues using the same Change Tracking Version.

  3. End Command The third request includes the END command, concluding the data pull. The stored Change Tracking Version is updated to the temporary copy stored during the START command.

------------------ REQUEST 1 ----------------- ​

GET /rest/api/candidates?query=firstname eq fred&fields=candidateid,firstname
Request header: X-CHANGETRACKING: MyApp START
Request header: X-CHANGETRACKING-OPERATION: IU

------------------ RESPONSE 1 ---------------- ​

json
Response header: X-CHANGETRACKING: 1234567899

Results: [
    {
        CandidateId: 333333333333333,
        FirstName: Fred
    },
]

------------------ REQUEST 2 ----------------- ​

GET /rest/api/candidates?query=firstname eq barney&fields=candidateid,firstname
Request header: X-CHANGETRACKING: MyApp
Request header: X-CHANGETRACKING-OPERATION: IU

------------------ RESPONSE 2 ---------------- ​

json
Response header: X-CHANGETRACKING: 1234567899

Results: [
    {
        CandidateId: 444444444444444,
        FirstName: Barney
    },
]

------------------ REQUEST 3 ----------------- ​

GET /rest/api/null
Request header: X-CHANGETRACKING: MyApp STOP

------------------ RESPONSE 3 ---------------- ​

Response header: X-CHANGETRACKING: 1234567899

TIP

The X-CHANGETRACKING-OPERATION header used above includes only Inserts and Updates (IU), omitting Deletes. Appnames must start with a non-numeric character and be a total of 10 alphanumeric characters or less.