Background Check

Background-check implementations most often use the Data APIs to retrieve employment records applicants share from their payroll accounts. Start with Identities, then add paystubs or source documents only when the check also requires income evidence.

​

Define the employment request

Decide whether the check requires:

• The applicant’s current employer, prior employers, or both.
• One connected account or multiple accounts covering the required employment history.
• Identity and employment fields only, or supporting paystubs and payroll documents.
• An embedded experience in your applicant portal or an email/SMS invitation.

​

Choose the applicant experience

Create one Argyle user for the applicant and retain the ID. Use external_id for an application or candidate identifier you need to query later. Keep the same user when the applicant returns or connects another employer.

​

Readiness

Use the event that matches the completeness required by the check:

• The accounts.connected webhook confirms that an account connection succeeded, but does not mean employment data is ready.
• The identities.added webhook lets you retrieve an identity as soon as it is created. Continue processing identity updates when fields change.
• The users.fully_synced webhook indicates that initial delivery finished for every newly connected payroll account. Use it when the check must wait for all available employment records.

Track every account separately. An applicant can successfully share one employment source while another account fails or requires action.

​

Retrieve employment records

• Use Identities for employer name, employment status, job title, pay details, and hire or termination dates.
• Use Employments to match identities with supporting paystubs and payroll documents for the same job.
• Add Paystubs and Payroll Documents when the check requires income or source-document support.

Query by user to assemble the applicant’s records, or by account to retrieve records from one connection. An account can contain data from more than one employment. Use the employment filter when you only need records for a specific employment, or retrieve all records and match them afterward to retain unmatched paystubs.

​

Exceptions and fallback

Subscribe to the accounts.failed webhook and the accounts.updated webhook with config.include_resource = true so your system can distinguish an incomplete request from a connection that needs applicant action.

• Let applicants connect another account when employment history spans more than one source.
• Return the existing user to Reconnect an Account when a previously connected account requires action.
• Offer Document Uploads when your process accepts documents after an employer cannot be found or connected.

See Data Delivery and Readiness for the complete synchronization model.