Skip to main content

People API - Overview

The People API is an API Subscription that enables Employee and Assignment information to be exchanged between AssignmentPro and other systems. In addition to Employee and Assignment, Dependents, Spou

Updated over 2 weeks ago

The People API is an API Subscription that enables Employee and Assignment information to be exchanged between AssignmentPro and other systems. In addition to Employee and Assignment, Dependents, Spouse/Domestic Partners and Initiations can also be created.

Note - assignments created with API requests will decrement relevant click counters and licensing modules.

Use of this feature requires the following:

  • Client's webserver configured to use the API - please contact your Equus representative. Configuration is completed by the Equus Development Team.

  • In AssignmentPro, create an API subscriber with a subscription to the People API (select People from the list of available API Subscriptions) and generate GUID and Secret Key for the API subscriber.

The People API Subscription grants Subscribers access to interact with the following objects within AssignmentPro:

Assignment

  • Requires an Employee ID to create

  • Can be created with POST requests, updated with PATCH requests (requires the ID of the Assignment from Equus Platform), or retrieved with a GET request

  • When using the API to create Assignments that should fall into specific Company Segment levels, the API can accept either the Name or the Client Code for the Segment. There is no need to use an Equus Platform specific ID

  • Custom fields via nested objects inside of the main object's attributes

Assignment Compensation Bonus

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Compensation Bonus to be updated)

  • Assignments can have many Compensation Bonus records, but a Compensation Bonus record can only belong to one Assignment

  • Custom fields via nested objects inside of the main object's attributes

Assignment Compensation Policy

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests. PATCH requests require the ID of the Compensation Policy to be updated

  • Assignments can only have one Compensation Policy record, and Compensation Policy records can only belong to one Assignment

  • Custom fields via nested objects inside of the main object's attributes

Assignment Compensation Salary

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of Salary record that should be updated)

  • Assignments can have many Compensation Salary records, but a Compensation Salary record can only belong to one Assignment

  • Custom fields via nested objects inside of the main object's attributes

Assignment Cost Center

  • Requires an Assignment ID to create or update

  • Custom fields via nested objects inside of the main object's attributes

Assignment Dependent

  • Requires an Assignment ID to create

  • Can be created with POST requests, updated with PATCH requests (requires the ID of the Assignment Dependent from AssignmentPro), or retrieved with a GET request

  • Assignments can have more than one Assignment Dependent

  • Custom fields via nested objects inside of the main object's attributes

Assignment Employee Contact

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Employee Contact record to be updated)

  • Assignments can have many Employee Contact records, but an Employee Contact record can only belong to one Assignment

Assignment Family Size

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Family Size record that should be updated)

  • Assignments can have many Family Size records, but a Family Size record can only belong to one Assignment

Assignment Mailing Address

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Mailing Address record to be updated)

  • Assignments can have many Mailing Address records, but a Mailing Address record can only belong to one Assignment

  • Custom fields via nested objects inside of the main object's attributes

Assignment Package

  • Requires an Assignment Configuration ID and Assignment ID to create

  • Can be created with POST requests

  • Providing the description and effective date for the Assignment Package is optional. If an effective date is not provided, the current date will be used for the request.

  • Enqueues an assignment package for an existing active assignment using the assignment package configuration specified in the request relationships

Assignment Visa

  • Requires an Assignment ID

  • Can only be retrieved with a GET request

  • Assignments can have many Visa records, but a Visa record can only belong to one Assignment

Assignment Visa Rule

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Assignment Visa record to be updated)

  • Assignments can have one Assignment Visa Rule record, and an Assignment Visa Rule record can only belong to one Assignment

  • The only available data elements involved the Job Description field

Company Segment

  • Can only be retrieved with a GET request

Compensation Data Repository

  • Requires an Assignment ID to create

  • Can be created with POST requests, updated with PATCH requests or deleted with DELETE requests

  • Assignments can have many Compensation Data Repository records, but a Compensation Data Repository record can only belong to one Assignment

  • Custom fields via nested objects inside of the main object's attributes

Employee

  • Requires a Company ID

  • Can be created with POST requests, updated with PATCH requests (requires the ID of the Employee from AssignmentPro), or retrieved with a GET request

  • Can have more than one Assignment

  • There is special logic built into this endpoint to prevent the creation of duplicate Employees with the API:

    • The Employee endpoint has special logic to prevent the creation of duplicate Employees, and will check the Employee System Number for matches against existing records, then a combination of First Name, Last Name, Gender and Email address if the first check results in no matching Employees

    • If Employees are found that meet either of the above criteria sets, the API will then provide an error response that informs the API Consumer which criteria matched, as well as possible employee matches

    • Custom fields via nested objects inside of the main object's attributes

Employee Passport

  • Requires a Employee ID to create or update

  • Can be created with POST requests, updated with PATCH requests (requires the relationship with the Employee), or retrieved with a GET request

  • Supports single and multiple records creation or update

Relocation Screen Contact

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Relocation Screen Contact record to be updated)

  • Assignments can have one Relocation Screen Contact per Contact Type

  • Custom fields via nested objects inside of the main object's attributes

Spouse/Domestic Partner

  • Requires an Assignment ID to create

  • Can be created with POST requests, updated with PATCH requests (requires the ID of the Spouse/Domestic Partner from AssignmentPro), or retrieved with a GET request

  • Assignments can only have one Spouse/Domestic Partner

  • Custom fields via nested objects inside of the main object's attributes

Training

  • Requires an Assignment ID to create or update

  • Can be created with POST requests, or updated with PATCH requests (requires the ID of the Training record to be updated)

  • Custom fields via nested objects inside of the main object's attributes

The IDs listed above are the fundamental links between each of the objects. Generally speaking, there are more required fields for the specific requests above and error messages will be returned pointing other systems to which fields are missing.

An example of using the People API could look something like this:

  1. External system makes a GET request to the Employee endpoint. When there is no ID specified in the request URL, then all Employees are returned. This way, the external system has a comprehensive list of all Employees that currently exist within AssignmentPro

  2. To create a new Employee, a POST request is made against the Employee endpoint

    • Details about what the JSON request looks like can be found in Swagger

  3. Once the Employee is successfully created, external system stores the ID AssignmentPro has assigned for them

  4. To create a new Assignment for the created employee, a POST request is made against the Assignment endpoint

    • Details about what the JSON request looks like can be found in Swagger

  5. Once the Assignment is successfully created, external system stores the ID AssignmentPro has created for it

  6. If applicable, Assignment Dependents can be added with a POST request to the Assignment Dependent endpoint

  7. If applicable, Spouse/Domestic Partner can be added with a POST request to the Spouse Domestic Partner endpoint

  8. Updates to any of the above can be made with PATCH requests to the applicable endpoints now that an ID has been established for them in AssignmentPro

  9. Optionally, the external system can receive updates about any of the above by creating and subscribing to Webhooks.

Things to Note

  • It is advisable to consult the Swagger documentation when using the API

  • Certain fields have been excluded from the Permission Set that backs the Subscription and should not be added back in

  • SOURCE_SYSTEM_TEXT_KEY can be used to store a user’s external ID

  • From 21.6 SOURCE_SYSTEM_TEXT_KEY & SOURCE_SYSTEM fields are now supported on all tables including:

    • ASSIGNMENT_COMPENSATION_BONUS

    • ASSIGNMENT_COMPENSATION_POLICY

    • ASSIGNMENT_COMPENSATION_SALARY

    • ASSIGNMENT_DEPENDENT

    • ASSIGNMENT_EMPLOYEE_CONTACT

    • ASSIGNMENT_VISA_RULE

    • RELOCATION_SCREEN_CONTACT

    • EMPLOYEE_PASSPORT

    • TRAINING

  • If you make a POST or PATCH request and have a source system text key in the payload, source system will also be required.

  • The Search endpoint for SOURCE_SYSTEM_TEXT_KEY can be used for any People API table. (see Swagger Documentation for more info.)

  • Assignment Packages that have been processed from a POST request may contain errors. It is recommended to configure a quick workflow with a webhook containing Assignment Package status information.

  • A POST request can be sent to the batch endpoint to create multiple Assignment records. Note that this will not affect individual click counters. For more information on Batch License Use and the click counter reconciliation process, please contact your Equus representative.

Related Articles
Cost Estimates API - Overview
AssignmentPro API - Custom Fields
AssignmentPro API - Viewing API Event History
Documents API - Assignment Documents
People API - How to search for Assignments and Employees based on alternate identifiers
Did this answer your question?